String manipulation functions                                  [STB-13: dm13.1]
-----------------------------

	^replstr  "^oldstr^" "^newstr^"^ # varname [^if^ exp] [^in^ range]

	^replword "^oldwrd^" "^newwrd^"^ # varname [^if^ exp] [^in^ range]


	^trimblnk^ varname [^if^ exp] [^in^ range]

	^mixcase^  varname [^if^ exp] [^in^ range]


	^exchstr^  varname varname [^if^ exp] [^in^ range]


	^splitstr^ newvar varname [character]


	^minlen^   [^str^]# varlist


Description
-----------

^replstr^ replaces, in each observation, up to # occurrences of oldstr with 
newstr.  ^replword^ replaces, in each observation, up to # occurrences of
oldwrd with newrd.  # may be 0, 1, 2, ..., or ^.^ (missing value).  If # is 
0, no action is taken.  If # is ^.^, all occurrences are replaced.


^trimblnk^ removes all leading and trailing blanks and removes all embedded 
multiple blanks.


^mixcase^ changes varname to be mostly lower case with the beginning of each
word capitalized.


^exchstr^ exchanges the contents of two string variables.


^splitstr^ parses varname on character (default " "), moves the first token
into newvar, and eliminates the token from the original varname.


Description, concluded
----------------------

^minlen^ recasts each variable in varlist to ^str^# if ^str^# is longer than
how the variable is currently stored; otherwise, it takes no action.








					Examples follow ...










Examples:  ^replstr^
------------------


To change every `(' and ')' to `[' and `]' in variable desc:

	. ^replstr "(" "[" . desc^
	. ^replstr ")" "]" . desc^

To change only the first occurrence in each observation:

	. ^replstr "(" "[" 1 desc^
	. ^replstr ")" "]" 1 desc^



To change `&' to "and" with blanks around it:

	. ^replstr "&" " and " . desc^

The storage type of string variable desc (^str^#) will be made longer if nec-
essary.  See example of ^trimblnk^ below to now remove possible multiple blanks.


Examples:  ^replstr^, concluded
-----------------------------

To remove all occurrences of the character `#' in desc:

	. ^replstr "#" "" . desc^


Examples:  ^replword^
-------------------

A word is a special case of string:  a word either has blanks around it or is
at the beginning or end of a string.  Changing all occurrences of string "is"
to "are" in "this is a test" results in "thare are a test"; changing the word
"is" to "are" results in "this are a test".

To change all occurrences of the word "Mr" to "Mr." in name:

	. ^replword "Mr" "Mr." . name^

This will not change "Mr." to "Mr.." because "Mr." is not equivalent to the
word "Mr".


Example:  ^trimblnk^
------------------

To remove all multiple blanks in variable name:

	. ^trimblnk name^

This is not equivalent to

	. ^replstr  "  "   " "  .  name^  (there are 2 blanks in the 1st
                                         pair of quotes and one in the second)

because ^replstr^ is not recursive (a sequence of three blanks would become two
after ^replstr^).


To change `&' to "and" with blanks around it and then remove the (possibly)
introduced) multiple blanks in variable desc:

	. ^replstr "&" " and " . desc^
	. ^trimblnk desc^



Example:  ^mixcase^
-----------------

To capitalize the first letter of each word and lowercase the rest in variable
name:

	. ^mixcase name^

If the first observation of name contained "MR. robert E. SMITH", it would now
contain "Mr. Robert E. Smith".



Example:  ^exchstr^
-----------------

To exchange the contents of the two string variables first and last wherever
variable swap is not zero:

	. ^exchstr first last if swap~=0^

The storage types (^str^#) of first and last will be changed if necessary.


Example:  ^splitstr^
------------------

You have a string variable pname; you wish to remove the first word (defined
as the characters up to a blank) and put those characters in a new string 
variable called first:

	. ^splitstr first pname " "^

If the first observation of pname was "Roger E. Smith", the first observation
of first now contains "Roger" and pname now contains "E. Smith".


Example:  ^minlen^
----------------

You have a string variable ttl.  You are about to replace its contents with
"Doctor" everywhere it contains "Dr.".  This is occurring in a program you have
written and you are not sure that string variable ttl is of sufficient width
to hold the word "Doctor":

	. ^minlen 6 ttl^
	. ^replace ttl="Doctor" if ttl=="Dr."^


Example:  ^minlen^, concluded
---------------------------

More generally, you have two string variables ttl1 and ttl2.  You are about
to replace ttl1 with ttl2 everywhere variable assign is not zero.  You want 
to be sure that ttl1 is long enough to contain what might come from ttl2 and,
afterwards, you want to make the variable ttl2 consume as little memory as
possible:

	. ^local stype : type ttl2^
	. ^minlen `stype' ttl1^
	. ^replace ttl1 = ttl2 if assign~=0^
	. ^compress ttl1^


Also see
--------

    STB:  dm13.1 (STB-13)
On-line:  ^help^ for ^extrname^