help mata Elabel_Utilities()

Title

Elabel_Utilities() -- Utility tools for elabel (class)

Syntax

class Elabel_Utilities scalar u

void
u.u_assert0([string scalar where])

(varies)
u.u_assert_lblname(string rowvector namelist[,
real scalar err])

(varies)
u.u_assert_name(string rowvector namelist[,
real scalar err])

(varies)
u.u_assert_newfile(string scalar fn,
real scalar replace[,
real scalar err])

(varies)
u.u_assert_newlblname(string rowvector namelist[,
real scalar err])

(varies)
u.u_assert_nosysmiss(real vector v[,
real scalar err])

(varies)
u.u_assert_uniq(string rowvector list[,
transmorphic scalar arg])

string matrix
u.u_bslsq(string matrix s)

void
u.u_err_alreadydefined(string scalar item[,
string scalar what])

void
u.u_err_expected(string scalar expected[,
string scalar found])

void
u.u_err_fewmany(real scalar fewmany,
string scalar what)

void
u.u_err_notallowed(string scalar item[,
string scalar what])

void
u.u_err_notfound(string scalar item[,
string scalar what])

void
u.u_err_numlist([real scalar rc,
string scalar nlist])

void
u.u_err_required(string scalar item,
string scalar what)

void
u.u_err_unbalanced(string scalar par)

void
u.u_exerr(real scalar rc,
string scalar msg[, string scalar arg])

void
u.u_fput(real scalar fh,
string scalar s)

string scalar
u.u_get_varlabel(scalar var,
string scalar lang)

string scalar
u.u_get_varvaluelabel(scalar var,
string scalar lang)

string scalar
u.u_invtoken(string rowvector s)

real scalar
u.u_iseexp(string scalar s[,
r1])

real scalar
u.u_isgmappings(string scalar s[,
r1, r2])

real scalar
u.u_ispfcn(string scalar s,
r1, r2[, r3])

transmorphic
u.u_selectnm(transmorphic vector x[,
real scalar asvec])

void
u.u_st_exe(string scalar cmd[,
real scalar nooutput])

void
u.u_swap_valuelabel(string rowvector oldnames,
string rowvector newnames)

void
u.u_st_syntax(string scalar 0[,
string scalar dos, rc])

string scalar
u.u_strip_wildcards(string scalar s[,
haswc])

string rowvector
u.u_st_numvarlist(string scalar s)

string scalar
u.u_tokenget_inpar(t[,
real scalar pars, rc])

string rowvector
u.u_tokensq(string scalar s)

real scalar
u.u_unabbr(string scalar abbr,
string scalar full)

Description

Elabel_Utilities() returns instances of
class Elabel_Utilities. The class is used for developing
the elabel package.

u.u_assert0() displays
elabel unexpected error[ in where] and exists
with return code 42.

u.u_assert_lblname() issues a Stata error message if any
of the value labels in namelist is not defined in memory or if
any of namelist is an invalid name. If err==0, the function
never exists with error but returns whether the assertion is true (==1)
or false (==0).

u.u_assert_name() issues a Stata error message if any of
namelist is not a valid name. If err==0, the function never
exists with error but returns whether the assertion is true (==1) or
false (==0).

u.u_assert_newfile() issues a Stata error message if fn
exists and replace==0; if replace==1 and fn does not exist,
the function prints a notification. If err==0, the function executes
quietly, never exists with error, and returns whether the assertion is
true (==1) or false (==0).

u.u_assert_newlblname() issues a Stata error message if
any of namelist is an already defined value label or if any of
namelist is an invalid name. If err==0, the function never
exists with error but returns whether the assertion is true (==1) or
false (==0).

u.u_assert_nosysmiss() issues the Stata error message
may not label . and exist with return code 180 if v
contains system missing values. If err==0, the function
never exists with error but returns whether the assertion is true
(==1) or false (==0).

u.u_assert_uniq() does nothing if list has no duplicate
elements. In list, any columns containing null string ("") or
only white spaces (" ") are ignored. If list has duplicate
elements, and if arg is string scalar, the functions issues the
Stata error message arg first_duplicate mentioned more than once
and exists with return code 110; if arg is not specified the function
exists with return code 198. If arg==0, the function never exists with
error but returns whether the assertion is true (==1) or false (==0).

u.u_bslsq() returns s with all single left quotes (`)
prefixed with a backslash; the function replaces ` with \`.

u.u_err_alreadydefined() issues the error message
what item already defined and exists with return code 110;
what defaults to value label.

u.u_err_expected() issues the error message
'found' where expected expected and exits with
return code 198.

u.u_err_fewmany() does nothing if fewmany==0 and issues
the error message too what specified otherwise; if
fewmany<0 the word few is used; if fewmany>0 the word
many is used.

u.u_err_notallowed() does nothing if item=="". Otherwise,
the function issues the error message {what|item} not allowed
and exists with return code 101.

u.u_err_notfound() issues the error message
what item not found and exists with return code 111;
what defaults to value label.

u.u_err_numlist() issues the error message
nlist -- invalid numlist followed by the full error
message specific to rc; the latter defaults to 121.

u.u_err_required() does nothing if item!="". Otherwise,
the functions issues the error message what required and exists
with return code 100.

u.u_err_unbalanced() issues the error message
unmatched parenthesis and exists with return code 132;
if par=( the word open is used; if par=) the word
close is used. The function exists with error and produces a Mata
traceback log if par is not one of ( or ).

u.u_exerr() issues the specified error message (msg)
just like errprintf() but with a maximum of one
argument, arg; the function exits with the specified return code
(rc).

u.u_fput() is a wrapper for fput(); if an
error occurs, the function closes fh and exits with a Stata error
code.

u.u_get_varlabel() returns the variable label of var in
label language lang, where lang is not the current label
language. var may be of type string or real and specifies a
variable name or variable index. The function returns "" if var
has no variable label in lang, if lang is the current label
language, or if lang is not a label language. Omitting lang or
lang="" returns the variable label of var in the current
label language. If var is not string or real, or if
1>var>st_nvar(), the function produces a Mata
traceback log.

u.u_get_varvaluelabel() returns the value label name that
is attached to var in label language lang, where lang is not
the current label language. var may be of type string or real
and specifies a variable name or variable index. The function returns ""
if varid has no value label attached in lang, if lang is the
current label language, or if lang is not a label language. Omitting
lang or lang="" returns the value label name that is attached
to var in the current label language. If var is not string or
real, or if 1>var>st_nvar(), the function
produces a Mata traceback log.

u.u_invtoken() returns the elements of s
concatenated into a string scalar. The function returns
"" if s=J(0, 0, ""); otherwise it returns
invtokens(u_selectnm(s)) (see below).

u.u_iseexp() returns 1 if s is = ... and
returns 0 otherwise. If the function returns 1, r1 is replaced
with a string scalar containing everything that follows the
equals sign.

u.u_isgmappings() returns 1 if s is
(...)(...) and returns 0 otherwise. If
the function returns 1, r1 is replaced with a string scalar
containing the contents found within the first pair of parentheses;
r2 is replaced with the contents found in the second pair of
parentheses.

u.u_ispfcn() returns 1 if s is
= fcn(...)[...] and if
elabel_fcn_fcn is a program in memory or stored as an
ado-file; r1 is replaced with a string scalar containing
fcn and r2 contains ..., i.e., whatever
follows the open parenthesis with the matching close parenthesis
removed. If r3 is specified, r2 contains only the contents
enclosed in parentheses, but not the parentheses; r3 contains
whatever follows the close parenthesis. The function returns 0 if s
does not have the expected form. If s has the expected form but
elabel_fcn_fcn is not found, the function exists with the
respective error message and return code 133. If s has the expected
form and elabel_fcn_fcn is found but r3 is not any of
{iff|if|in|,...}, the function exits with
an error message and sets the return code to 198.

u.u_selectnm() selects the non-missing elements from x. If
x=J(r, 0, val), the function returns
J(1, 0, missingof(x)); if x=J(0, c,
val), the function returns J(0, 1, missingof(x));
if asvec==0 and if x==missingof(x), the function
returns x. Typical usage is
invtokens(u_selectnm(x, 0)) to avoid conformability errors.

u.u_swap_valuelabel() detaches value labels oldnames from
variables and attaches value labels newnames to variables. oldnames
and newnames must have the same length and correspond one-to-one. Also,
oldnames must be unique. Note that the function does not perfrom any
checks and always produces a Mata traceback log on errors.

u.u_st_exe() is a convenience function; the code is:
if ( rc=_stata(cmd, nooutput) ) exit(rc).

u.u_st_syntax() puts 0 into Stata local 0 and
executes syntax with dos (description_of_syntax). The
type of capture is irrelevant and it is replaced with a
real scalar containing the Stata return code. If capture is
specified, any output form syntax is suppressed.

u.u_strip_wildcards() returns s with all * and
~ removed, and all ? changed to _. If specified,
haswc is replaced with a real scalar indicating whether
name contains any wildcard characters.

u.u_st_numvarlist() calls
u.u_st_syntax(s, "varlist(numeric)") and returns
the expanded varlist from Stata. If there are string variables in
varlist, the function exits with error
r(181); if there is another problem, the function
exits with the respective error message.

u.u_tokenget_inpar() expectes a parsing environment obtained
from tokeninit(). The function obtains from t the
next token defined as everything enclosed in parentheses, including the
parentheses themselves. The string in t is expected to be of the
form (...)[...] and if it is not, the function
exists with error, unless rc is specified. More specifically, if
rc is not specified, the function produces a Mata traceback log if
the string in t does not start with an open parenthesis. The function
issues an unbalanced parenthesis error if parentheses are unbalanced. If
rc is specified, the function does not exit with error; it replaces
rc with 0 if there is no problem, with 132 if there is an unmatched
open parenthesis and with -132 if the string in t does not start with
an open parenthesis. If par=0, the returned token is not enclosed in
parentheses.

u.u_tokensq() returns the tokens in s, preserving (nested)
double quotes.

u.u_unabbr() returns whether abbr===full; full
is minimal_abbreviation:rest.

Conformability

As indicated above.

Diagnostics

Not documented; class functions are for internal use.

Source code

Distributed with the elabel package.

Author

Daniel Klein

University of Kassel

klein.daniel.81@gmail.com

Also see

Online: mata

if installed: elabel