Stata 15 help for extended_fcn

[P] macro -- Extended macro functions

Syntax

{local | global} mname : extended_function

where extended_function is any of the following:

Macro extended function for extracting program properties

properties command

Macro extended functions for extracting data attributes

type varname

format varname

value label varname

variable label varname

data label

sortedby

label { valuelabelname | (varname) } { maxlength | # [#_2] } [, strict ]

constraint { dir | # }

char { varname[] | varname[charname] }

char { _dta[] | _dta[charname] }

Macro extended function for naming variables

permname suggestedname [, length(#) ]

Macro extended functions for filenames and file paths

adosubdir ["]filename["]

dir ["]dirname["] {files|dirs|other} ["]pattern["] [, nofail respectcase]

sysdir [ STATA | BASE | SITE | PLUS | PERSONAL | dirname ]

Macro extended function for accessing operating-system parameters

environment name

Macro extended functions for names of stored results

e(scalars | macros | matrices | functions)

r(scalars | macros | matrices | functions)

s(macros)

all {globals|scalars|matrices} ["pattern"]

all {numeric|string} scalars ["pattern"]

Macro extended function for formatting results

display display_directive

Macro extended functions for manipulating lists

list macrolist_directive

Macro extended functions related to matrices

rownames matrixname

colnames matrixname

rowfullnames matrixname

colfullnames matrixname

roweq matrixname [, quoted ]

coleq matrixname [, quoted ]

rownumb matrixname string

colnumb matrixname string

roweqnumb matrixname string

coleqnumb matrixname string

rownfreeparms matrixname

colnfreeparms matrixname

rownlfs matrixname

colnlfs matrixname

rowsof matrixname

colsof matrixname

rowvarlist matrixname

colvarlist matrixname

rowlfnames matrixname [, quoted ]

collfnames matrixname [, quoted ]

Macro extended function related to time-series operators

tsnorm string [, varname ]

Macro extended function for copying a macro

copy { local | global } mname

Macro extended functions for parsing

word count string

word # of string

piece #_1 #_2 of [`]"string"['] [, nobreak ]

strlen { local | global } mname

ustrlen { local | global } mname

udstrlen { local | global } mname

subinstr { local | global } mname [`]"from"['] [`]"to"['] [, all word count({ local | global } mname) ]

Description

Macro extended function for extracting program properties

properties command returns the properties declared for command; see [P] program properties.

Macro extended functions for extracting data attributes

type varname returns the storage type of varname, which might be int, long, float, double, str1, str2, etc.

format varname returns the display format associated with varname; for instance, %9.0g or %12s.

value label varname returns the name of the value label associated with varname, which might be "" (meaning no label), or, for example, make, meaning that the value label's name is make.

variable label varname returns the variable label associated with varname, which might be "" (meaning no label), or, for example, Repair Record 1978.

data label returns the dataset label associated with varname, which might be "" (meaning no label), or, for example, 1978 Automobile Data. See [D] label.

sortedby returns the names of the variables by which the data in memory are currently sorted, which might be "" (meaning not sorted), or, for example, foreign mpg, meaning that the data are in the order of variable foreign, and, within that, in the order of mpg (the order that would be obtained from the Stata command sort foreign mpg). See [D] sort.

label valuelabelname { maxlength | # [#_2] } [, strict ] returns the value label of # in valuelabelname. For instance, label forlab 1 might return Foreign cars if forlab were the name of a value label and 1 mapped to "Foreign cars". If 1 did not correspond to any mapping within the value label, or if the value label forlab were not defined, 1 (the # itself) would be returned.

#_2 optionally specifies the maximum length of the label to be returned. If label forlab 1 would return Foreign cars, then label forlab 1 6 would return Foreig.

maxlength specifies that, rather than looking up a number in a value label, label return the maximum length of the labelings. For instance, if value label yesno mapped 0 to no and 1 to yes, then its maxlength would be 3 because yes is the longest label and it has three characters.

strict specifies that nothing is to be returned if there is no value label for #.

label (varname) { maxlength | # [#_2] } [, strict ] works exactly as the above, except that rather than specifying the valuelabelname directly, you indirectly specify it. The value label name associated with varname is used, if there is one. If not, it is treated just as if valuelabelname were undefined, and the number itself is returned.

constraint { # | dir } gives information on constraints.

constraint # puts constraint # in mname or returns "" if constraint # is not defined. constraint # for # < 0 is an error.

constraint dir returns an unsorted numerical list of those constraints that are currently defined. For example,

. constraint 1 price = weight . constraint 2 mpg > 20 . local myname : constraint 2 . macro list _myname _myname mpg > 20

. local aname : constraint dir

. macro list _aname _aname: 2 1

char { varname[] | varname[charname] } or char { _dta[] | _dta[charname] } returns information on the characteristics of a dataset; see [P] char. For instance,

. sysuse auto

. char mpg[one] "this" . char mpg[two] "that"

. local x : char mpg[one]

. di "`x'" this

. local x : char mpg[nosuch]

. di "`x'"

. local x : char mpg[]

. di "`x'" two one

Macro extended function for naming variables

permname suggested_name [, length(#) ] returns a valid new variable name based on suggested_name in matname, where suggested_name must follow naming conventions but may be too long or correspond to an already existing variable.

length(#) specifies the maximum length of the returned variable name, which must be between 8 and 32. length(32) is the default. For instance,

. local myname : permname foreign

. macro list _myname _myname: foreign1

. local aname : permname displacement, length(8)

. macro list _aname _aname displace

Macro extended functions for filenames and file paths

adosubdir ["]filename["] puts in mname the subdirectory in which Stata would search for this file along the ado-path. Typically, the directory name would be the first letter of filename. However, certain files may result in a different directory name depending on their extension.

dir ["]dirname["] { files | dirs | other } ["]pattern["] [, nofail respectcase] puts in mname the specified files, directories, or entries that are neither files nor directories, from directory dir and matching pattern pattern, where the pattern matching is defined by Stata's strmatch(s1,s2) function. The quotes in the command are optional but recommended, and they are nearly always required surrounding pattern. The returned string will contain each of the names, separated one from the other by spaces and each enclosed in double quotes. If mname is subsequently used in a quoted context, it must be enclosed in compound double quotes: `"`mname'"'.

The nofail specifies that if the directory contains too many filenames to fit into a macro, rather than issuing an error, the filenames that fit into mname should be returned. nofail should rarely, if ever, be specified.

In Windows only, the respectcase option specifies that dir respect the case of filenames when performing matches. Unlike other operating systems, Windows has, by default, case-insensitive filenames. respectcase is ignored in operating systems other than Windows.

For example,

local list : dir . files "*" makes a list of all regular files in the current directory. In list might be returned "subjects.dta" "step1.do" "step2.do" "reest.ado".

local list : dir . files "s*", respectcase in Windows makes a list of all regular files in the current directory that begin with a lowercase "s". The case of characters in the filenames is preserved. In Windows, without the respectcase option, all filenames would be converted to lowercase before being compared with pattern and possibly returned.

local list : dir . dirs "*" makes a list of all subdirectories of the current directory. In list might be returned "notes" "subpanel". {pmore2} local list : dir . other "*" makes a list of all things that are neither regular files nor directories. These files rarely occur and might be, for instance, Unix device drivers. {pmore2} local list : dir "\mydir\data" files "*" makes a list of all regular files that are to be found in \mydir\data. Returned might be "example.dta" "make.do" "analyze.do". {pmore2} It is the names of the files that are returned, not their full path names. {pmore2} local list : dir "subdir" files "*" makes a list of all regular files that are to be found in subdir of the current directory. {phang2} sysdir [ STATA | BASE | SITE | PLUS | PERSONAL ] {break} returns the various Stata system directory paths; see [P] sysdir. The path is returned with a trailing separator; for example, sysdir STATA might return D:\PROGRAMS\STATA\. {phang2} sysdir dirname {break} returns dirname. This function is used to code local x : sysdir `dir', where `dir' might contain the name of a directory specified by a user or a keyword, such as STATA or BASE. The appropriate directory name will be returned. The path is returned with a trailing separator. {pstd}Macro extended function for accessing operating-system parameters {phang2} environment name {break} returns the contents of the operating system's environment variable name, or "" if name is undefined. {pstd}Macro extended functions for names of stored results {phang2} e(scalars | macros | matrices | functions) {break} returns the names of all the stored results in e() of the specified type, with the names listed one after the other and separated by one space. For instance, e(scalars) might return N ll_0 ll df_m chi2 r2_p, meaning that scalar stored results e(N), e(ll_0), ... exist. {phang2} r(scalars | macros | matrices | functions) {break} returns the names of all the stored results in r() of specified type. {phang2} s(macros) {break} returns the names of all the stored results in s() of type macro, which is the only type that exists within s(). {phang2} all { globals | scalars | matrices } ["pattern"] {break} puts in mname the specified globals, scalars, or matrices that match the pattern, where the pattern matching is defined by Stata's strmatch(s1,s2) function. {phang2} all { numeric | string } scalars ["pattern"] {break} puts in mname the specified numeric or string scalars that match the pattern, where the pattern matching is defined by Stata's strmatch(s1,s2) function. {pstd}Macro extended function for formatting results {phang2} display display_directive {break} returns the results from the display command. The display extended function is the display command, except that the output is rerouted to a macro rather than the screen. {pmore2} You can use all the features of display that make sense. That is, you may not set styles with as style because macros do not have colors, you may not use _continue to suppress going to a new line on the real display (it is not being displayed), you may not use _newline (for the same reason), and you may not use _request to obtain input from the console (because input and output have nothing to do with macro definition). Everything else works. See [P] display. {pmore2} Example: local x : display %9.4f sqrt(2) {pstd}Macro extended function for manipulating lists {phang2} list macrolist_directive {break} fills in mname with the macrolist_directive, which specifies one of many available commands or operators for working with macros that contain lists; see [P] macro lists. {pstd}Macro extended functions related to matrices {pstd} In understanding the functions below, remember that the fullname of a matrix row or column is defined as eqname:name. For instance, fullname might be outcome:weight, and then the eqname is outcome and the name is weight. Or, the fullname might be gnp:L.cpi, and then the eqname is gnp and the name is L.cpi. Or, the fullname might be mpg, in which case the eqname is "" and the name is mpg. For more information, see [P] matrix define. {phang2} rownames matrixname{p_end} {phang2} rowfullnames matrixname{p_end} {phang2} roweq matrixname [, quoted ] {break} return the names of the rows of matname; see matmacfunc. {phang2} colnames matrixname{p_end} {phang2} colfullnames matrixname{p_end} {phang2} coleq matrixname [, quoted ] {break} return the names of the columns of matname; see matmacfunc. {phang2} rownumb matrixname string {break} returns the row number of matname that matches string; see matmacfunc. {phang2} colnumb matrixname string {break} returns the column number of matname that matches string; see matmacfunc. {phang2} roweqnumb matrixname string {break} returns the row equation number of matname that matches string; see matmacfunc. {phang2} coleqnumb matrixname string {break} returns the column equation number of matname that matches string; see matmacfunc. {phang2} colnfreeparms matrixname{break} returns the number of free parameter columns of matname; see matmacfunc. {phang2} rownfreeparms matrixname{break} returns the number of free parameter rows of matname; see matmacfunc. {phang2} colnlfs matrixname{break} returns the number of linear forms among the columns of matname; see matmacfunc. {phang2} rownlfs matrixname{break} returns the number of linear forms among the rows of matname; see matmacfunc. {phang2} colsof matrixname{break} returns the number of columns of matname; see matmacfunc. {phang2} rowsof matrixname{break} returns the number of rows of matname; see matmacfunc. {phang2} colvarlist matrixname{break} returns the variable list corresponding to the columns of matname; see matmacfunc. {phang2} rowvarlist matrixname{break} returns the variable list corresponding to the rows of matname; see matmacfunc. {phang2} collfnames matrixname [, quoted ] {break} returns the list of names corresponding to the linear forms in the columns of matname; see matmacfunc. {phang2} rowlfnames matrixname [, quoted ] {break} returns the list of names corresponding to the linear forms in the rows of matname; see matmacfunc. {pstd}Macro extended function related to time-series operators {phang2} tsnorm string {break} returns the canonical form of string when string is interpreted as a time-series operator. For instance, if string is ldl, then L2D is returned, or if string is l.ldl, then L3D is returned. If string is nothing, "" is returned. {phang2} tsnorm string, varname {break} returns the canonical form of string when string is interpreted as a time series--operated variable. For instance, if string is ldl.gnp, then L2D.gnp is returned, and if string is l.ldl.gnp, then L3D.gnp is returned. If string is just a variable name, the variable name is returned. {pstd}Macro extended function for copying a macro {phang2} copy { local | global } mname {break} returns a copy of the contents of mname, or an empty string if mname is undefined. {pstd}Macro extended functions for parsing {phang2} word count string {break} returns the number of words in string. A token is a word (characters separated by spaces) or set of words enclosed in quotes. Do not enclose string in double quotes because word count will return 1. {phang2} word # of string {break} returns the #th token of string. Do not enclose string in double quotes. {phang2} piece #_1 #_2 of [`]"string"['] [, nobreak ] {break} returns a piece of string. This macro extended function provides a smart method of breaking a string into pieces of roughly the specified display columns. #_1 specifies which piece to obtain. #_2 specifies the maximum number of display columns of each piece. Each piece is built trying to fill to the maximum number of display columns without breaking in the middle of a word. However, when a word takes more display columns than #_2, the word will be split unless nobreak is specified. nobreak specifies that words not be broken, even if that would result in a string being displayed in more than #_2 columns. {pmore2} Compound double quotes may be used around string and must be used when string itself might contain double quotes. {phang2} strlen { local | global } mname {break} returns the length of the contents of mname in bytes. If mname is undefined, 0 is returned. For instance, . constraint 1 price = weight . local myname : constraint 1 . macro list _myname _myname price = weight . local lmyname : strlen local myname . macro list _lmyname _lmyname: 14 {phang2} ustrlen { local | global } mname {break} returns the length of the contents of mname in Unicode characters. If mname is undefined, 0 is returned. {phang2} udstrlen { local | global } mname {break} returns the length of the contents of mname in display columns. If mname is undefined, 0 is returned. {phang2} subinstr local mname "from" "to" {break} returns the contents of mname, with the first occurrence of "from" changed to "to". {phang2} subinstr local mname "from" "to", all {break} does the same thing but changes all occurrences of "from" to "to". {phang2} subinstr local mname "from" "to", word {break} returns the contents of mname, with the first occurrence of the word "from" changed to "to". A word is defined as a space-separated token or a token at the beginning or end of the string. {phang2} subinstr local mname "from" "to", all word {break} does the same thing but changes all occurrences of the word "from" to "to". {phang2} subinstr global mname ... {break} is the same as the above, but obtains the original string from the global macro $mname rather than from the local macro mname. {phang2} subinstr ... global mname ..., ... count( { global | local } mname2) {break} in addition to the usual, places a count of the number of substitutions in the specified global or in local macro mname2.


© Copyright 1996–2018 StataCorp LLC   |   Terms of use   |   Privacy   |   Contact us   |   What's new   |   Site index