FOLD

Divides a string into substring units separated by a delimiter.

Synopsis

FOLD(string,length[,delim])

Arguments

string	An expression that resolves to a string or numeric expression.
length	An expression that resolves to 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 — An expression that resolves to 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:

If a space character is encountered within length number of characters, FOLD replaces the space character with a field mark delimiter, then begins counting length characters from that point. If there are multiple space characters within length, FOLD only replaces the last space character prior to reaching the length character count. If the length character is a space character, FOLD replaces it with a field mark delimiter.
If a space character is not encountered within length number of characters, FOLD inserts a field mark delimiter, then begins counting length characters from that point.

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, 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:

FOLD.DELIM.VM sets the delimiter character to @VM (value mark) rather than @FM (field mark). This provides compatibility with D3 applications.
FOLD.LEN.1 sets the behavior for a length of less than 1, by having FOLD default to a length of 1. Otherwise, a value less than 1 (for example, 0, .5, or –1) returns the empty string. This provides compatibility with jBASE applications.

Examples

The following example uses the FOLD function to return a string delimited by Field Marks (þ) 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"