**[FN] Programming functions**

__Functions__

**autocode(***x***,***n***,***x0***,***x1***)**
Description: partitions the interval from *x0* to *x1* into *n*
equal-length intervals and returns the upper bound of
the interval that contains *x*

This function is an automated version of **recode()**. See
**[U] 25 Working with categorical data and factor**
**variables** for an example.
Domain *x*: -8e+307 to 8e+307
Domain *n*: integers 1 to 8e+307
Domain *x0*: -8e+307 to 8e+307
Domain *x1*: *x0* to 8e+307
Range: *x0* to *x1*

**byteorder()**
Description: **1** if your computer stores numbers by using a hilo byte
order and evaluates to **2** if your computer stores numbers
by using a lohi byte order

Consider the number 1 written as a 2-byte integer. On
some computers (called hilo), it is written as "00 01",
and on other computers (called lohi), it is written as
"01 00" (with the least significant byte written first).
There are similar issues for 4-byte integers, 4-byte
floats, and 8-byte floats. Stata automatically handles
byte-order differences for Stata-created files. Users
need not be concerned about this issue. Programmers
producing custom binary files can use **byteorder()** to
determine the native byte ordering; see **[P] file**.
Range: 1 and 2

**c(***name***)**
Description: the value of the system or constant result **c(***name***)**
See **[P] creturn**. Referencing **c(***name***)** will return an
error if the result does not exist.
Domain: names
Range: real values, strings, or *missing*

**_caller()**
Description: **version** of the program or session that invoked the
currently running program; see **[P] version**
The current version at the time of this writing is 15.1,
so 15.1 is the upper end of this range. If Stata 15.2
were the current version, 15.2 would be the upper end of
this range, and likewise, if Stata 16 were the current
version, 16 would be the upper end of this range. This
is a function for use by programmers.
Range: 1 to 15.1

**chop(***x***,***tol***)**
Description: **round(***x***)** if **abs(***x***-round(***x***))** < *tol*; otherwise, *x*; or *x* if
*x* is missing
Domain *x*: -8e+307 to 8e+307
Domain *tol*: -8e+307 to 8e+307
Range: -8e+307 to 8e+307

**clip(***x***,***a***,***b***)**
Description: *x* if *a* < *x* < *b*, *b* if *x* __>__ *b*, *a* if *x* __<__ *a*, or *missing* if *x*
is missing or if *a* > *b*; *x* if *x* is missing

If *a* or *b* is missing, this is interpreted as *a* = -inf or
*b* = +inf, respectively.
Domain *x*: -8e+307 to 8e+307
Domain *a*: -8e+307 to 8e+307
Domain *b*: -8e+307 to 8e+307
Range: -8e+307 to 8e+307

**cond(***x***,***a***,***b*[**,***c*]**)**
Description: *a* if *x* is true and nonmissing, *b* if *x* is false, and *c* if
*x* is *missing*; *a* if *c* is not specified and *x* evaluates to
*missing*

Note that expressions such as *x*>2 will never evaluate to
*missing*.

**cond(x>2,50,70)** returns **50** if **x** > **2** (includes **x** __>__ **.**)
**cond(x>2,50,70)** returns **70** if **x** __<__ **2**

If you need a case for missing values in the above
examples, try

**cond(missing(x), ., cond(x>2,50,70))** returns **.** if **x** is
*missing*, returns **50** if **x** > **2**, and returns **70** if **x** __<__ **2**

If the first argument is a scalar that may contain a
missing value or a variable containing missing values,
the fourth argument has an effect.

**cond(wage,1,0,.)** returns **1** if **wage** is not zero and not
missing
**cond(wage,1,0,.)** returns **0** if **wage** is zero
**cond(wage,1,0,.)** returns **.** if **wage** is *missing*

Caution: If the first argument to **cond()** is a logical
expression, that is, **cond(x>2,50,70,.)**, the fourth
argument is never reached.
Domain *x*: -8e+307 to 8e+307 or *missing*; 0 means false, otherwise
interpreted as true
Domain *a*: numbers and strings
Domain *b*: numbers if *a* is a number; strings if *a* is a string
Domain *c*: numbers if *a* is a number; strings if *a* is a string
Range: *a*, *b*, and *c*

**e(***name***)**
Description: the value of stored result **e(***name***)**; see **[U] 18.8**
**Accessing results calculated by other programs**

**e(***name***)** = scalar missing if the stored result does not
exist
**e(***name***)** = specified matrix if the stored result is a
matrix
**e(***name***)** = scalar numeric value if the stored result is a
scalar
Domain: names
Range: strings, scalars, matrices, or *missing*

**e(sample)**
Description: **1** if the observation is in the estimation sample and **0**
otherwise
Range: 0 to 1

**epsdouble()**
Description: the machine precision of a double-precision number
If *d* < **epsdouble()** and (double) *x* = 1, then *x* + *d* =
(double) 1. This function takes no arguments, but the
parentheses must be included.
Range: a double-precision number close to 0

**epsfloat()**
Description: the machine precision of a floating-point number

If *d* < **epsfloat()** and (float) *x* = 1, then *x* + *d* =
(float) 1. This function takes no arguments, but the
parentheses must be included.
Range: a floating-point number close to 0

**fileexists(***f***)**
Description: **1** if the file specified by *f* exists; otherwise, **0**

If the file exists but is not readable, **fileexists()**
will still return **1**, because it does exist. If the
"file" is a directory, **fileexists()** will return **0**.
Domain: filenames
Range: 0 and 1

**fileread(***f***)**
Description: the contents of the file specified by *f*

If the file does not exist or an I/O error occurs while
reading the file, then "**fileread() error** *#*" is returned,
where *#* is a standard Stata error return code.
Domain: filenames
Range: strings

**filereaderror(***s***)**
Description: **0** or positive integer, said value having the
interpretation of a return code

It is used like this

**. generate strL** *s* **= fileread(***filename***) if**
**fileexists(***filename***)**
**. assert filereaderror(***s***)==0**

or this

**. generate strL** *s* **= fileread(***filename***) if**
**fileexists(***filename***)**
**. generate** *rc* **= filereaderror(***s***)**

That is, **filereaderror(***s***)** is used on the result returned
by **fileread(***filename***)** to determine whether an I/O error
occurred.

In the example, we only **fileread()** files that
**fileexists()**. That is not required. If the file does
not exist, that will be detected by **filereaderror()** as
an error. The way we showed the example, we did not
want to read missing files as errors. If we wanted to
treat missing files as errors, we would have coded

**. generate strL** *s* **= fileread(***filename***)**
**. assert filereaderror(***s***)==0**

or

**. generate strL** *s* **= fileread(***filename***)**
**. generate** *rc* **= filereaderror(***s***)**
Domain: strings
Range: integers

**filewrite(***f***,***s*[**,***r*]**)**
Description: writes the string specified by *s* to the file specified
by *f* and returns the number of bytes in the resulting
file

If the optional argument *r* is specified as 1, the file
specified by *f* will be replaced if it exists. If *r* is
specified as 2, the file specified by *f* will be appended
to if it exists. Any other values of *r* are treated as
if *r* were not specified; that is, *f* will only be written
to if it does not already exist.

When the file *f* is freshly created or is replaced, the
value returned by **filewrite()** is the number of bytes
written to the file, **strlen(***s***)**. If *r* is specified as 2,
and thus **filewrite()** is appending to an existing file,
the value returned is the total number of bytes in the
resulting file; that is, the value is the sum of the
number of the bytes in the file as it existed before
**filewrite()** was called and the number of bytes newly
written to it, **strlen(***s***)**.

If the file exists and *r* is not specified as 1 or 2, or
an error occurs while writing to the file, then a
negative number (*#*) is returned, where **abs(***#***)** is a
standard Stata error return code.
Domain *f*: filenames
Domain *s*: strings
Domain *r*: integers 1 or 2
Range: integers

**float(***x***)**
Description: the value of *x* rounded to **float** precision

Although you may store your numeric variables as **byte**,
**int**, **long**, **float**, or **double**, Stata converts all numbers
to **double** before performing any calculations.
Consequently, difficulties can arise in comparing
numbers that have no finite binary representations.

For example, if the variable **x** is stored as a **float** and
contains the value **1.1** (a repeating "decimal" in
binary), the expression **x==1.1** will evaluate to *false*
because the literal **1.1** is the **double** representation of
1.1, which is different from the **float** representation
stored in **x**. (They differ by 2.384 x 10^(-8).) The
expression **x==float(1.1)** will evaluate to *true* because
the **float()** function converts the literal **1.1** to its
**float** representation before it is compared with **x**. (See
**[U] 13.12 Precision and problems therein** for more
information.)
Domain: -1e+38 to 1e+38
Range: -1e+38 to 1e+38

**fmtwidth(***fmtstr***)**
Description: the output length of the **%***fmt* contained in *fmtstr*;
*missing* if *fmtstr* does not contain a valid **%***fmt*

For example, **fmtwidth("%9.2f")** returns **9** and
**fmtwidth("%tc")** returns **18**.
Range: strings

**has_eprop(***name***)**
Description: **1** if *name* appears as a word in **e(properties)**; otherwise,
**0**
Domain: names
Range: 0 or 1

**inlist(***z***,***a***,***b***,***...***)**
Description: **1** if *z* is a member of the remaining arguments;
otherwise, **0**
All arguments must be reals or all must be strings. The
number of arguments is between 2 and 250 for reals and
between 2 and 10 for strings.
Domain: all reals or all strings
Range: 0 or 1

**inrange(***z***,***a***,***b***)**
Description: **1** if it is known that *a* __<__ *z* __<__ *b*; otherwise, **0**
The following ordered rules apply:
*z* __>__ **.** returns **0**.
*a* __>__ **.** and *b* = **.** returns **1**.
*a* __>__ **.** returns **1** if *z* __<__ *b*; otherwise, it returns **0**.
*b* __>__ **.** returns **1** if *a* __<__ *z*; otherwise, it returns **0**.
Otherwise, **1** is returned if *a* __<__ *z* __<__ *b*.
If the arguments are strings, "**.**" is interpreted as **""**.
Domain: all reals or all strings
Range: 0 or 1

**irecode(***x***,***x1***,***x2***,***...***,***xn***)**
Description: *missing* if *x* is missing or *x1*,...,*xn* is not weakly
increasing; **0** if *x* __<__ *x1*; **1** if *x1* < *x* __<__ *x2*; **2** if *x2* < *x* __<__
*x3*; ...; *n* if *x* > *xn*

Also see **autocode()** and **recode()** for other styles of
recode functions.

**irecode(3, -10, -5, -3, -3, 0, 15, .)** = **5**
Domain *x*: -8e+307 to 8e+307
Domain *xi*: -8e+307 to 8e+307
Range: nonnegative integers

**matrix(***exp***)**
Description: restricts name interpretation to scalars and matrices;
see **scalar()**
Domain: any value expression
Range: evaluation of *exp*

**maxbyte()**
Description: the largest value that can be stored in storage type
**byte**
This function takes no arguments, but the parentheses
must be included.
Range: one integer number

**maxdouble()**
Description: the largest value that can be stored in storage type
**double**
This function takes no arguments, but the parentheses
must be included.
Range: one double-precision number

**maxfloat()**
Description: the largest value that can be stored in storage type
**float**
This function takes no arguments, but the parentheses
must be included.
Range: one floating-point number

**maxint()**
Description: the largest value that can be stored in storage type **int**
This function takes no arguments, but the parentheses
must be included.
Range: one integer number

**maxlong()**
Description: the largest value that can be stored in storage type
**long**
This function takes no arguments, but the parentheses
must be included.
Range: one integer number

**mi(***x1***,***x2***,***...***,***xn***)**
Description: a synonym for **missing(***x1***,***x2***,***...***,***xn***)**

**minbyte()**
Description: the smallest value that can be stored in storage type
**byte**
This function takes no arguments, but the parentheses
must be included.
Range: one integer number

**mindouble()**
Description: the smallest value that can be stored in storage type
**double**
This function takes no arguments, but the parentheses
must be included.
Range: one double-precision number

**minfloat()**
Description: the smallest value that can be stored in storage type
**float**
This function takes no arguments, but the parentheses
must be included.
Range: one floating-point number

**minint()**
Description: the smallest value that can be stored in storage type
**int**
This function takes no arguments, but the parentheses
must be included.
Range: one integer number

**minlong()**
Description: the smallest value that can be stored in storage type
**long**
This function takes no arguments, but the parentheses
must be included.
Range: one integer number

**missing(***x1***,***x2***,***...***,***xn***)**
Description: **1** if any of the arguments evaluates to *missing*;
otherwise, **0**

Stata has two concepts. of missing values: a numeric
missing value (**.**, **.a**, **.b**, ..., **.z**) and a string missing
value (**""**). **missing()** returns **1** (meaning *true*) if any
expression *xi* evaluates to *missing*. If *x* is numeric,
**missing(***x***)** is equivalent to *x* __>__ **.**. If *x* is string,
**missing(***x***)** is equivalent to *x***==""**.
Domain *xi*: any string or numeric expression
Range: 0 and 1

**r(***name***)**
Description: the value of stored result **r(***name***)**; see **[U] 18.8**
**Accessing results calculated by other programs**

**r(***name***)** = scalar missing if the stored result does not
exist
**r(***name***)** = specified matrix if the stored result is a
matrix
**r(***name***)** = scalar numeric value if the stored result is a
scalar that can be interpreted as a number
Domain: names
Range: strings, scalars, matrices, or *missing*

**recode(***x***,***x1***,***x2***,***...***,***xn***)**
Description: *missing* if *x1*, *x2*, ..., *xn* is not weakly increasing; *x*
if *x* is missing; *x1* if *x* __<__ *x1*; *x2* if *x* __<__ *x2*, ...;
otherwise, *xn* if *x* > *x1*, *x2*, ..., *xn-1*. *xi* __>__ **.** is
interpreted as *xi* = +inf

Also see **autocode()** and **irecode()** for other styles of
recode functions.
Domain *x*: -8e+307 to 8e+307 or *missing*
Domain *x1*: -8e+307 to 8e+307
Domain *x2*: *x1* to 8e+307
...
Domain *xn*: *xn-1* to 8e+307
Range: *x1*, *x2*, ..., *xn* or *missing*

**replay()**
Description: **1** if the first nonblank character of local macro **`0'** is
a comma, or if **`0'** is empty

This is a function for use by programmers writing
estimation commands; see **[P] ereturn**.
Range: integers 0 and 1, meaning *false* and *true*, respectively

**return(***name***)**
Description: the value of the to-be-stored result **return(***name***)**; see
**[P] return**

**return(***name***)** = scalar missing if the stored result
does not exist
**return(***name***)** = specified matrix if the stored result
is a matrix
**return(***name***)** = scalar numeric value if the stored
result is a scalar
Domain: names
Range: strings, scalars, matrices, or *missing*

**s(***name***)**
Description: the value of stored result **s(***name***)**; see **[U] 18.8**
**Accessing results calculated by other programs**

**s(***name***)** = **.** if the stored result does not exist
Domain: names
Range: strings or *missing*

**scalar(***exp***)**
Description: restricts name interpretation to scalars and matrices

Names in expressions can refer to names of variables in
the dataset, names of matrices, or names of scalars.
Matrices and scalars can have the same names as
variables in the dataset. If names conflict, Stata
assumes that you are referring to the name of the
variable in the dataset.

**matrix()** and **scalar()** explicitly state that you are
referring to matrices and scalars. **matrix()** and
**scalar()** are the same function; scalars and matrices may
not have the same names and so cannot be confused.
Typing **scalar(x)** makes it clear that you are referring
to the scalar or matrix named **x** and not the variable
named **x**, should there happen to be a variable of that
name.
Domain: any valid expression
Range: evaluation of *exp*

**smallestdouble()**
Description: the smallest double-precision number greater than zero
If 0 < *d* < **smallestdouble()**, then *d* does not have full
double precision; these are called the denormalized
numbers. This function takes no arguments, but the
parentheses must be included.
Range: a double-precision number close to 0