help mata elabel_u_*()

Title

mata elabel_u_*() -- elabel utility functions

Syntax

(varies)
elabel_u_assert_lblname(string rowvector namelist[,
real scalar err])

(varies)
elabel_u_assert_name(string rowvector namelist[,
real scalar err])

(varies)
elabel_u_assert_newlblname(string rowvector namelist[,
real scalar err])

(varies)
elabel_u_assert_uniq(string rowvector list[,
transmorphic scalar arg])

colvector
elabel_u_eexp(string scalar eexp,
real colvector hash, string colvector at)

string scalar
elabel_u_get_varlabel(transmorphic scalar var,
string scalar lang)

string scalar
elabel_u_get_varvaluelabel(transmorphic scalar var,
string scalar lang)

real scalar
elabel_u_iseexp(string scalar s,
r1)

real scalar
elabel_u_isgmappings(string scalar s,
r1, r2)

void
elabel_u_parse_rules(string scalar rules,
from,
to,
text[,
null,
recode_rules])

void
elabel_u_st_syntax(string scalar 0[,
string scalar descr_of_syntax,
capture])

void
elabel_u_swap_valuelabel(string colvector oldnames,
string colvector newnames)

string scalar
elabel_u_tokenget_inpar(t[,
real scalar pars, rc])

string rowvector
elabel_u_tokensq(string scalar s)

string rowvector
elabel_u_usedby(string rowvector lblnamelist[,
real scalar mlang])

Description

These functions are primarily used for developing the elabel
package but might be of interest to programmers.

elabel_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 exits with error but returns whether the assertion is true (==1)
or false (==0).

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

elabel_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
exits with error but returns whether the assertion is true (==1) or
false (==0).

elabel_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 exits with return code 110; if arg is not specified the function
exits with return code 198. If arg==0, the function never exits with
error but returns whether the assertion is true (==1) or false (==0).

elabel_u_eexp() returns eexp with all # characters
replaced with hash and all @ characters replaced with
at. If Stata cannot evaluate eexp, the function exits with
the respective Stata error message.

elabel_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.

elabel_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.

elabel_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.

elabel_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.

elabel_u_parse_rules() parses rules of the form
(from_numlist = to_numlist
["label" [...]]) ..., and returns the
respective elements. If null is specified, it contains information
whether elements of text are null strings. If recode_rules is
specified, it is filled with (#=#) ...,
i.e., rules in a format that can be passed to the recode
command. The function exist with Stata error messages if rules are
invalid.

elabel_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 from syntax is suppressed.

elabel_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.

elabel_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
exits 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.

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

elabel_u_usedby() returns a rowvector of variable names that have one
of the value labels in lblnamelist attached (in any label language). If
mlang=0, only the current label language is considered. lblnamelist
may contain non-existing value label names; actually, lblnamelist may
contain any string. If lblnamelist contains "", the function
returns all (numeric) variabels that do not have a value label attached. The
returned variable names are unique.

Conformability

As indicated above.

Diagnostics

Not documented; 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