Home|Management Portal|Index
Caché MultiValue Basic Reference
FOLD
« »
   
Server:docs.intersystems.com
Instance:CACHE20091
User:UnknownUser
 
-
Go to:
Search:    

Divides a string into substring units separated by a delimiter.
Synopsis
FOLD(string,length[,delim])
Arguments
string Any valid string or numeric expression.
length An integer specifying the maximum number of characters per substring. If you specify a fractional value, FOLD truncates it to its integer portion. By default, any value less than 1 returns the empty string (see Emulation section below).
delim Optional — The delimiter character to use. If omitted or set to the empty string ("") the default is @FM. This argument is provided for D3 compatibility. (Note that in D3 the default delimiter is @VM.)
Description
The FOLD function returns the specified string as a string divided into subunits by delimiter characters. This delimiter character by default is the @FM (also known as @AM) field mark character. FOLD places field mark delimiters as follows:
FOLD does not place a field mark delimiter before the first character or after the last character of string, unless the first or the last character is a space character. If the input string contains a field mark delimiter character, it is counted as an ordinary character. Note that because field mark delimiters replace spaces, but are inserted between non-space characters, the returned string can be vary from being the same length to being significantly longer than the input string.
FOLD counts characters, not bytes. You can use the LEN function to determine the number of characters in a string. You can use the LENS function to determine the number of characters in each delimited substring.
The string argument can be a quoted string or a numeric expression. If string is the empty string or an undefined variable, FOLD returns the empty string.
If length is equal to or larger than the number of characters in string, string is returned unchanged. If length is less than 1 or a non-numeric string, FOLD returns the empty string.
If string is a numeric expression, prior to performing the FOLD operation MVBasic performs all arithmetic operations and converts numbers to canonical form, with leading and trailing zeroes, a trailing decimal point, and all signs removed except a single minus sign. Numeric strings are not converted to canonical form.
Emulation
You can change the behavior of FOLD by setting the following $OPTIONS statement values:
Examples
In the following examples, comments indicate the field mark delimiter character by “^”.
The following example uses the FOLD function to return a string delimited into fixed-length units specified by length:
PRINT FOLD("InterSystems",3); ! Returns "Int^erS^yst^ems"
PRINT FOLD(+0099.900,2);       ! Returns "99^.9"
PRINT FOLD("+0099.900",2);      ! Returns "+0^09^9.^90^0"
The following example uses the FOLD function to return a string delimited according to the spaces in the source string and the length count:
PRINT FOLD("The quick brown fox",19); 
   ! Returns "The quick brown fox"
PRINT FOLD("The quick brown fox",16); 
   ! Returns "The quick brown^fox" 
   ! (delimiter replaces the last space;
   !  character 16 is a space)
PRINT FOLD("The quick brown fox",15); 
   ! Returns "The quick brown^fox" 
   ! (delimiter inserted at count=15)
PRINT FOLD("The quick brown fox",14); 
   ! Returns "The quick^brown fox"
   ! (delimiter replaces the last space prior
   !  to count=14) 
PRINT FOLD("The quick brown fox",5); 
   ! Returns "The^quick^brown^fox"
PRINT FOLD("The quick brown fox",4); 
   ! Returns "The^quic^k^brow^n^fox"
PRINT FOLD("The quick brown fox",3); 
   ! Returns "The^qui^ck^bro^wn^fox"
PRINT FOLD("The quick brown fox",2); 
   ! Returns "Th^e^qu^ic^k^br^ow^n^fo^x"
See Also