|
Size: 9475
Comment:
|
Size: 9167
Comment: Rewrite
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 10: | Line 10: |
| == General Syntax == | |
| Line 12: | Line 11: |
| == General Purpose Functions == | |
| Line 13: | Line 13: |
| There are three sets of general-purpose string functions. The first are general-purpose string functions. | |
| Line 14: | Line 15: |
| === Date and Datetime Masks === | ||'''Function Name'''||'''Meaning''' ||'''Example'''|| ||`abbrev(s,n)` || || || ||`plural(n,s)` ||Append "s" to string s if n>1, otherwise returns the original string s|| || ||`plural(n,s,p)` ||As `plural` but specifying the plural form p explicitly || || ||`real(s)` ||Convert string s to a real value || || ||`string(n)` ||Convert numeric value n to a string || || ||`string(n,f)` ||Convert numeric value n to a string using format f || || ||`stritrim(s)` ||Remove duplicated internal space characters || || ||`strofreal(n)` ||Convert numeric value n to a string || || ||`strofreal(n,f)` ||Convert numeric value n to a string using format f || || The second set are the legacy functions designed for string data representing strictly ASCII-encoded values. |
| Line 16: | Line 28: |
| Date and datetime conversion functions use a concept of '''masks'''. These instruct the function how to interpret the string. | ||'''Function Name''' ||'''Meaning''' ||'''Example'''|| ||`char(n)` ||ASCII code n || || ||`indexnot(a,b)` || || || ||`lower(s)` ||Convert to lowercase || || ||`ltrim(s)` ||Remove leading space characters || || ||`rtrim(s)` ||Remove trailing space characters || || ||`soundex(s)` || || || ||`soundex_nara(s)` || || || ||`strlen(s)` ||Length of string s in characters/bytes || || ||`strlower(s)` ||Convert to lowercase || || ||`strltrim(s)` ||Remove leading space characters || || ||`strpos(s,p)` || || || ||`strproper(s)` ||Convert to proper case || || ||`strreverse(s)` || || || ||`strrpos(s,p)` || || || ||`strrtrim(s)` ||Remove trailing space characters || || ||`strtrim(s)` ||Remove external space characters || || ||`strupper(s)` ||Convert to uppercase || || ||`subinstr(s,p,r,n)` ||Replace the first n matches of pattern p with replacement r || || ||`subinword(s,p,r,n)`|| || || ||`substr(s,o)` ||Return the substring of string s from offset o || || ||`substr(s,o,n)` ||Return the substring of string s from offset o for length n characters|| || ||`trim(s)` ||Remove external space characters || || ||`upper(s)` ||Convert to uppercase || || ||`word(s,n)` || || || ||`wordcount(s)` || || || |
| Line 18: | Line 55: |
| A mask of `"DMY"` can parse all of: | The third set are the new functions designed for Unicode-encoded values. |
| Line 20: | Line 57: |
| * `"21nov2006"` * `"21 November 2006"` * `"21-11-2006"` * `"21112006"` |
||'''Function Name''' ||'''Meaning''' ||'''Example'''|| ||`uchar(n)` ||Unicode code n || || ||`udstrlen(s)` ||Length of string s in display columns, respecting wide characters || || ||`udsubstr(s,o,n)` ||Return the substring of string s from offset o for n display columns || || ||`uisdigit(s)` || || || ||`uisletter(s)` || || || ||`ustrcompare(a,b)` || || || ||`ustrcompare(a,b,l)`|| || || ||`ustrleft(s,n)` ||Return the leftmost substring of string s for length n characters || || ||`ustrlen(s)` ||Length of string s in characters || || ||`ustrlower(s)` ||Convert to lowercase || || ||`ustrlower(s,l)` ||Convert to lowercase in locale l || || ||`ustrltrim(s)` || || || ||`ustrpos(s)` || || || ||`ustrreverse(s)` || || || ||`ustrright(s,n)` ||Return the rightmost substring of string s for length n characters || || ||`ustrrpos(s,p)` || || || ||`ustrrpos(s,p,o)` || || || ||`ustrrtrim(s)` || || || ||`ustrsortkey(s)` || || || ||`ustrsortkey(s,l)` || || || ||`ustrtitle(s)` ||Convert to title case || || ||`ustrtitle(s,l)` ||Convert to title case in locale l || || ||`ustrtrim(s)` ||Remove external whitespace characters || || ||`ustrupper(s)` ||Convert to uppercase || || ||`ustrupper(s,l)` ||Convert to uppercase in locale l || || ||`ustrword(s,n)` || || || ||`ustrword(s,n,l)` || || || ||`ustrwordcount(s)` || || || ||`ustrwordcount(s,l)`|| || || ||`usubinstr(s,p,r,n)`||Replace the first n matches of pattern p with replacement r || || ||`usubstr(s,o,n)` ||Return the substring of string s from offset o for length n characters|| || |
| Line 25: | Line 90: |
| Spaces are ignored in a mask; `"DMY"` is equivalent to `"D M Y"`. | A couple of notes about the `substr` functions: |
| Line 27: | Line 92: |
| The mask `"DMY"` cannot parse a string with a two-digit year. A two-digit prefix can be applied to "Y" in the mask, such as "DM19Y". If a string has a two-digit year, such a mask will cause the year to be interpreted as being within the 1900s. If a string has a four-digit year, the mask will not mutate the value. ---- == Clock == Convert a string date and time into the number of milliseconds since the Stata epoch (`01jan1960 00:00:00.000`). There are two functions: '''`clock`''' and '''`Clock`'''. To create a datetime that ''ignores'' leap seconds, try: {{{ generate double datetime = clock(string, "YMDhms") format datetime %tc }}} To create a datetime that ''includes'' leap seconds since the epoch, try: {{{ generate double datetime = Clock(string, "YMDhms") format datetime %tC }}} As noted above, the mask should be composed of: `"Y"`, `"M"`, `"D"`, `"h"`, `"m"`, and `"s"`. See above for details on masks. ---- == Date == Convert a string date into the number of days since the Stata epoch (`01jan1960 00:00:00.000`). {{{ generate long date = date(string, "MDY") format date %td }}} As noted above, the mask should be composed of: `"Y"`, `"M"`, and `"D"`. See above for details on masks. ---- == HalfYearly == Convert a string date into the number of half years since the Stata epoch (`01jan1960 00:00:00.000`). {{{ generate int halfyear = halfyearly(string, "YH") format halfyear %th }}} As noted above, the mask should be composed of: `"Y"` and `"H"`. See above for details on masks. ---- == Monthly == Convert a string date into the number of months since the Stata epoch (`01jan1960 00:00:00.000`). {{{ generate int month = monthly(string, "YM") format month %tm }}} As noted above, the mask should be composed of: `"Y"` and `"M"`. See above for details on masks. ---- == Quarterly == Convert a string date into the number of quarters since the Stata epoch (`01jan1960 00:00:00.000`). {{{ generate int quarter = quarterly(string, "YQ") format quarter %tq }}} As noted above, the mask should be composed of: `"Y"` and `"Q"`. See above for details on masks. ---- == RegexM == Match a string against a pattern. Returns 1 if the string matches and 0 otherwise. The string must not contain a null byte (`char(0)`). While fixed-length strings cannot contain a null byte by design, long strings (`strL`) can. To get around this restriction, consider [[Stata/StringFunctions#UstrRegexM|ustrregexm]]. The {{{ generate byte begins_with_number = regexm(string, "^[0-9]") }}} See [[Stata/RegularExpressions|here]] for details on Stata's regular expressions. ---- == RegexR == Match a string against a pattern and replace the first matching substring with a replacement substring. The string must not contain a null byte (`char(0)`). While fixed-length strings cannot contain a null byte by design, long strings (`strL`) can. Returned substrings can be up to 1,100,000 bytes long. To get around these restrictions, consider [[Stata/StringFunctions#UstrRegexRf|ustrregexrf]]. To replace more than just the first matching substring, consider [[Stata/StringFunctions#UstrRegexRa|ustrregexra]]. {{{ generate filename_without_extension = regexr(filename,"\.(txt|csv|tsv)","") }}} See [[Stata/RegularExpressions|here]] for details on Stata's regular expressions. ---- == RegexS == Extract the nth matching substring from a prior `regexm` test. The 0th match is the original string if it matched. Only the first 9 matching substrings are stored and available. Returned substrings can be up to 1,100,000 bytes long. To get around these restrictions, consider [[Stata/StringFunctions#UstrRegexS|ustrregexs]]. {{{ generate byte is_pipe_delimited = regexm(string,"[^|]+") generate first_field = regexs(1) }}} See [[Stata/RegularExpressions|here]] for details on Stata's regular expressions. ---- == SubInStr == ---- == SubStr == Extract a substring from a string using a ''start'' argument and an optional ''length'' argument, as `substr(string, start, length)`. If the optional ''length'' argument is left off or set to the missing value (`.`), the extraction continues to the end of the string. {{{ generate skip_first_character = substr(string, 2) generate skip_first_character = substr(string, 2, .) generate second_character = substr(string, 2, 1) generate last_character = substr(string, -1, 1) }}} The ''start'' and ''length'' parameters are byte positions rather than character indices, which does not matter for ASCII data but will impact many other character encodings. If the optional ''length'' argument is left off and a null byte (`char(0)`) is encountered between the ''start'' byte position and the end of the string, the extraction ends at that null byte (excluding the null byte). To get around these restrictions, consider [[Stata/StringFunctions#USubStr|usubstr]]. ---- == UstrLeft == Extract the first n characters from a string. {{{ generate first_two = ustrleft(string, 2) }}} ---- == UstrRegexM == Match a Unicode string against a pattern. Returns 1 if the string matches and 0 otherwise. The optional third argument toggles case-insensitive matching. The default is 0 (case-sensitive). {{{ generate byte begins_with_number = ustrregexm(string, "^[0-9]") generate byte begins_with_letter = ustrregexm(string, "^[a-z]", 1) }}} See [[Stata/RegularExpressions|here]] for details on Stata's regular expressions. ---- == UstrRegexRf == Match a Unicode string against a pattern and replace the first matching substring with a replacement substring. The optional fourth argument toggles case-insensitive matching. The default is 0 (case-sensitive). {{{ generate filename_without_extension = ustrregexrf(filename, "\.(txt|csv|tsv)", "", 1) }}} See [[Stata/RegularExpressions|here]] for details on Stata's regular expressions. ---- == UstrRegexRa == Match a Unicode string against a pattern and replace all matching substrings with a replacement substring. The optional fourth argument toggles case-insensitive matching. The default is 0 (case-sensitive). {{{ generate name_without_numbers = ustrregexra(name, "[0-9]", "") generate name_without_accented_a = ustrregexra(name, "[áàȧâäǎăāãå]", "a", 1) }}} See [[Stata/RegularExpressions|here]] for details on Stata's regular expressions. ---- == UstrRegexS == Extract the nth matching substring from a prior `regexm` test. The 0th match is the original string if it matched. {{{ generate byte is_pipe_delimited = ustrregexm(string,"[^|]+") generate first_field = ustrregexs(1) }}} See [[Stata/RegularExpressions|here]] for details on Stata's regular expressions. ---- == UstrRight == Extract the last n characters from a string. {{{ generate last_two = ustrright(string, 2) }}} ---- == USubInStr == ---- == USubStr == Extract a substring from a string using ''start'' and ''length'' arguments, as `usubstr(string, start, length)`. If the ''length'' argument is the missing value (`.`), the extraction continues to the end of the string. |
* Negative offsets are interpreted as offsets from the end of the string value. * Missing lengths are interpreted as the maximum; read until the end of the string value. |
| Line 298: | Line 101: |
| The ''start'' and ''length'' parameters are character indices, irrespective of wide characters. To extract a substring that can be printed in fixed-width fonts to a fixed-length space respecting wide characters, consider [[Stata/StringFunctions#UdSubStr|udsubstr]]. | |
| Line 304: | Line 107: |
| == UdSubStr == | == Regular Expression Functions == |
| Line 306: | Line 109: |
| Extract a substring from a string using ''start'' and ''length'' arguments, as `udsubstr(string, start, length)`. If the ''length'' argument is the missing value (`.`), the extraction continues to the end of the string. | There are two sets of regular expression functions. The first are the legacy functions designed for string data representing strictly ASCII-encoded values. |
| Line 308: | Line 111: |
| {{{ generate skip_first_character = udsubstr(string, 2, .) generate second_character = udsubstr(string, 2, 1) generate last_character = udsubstr(string, -1, 1) }}} |
||'''Function Name'''||'''Meaning''' ||'''Example''' || ||`regexm(s,p)` ||1 if string s matches pattern p, 0 otherwise ||`regexm(zip5,"^[0-9][0-9][0-9][0-9][0-9]$")`|| ||`regexr(s,p,r)` ||Replace all matches to pattern p with replacement r ||`regexr(filename,"\.(txt|csv|tsv)","")` || ||`regexs(n)` ||The nth (in [1,9]) pattern match from the last `regexm` call|| || |
| Line 314: | Line 116: |
| The ''start'' and ''length'' parameters are display columns. To extract a substring that is a fixed number of characters, consider [[Stata/StringFunctions#USubStr|usubstr]]. | The second set are the new functions designed for Unicode-encoded values. ||'''Function Name''' ||'''Meaning''' ||'''Example''' || ||`ustrregexm(s,p)` ||1 if string s matches pattern p, 0 otherwise || || ||`ustrregexm(s,p,b)` ||Call `ustrregexm` with case-insensitivity if b is 1 || || ||`ustrregexrf(s,p,r)` ||Replace the first match to pattern p with replacement r|| || ||`ustrregexrf(s,p,r,b)`||Call `ustrregexrf` with case-insensitivity if b is 1 || || ||`ustrregexra(s,p,r)` ||Replace all matches to pattern p with replacement r || || ||`ustrregexra(s,p,r,b)`||Call `ustrregexrf` with case-insensitivity if b is 1 || || ||`ustrregexs(n)` ||The nth pattern match from the last `ustrregexm` call || || For `ustrregexs`, note that the 0th match is them entire original string if it matched the pattern at all. See [[Stata/RegularExpressions|here]] for details on Stata's regular expressions syntax. |
| Line 320: | Line 135: |
| == Encoding and Decoding Functions == | |
| Line 321: | Line 137: |
| == Weekly == | There are several function meant for encoding or decoding string data. |
| Line 323: | Line 139: |
| Convert a string date into the number of weeks since the Stata epoch (`01jan1960 00:00:00.000`). {{{ generate int week = weekly(string, "YW") format week %tw }}} As noted above, the mask should be composed of: `"Y"` and `"W"`. See above for details on masks. |
||'''Function Name''' ||'''Meaning'''|| ||`tobytes(s)` || || ||`tobytes(s,n)` || || ||`ustrfix(s)` || || ||`ustrfix(s,r)` || || ||`ustrfrom(s,e,m)` || || ||`ustrinvalidcnt(s)` || || ||`ustrnormalize(s,m)`|| || ||`ustrto(s,e,m)` || || ||`ustrtohex(s)` || || ||`ustrtohex(s,n)` || || ||`ustrunescape(s)` || || |
| Line 336: | Line 156: |
| == Yearly == | == Locale Name Functions == |
| Line 338: | Line 158: |
| Convert a string date into the number of years since the Stata epoch (`01jan1960 00:00:00.000`). | Several of the above string functions take an optional ''locale name'' argument. This creates the need for more functions that can parse and validate locale names. |
| Line 340: | Line 160: |
| {{{ generate int year = yearly(string, "Y") format year %th }}} |
||'''Function Name''' ||'''Meaning'''|| ||`collatorlocale(l,t)` || || ||`collatorversion(l)` || || ||`wordbreaklocale(s,n)`|| || |
| Line 345: | Line 165: |
| As noted above, the mask should be composed of: `"Y"` and `"W"`. See above for details on masks. | ---- == Stata Name Functions == Stata offers several functions for generating a safe name, as for use in generating variables or macros. ||'''Function Name''' ||'''Meaning''' || ||`strtoname(s)` ||Create a Stata 13 name || ||`ustrtoname(s)` ||Create a modern Stata name|| Both of these functions are variadic. If the second argument is a 1, and then if the first character is numeric, the returned name is prefixed with an underscore character. ---- == See also == [[https://www.stata.com/manuals/fnstringfunctions.pdf|Stata string functions]] |
Stata String Functions
Stata supports these string functions in the global scope.
Contents
General Purpose Functions
There are three sets of general-purpose string functions. The first are general-purpose string functions.
Function Name |
Meaning |
Example |
abbrev(s,n) |
|
|
plural(n,s) |
Append "s" to string s if n>1, otherwise returns the original string s |
|
plural(n,s,p) |
As plural but specifying the plural form p explicitly |
|
real(s) |
Convert string s to a real value |
|
string(n) |
Convert numeric value n to a string |
|
string(n,f) |
Convert numeric value n to a string using format f |
|
stritrim(s) |
Remove duplicated internal space characters |
|
strofreal(n) |
Convert numeric value n to a string |
|
strofreal(n,f) |
Convert numeric value n to a string using format f |
|
The second set are the legacy functions designed for string data representing strictly ASCII-encoded values.
Function Name |
Meaning |
Example |
char(n) |
ASCII code n |
|
indexnot(a,b) |
|
|
lower(s) |
Convert to lowercase |
|
ltrim(s) |
Remove leading space characters |
|
rtrim(s) |
Remove trailing space characters |
|
soundex(s) |
|
|
soundex_nara(s) |
|
|
strlen(s) |
Length of string s in characters/bytes |
|
strlower(s) |
Convert to lowercase |
|
strltrim(s) |
Remove leading space characters |
|
strpos(s,p) |
|
|
strproper(s) |
Convert to proper case |
|
strreverse(s) |
|
|
strrpos(s,p) |
|
|
strrtrim(s) |
Remove trailing space characters |
|
strtrim(s) |
Remove external space characters |
|
strupper(s) |
Convert to uppercase |
|
subinstr(s,p,r,n) |
Replace the first n matches of pattern p with replacement r |
|
subinword(s,p,r,n) |
|
|
substr(s,o) |
Return the substring of string s from offset o |
|
substr(s,o,n) |
Return the substring of string s from offset o for length n characters |
|
trim(s) |
Remove external space characters |
|
upper(s) |
Convert to uppercase |
|
word(s,n) |
|
|
wordcount(s) |
|
|
The third set are the new functions designed for Unicode-encoded values.
Function Name |
Meaning |
Example |
uchar(n) |
Unicode code n |
|
udstrlen(s) |
Length of string s in display columns, respecting wide characters |
|
udsubstr(s,o,n) |
Return the substring of string s from offset o for n display columns |
|
uisdigit(s) |
|
|
uisletter(s) |
|
|
ustrcompare(a,b) |
|
|
ustrcompare(a,b,l) |
|
|
ustrleft(s,n) |
Return the leftmost substring of string s for length n characters |
|
ustrlen(s) |
Length of string s in characters |
|
ustrlower(s) |
Convert to lowercase |
|
ustrlower(s,l) |
Convert to lowercase in locale l |
|
ustrltrim(s) |
|
|
ustrpos(s) |
|
|
ustrreverse(s) |
|
|
ustrright(s,n) |
Return the rightmost substring of string s for length n characters |
|
ustrrpos(s,p) |
|
|
ustrrpos(s,p,o) |
|
|
ustrrtrim(s) |
|
|
ustrsortkey(s) |
|
|
ustrsortkey(s,l) |
|
|
ustrtitle(s) |
Convert to title case |
|
ustrtitle(s,l) |
Convert to title case in locale l |
|
ustrtrim(s) |
Remove external whitespace characters |
|
ustrupper(s) |
Convert to uppercase |
|
ustrupper(s,l) |
Convert to uppercase in locale l |
|
ustrword(s,n) |
|
|
ustrword(s,n,l) |
|
|
ustrwordcount(s) |
|
|
ustrwordcount(s,l) |
|
|
usubinstr(s,p,r,n) |
Replace the first n matches of pattern p with replacement r |
|
usubstr(s,o,n) |
Return the substring of string s from offset o for length n characters |
|
A couple of notes about the substr functions:
- Negative offsets are interpreted as offsets from the end of the string value.
- Missing lengths are interpreted as the maximum; read until the end of the string value.
generate skip_first_character = usubstr(string, 2, .) generate second_character = usubstr(string, 2, 1) generate last_character = usubstr(string, -1, 1)
Regular Expression Functions
There are two sets of regular expression functions. The first are the legacy functions designed for string data representing strictly ASCII-encoded values.
Function Name |
Meaning |
Example |
regexm(s,p) |
1 if string s matches pattern p, 0 otherwise |
regexm(zip5,"^[0-9][0-9][0-9][0-9][0-9]$") |
regexr(s,p,r) |
Replace all matches to pattern p with replacement r |
regexr(filename,"\.(txt|csv|tsv)","") |
regexs(n) |
The nth (in [1,9]) pattern match from the last regexm call |
|
The second set are the new functions designed for Unicode-encoded values.
Function Name |
Meaning |
Example |
ustrregexm(s,p) |
1 if string s matches pattern p, 0 otherwise |
|
ustrregexm(s,p,b) |
Call ustrregexm with case-insensitivity if b is 1 |
|
ustrregexrf(s,p,r) |
Replace the first match to pattern p with replacement r |
|
ustrregexrf(s,p,r,b) |
Call ustrregexrf with case-insensitivity if b is 1 |
|
ustrregexra(s,p,r) |
Replace all matches to pattern p with replacement r |
|
ustrregexra(s,p,r,b) |
Call ustrregexrf with case-insensitivity if b is 1 |
|
ustrregexs(n) |
The nth pattern match from the last ustrregexm call |
|
For ustrregexs, note that the 0th match is them entire original string if it matched the pattern at all.
See here for details on Stata's regular expressions syntax.
Encoding and Decoding Functions
There are several function meant for encoding or decoding string data.
Function Name |
Meaning |
tobytes(s) |
|
tobytes(s,n) |
|
ustrfix(s) |
|
ustrfix(s,r) |
|
ustrfrom(s,e,m) |
|
ustrinvalidcnt(s) |
|
ustrnormalize(s,m) |
|
ustrto(s,e,m) |
|
ustrtohex(s) |
|
ustrtohex(s,n) |
|
ustrunescape(s) |
|
Locale Name Functions
Several of the above string functions take an optional locale name argument. This creates the need for more functions that can parse and validate locale names.
Function Name |
Meaning |
collatorlocale(l,t) |
|
collatorversion(l) |
|
wordbreaklocale(s,n) |
|
Stata Name Functions
Stata offers several functions for generating a safe name, as for use in generating variables or macros.
Function Name |
Meaning |
strtoname(s) |
Create a Stata 13 name |
ustrtoname(s) |
Create a modern Stata name |
Both of these functions are variadic. If the second argument is a 1, and then if the first character is numeric, the returned name is prefixed with an underscore character.