{smcl}
{* 09Aug2010}{...}
{cmd:help lstrfun} {right:{hi: Dan Blanchette}}
{hline}

{title:Title}

{p2colset 8 23 2 1}
{p2col :{hi:lstrfun} {hline 2}}Modify long local macros that contain strings 
{p2colreset}{...}


{title:Syntax}

{p 8 16 2}
{cmd:lstrfun} {it:local_macro_name} [{cmd:,} {it:{help lstrfun##options:options}}]

{pstd}where {it:local_macro_name} is a valid name of either an existing local macro that will be modified or a 
valid name of a local macro that will be generated by {cmd:lstrfun}.  The strings being modified can be as long 
as the maximum {helpb limits:number of characters in a local macro} minus about 50 (which is about how many 
characters are used to submit {cmd:lstrfun}).
{p_end}

{pstd}
Only one local macro name can be submitted and only one option can be specified.
{p_end}

{marker options}{...}
{synoptset 36 tabbed}{...}
{synopthdr:options}
{synoptline}
{syntab:In these descriptions {it:string} is referring to the contents of the local macro:}

{synopt:{opt lower(macname)}} make string all {helpb f_lower:lowercase}.{p_end}
{synopt:{opt proper(macname)}} make string {helpb f_proper:proper} case.{p_end}
{synopt:{opt upper(macname)}} make string all {helpb f_upper:uppercase}.{p_end}
{synopt:{opt ltrim(macname)}} remove {helpb f_ltrim:leading blanks} from string.{p_end}
{synopt:{opt itrim(macname)}} replace multiple {helpb f_itrim:internal blanks} with a single blank in string.{p_end}
{synopt:{opt rtrim(macname)}} remove {helpb f_rtrim:trailing blanks} from string.{p_end}
{synopt:{opt substr(macname, pos, length)}} {helpb f_substr:cut string} from starting point for the specified length.{p_end}
{marker subinstr}{...}
{synopt:{opt subinstr(macname, "from", "to", n)}} {helpb f_subinstr:replace "from string" with "to string"} in the string for the 
                    specified number of occurrences.{p_end}
{marker subinword}{...}
{synopt:{opt subinword(macname, "from", "to", n)}} {helpb f_subinword:replace "from word" with "to word"} in the string for the 
                    specified number of occurrences.{p_end}
{synopt:{opt strdup(macname, n)}} {helpb mf_strdup:duplicate} the string the specified number of times.{p_end}
{synopt:{opt reverse(macname)}} {helpb reverse:reverse} the string.{p_end}
{synopt:{opt _substr(macname, "tosub", pos)}} {helpb mf__substr:substitutes} "tosub" into the string at the specified position.{p_end}

{break}
{syntab:{cmd:Submit a new local macro name to be generated when using these options since these options return numbers/codes:}}
{marker strlen}{...}
{synopt:{opt strlen(macname)}} returns the {helpb f_length:length} of the string.{p_end}
{synopt:{opt strpos(macname, "needle")}} returns the {helpb f_strpos:position} of the specified string.{p_end}
{synopt:{opt strmatch(macname, pattern)}} returns 1 if the string {helpb f_strmatch:matches} the specified pattern.{p_end}
{synopt:{opt soundex(macname)}} returns the {helpb f_soundex:soundex} code for the string.{p_end}
{synopt:{opt soundex_nara(macname)}} returns the {helpb f_soundex_nara:U.S. Census soundex} code for the string.{p_end}
{synopt:{opt indexnot("characters", macname)}} returns the position of the first character in the set of characters
               specified that is {helpb f_indexnot:not found} in the string, or it returns 0 if all characters in the set of 
               characters specified are found in the string.{p_end}
{synopt:{opt regexm(macname, pattern)}} returns either a 1 or a 0 if {helpb mf_regexm:regexm} finds the pattern in the macro.{p_end}
{synopt:{opt regexms(macname, pattern with groups defined, nth_group)}} returns the nth group if {helpb mf_regexm:regexm} finds the pattern in the macro.{p_end}
{synopt:{opt regexr(macname, pattern, what to replace)}} returns what is wanted to be replaced if {helpb mf_regexr:regexr} finds the pattern in the macro.{p_end}


{title:Description}

{pstd}
{cmd:lstrfun} allows you to modify local {helpb macro:macros} that contain strings using 
{helpb m4_string:Mata's string functions} which are not restricted to the {helpb limits:maximum length of strings} in Stata like
the normal {helpb string_functions:string functions} in Stata are limited.  If you are using Stata SE or Stata MP, then your
setting of {helpb maxvar:maxvar} affects the maximum {helpb limits:number of characters in a macro}.  The maximum number of 
characters in a macro is only 1,081,511 when {helpb maxvar:maxvar} is set to 32767.  When {helpb maxvar:maxvar} is set to 5000 
(the default value) then the maximum number of characters in a macro is 165,200.  The local macro submitted to {cmd:lstrfun} will 
be modified if it already exists or it will be created if it does not exist.  {cmd:lstrfun} can be very helpful when trying to 
modify {helpb label:value labels} and {helpb notes:notes} in Stata since {helpb label:value labels} and {helpb notes:notes} are 
allowed to have more characters than normal {helpb string_functions:string functions} are allowed to handle. The option 
{helpb lstrfun##strlen:strlen()} has an equivalent function in Stata's {helpb extended_fcn:extended macro functions}, but the 
options {helpb lstrfun##subinword:subinstr()} and {helpb lstrfun##subinword:subinword()} have similar functions in Stata's 
{helpb extended_fcn:extended macro functions} which do not allow you to specify a specific number of replacements to make. 
{p_end}

{pstd}
Local macro strings that are submitted in any of the options have to be enclosed in at least double quotes.  It is a good idea to 
enclose local macro strings in compound double {helpb quotes:quotes} in case the macro contains quotes.
{p_end}

{pstd}
The maximum number of characters submitted to an option of {cmd:lstrfun} in total cannot exceed the 
{helpb limits:maximum length of strings} in Stata minus about 50 (which is about how many characters are used to 
submit {cmd:lstrfun}).  The command {helpb file:file read} can create local macros with more characters than Stata allows. 
If you get the following error messages when submitting {cmd:lstrfun}, then the submitted macro has too many characters:
{p_end}

{phang}{cmd:unmatched quote}{p_end}
{phang}{search r(198):r(198);}{p_end}
{phang}{cmd:too many macros}{p_end}
{phang}{search r(920):r(920);}{p_end}
{phang}{cmd:command too long}{p_end}
{phang}{search r(1004):r(1004);}{p_end}

{pstd}
If you are using Stata SE or Stata MP, then increase your setting of {helpb maxvar:maxvar} since it affects the maximum 
{helpb limits:number of characters in a macro}.
{p_end}

{title:Examples of modifying local macros}
{pstd}It is a good idea to use {cmd:macval()} when submitting a macro so that if the submitted macro contains a
macro: {it:`something'} then it is left as is.{p_end}

{phang}{cmd:. lstrfun mvar, lower(`"`mvar'"')}{p_end}

{phang}{cmd:. lstrfun mvar, itrim(`"`macval(mvar)'"')}{p_end}

{phang}{cmd:. lstrfun mvar, substr(`"`mvar'"', 332, 3235)}{p_end}

{phang}{cmd:. lstrfun mvar, _substr(`"`macval(mvar)'"', "XX", 20345)}{p_end}

{phang}{cmd:. lstrfun mvar, regexr(`"`macval(mvar)'"', `"Geo(rgi)e.Boy"', "George's son")}{p_end}

{title:Examples of creating new local macros}

{phang}{cmd:. lstrfun new_mvar, strpos(`"`mvar'"', "needle in the haystack")}{p_end}

{phang}{cmd:. lstrfun new_mvar, strmatch(`"`mvar'"', "mat*me")}{p_end}

{phang}{cmd:. lstrfun new_mvar, strmatch(`"`macval(mvar)'"', `"`macval(mvar2)'"')}{p_end}

{phang}{cmd:. lstrfun new_mvar, indexnot("abcdef", `"`mvar'"')}{p_end}

{phang}{cmd:. lstrfun new_mvar, regexm(`"`macval(mvar)'"', `".*Georgie.Boy*"')}{p_end}

{phang}{cmd:. lstrfun new_mvar, regexms(`"`macval(mvar)'"', `".*Geo(rgi)e.Boy*"', 1)}{p_end}

{title:Author} 

{pstd}
Dan Blanchette {break}
The Carolina Population Center {break}
University of North Carolina - Chapel Hill, USA {break}
dan_blanchette@unc.edu{p_end}

{title:Note}
Useful suggestions and feedback by Nick Cox are gratefully acknowledged.


{title:Also see}

{psee}
Online: {helpb string_functions:string functions}, 
{helpb m4_string:Mata string manipulation functions}, 
and {helpb extended_fcn:extended macro functions}{p_end}