FOLD

Caché MultiValue Basic Reference

FOLD

Server:docs.intersystems.com

Instance:CACHE20091

User:UnknownUser


	[Documentation] > [Development References] > [MultiValue Basic Reference] > [MultiValue Basic Functions] > [FOLD]		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:

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

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

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"