CONVERT - Caché MultiValue Basic Reference

docs.intersystems.com

Caché MultiValue Basic Reference

CONVERT

[Home] [Back] [Next]

InterSystems: The power behind what matters

MultiValue Features of Caché > Caché MultiValue Basic Reference > Caché MultiValue Basic Commands > CONVERT

Search:

Replaces single characters in a string.

Synopsis

CONVERT charsout TO charsin IN string

Arguments

charsout	One or more characters to be replaced. Any expression that resolves to a valid string or numeric.
charsin	The character or characters to be inserted in place of the corresponding characters in charsout. Any expression that resolves to a valid string or numeric.
string	The string in which character substitutions are made. An expression that resolves to a valid string. string may be a dynamic array. string accepts a single dynamic array reference (A<i>), a single substring reference (A[s,l]), or a substring reference nested inside a dynamic array reference (A<i>[s,l]).

Description

The CONVERT statement edits the value of string by replacing all instances of single characters in charsout with single characters from charsin. CONVERT performs a character-for-character substitution. Matching of characters is case-sensitive.

CONVERT can be used as follows:

To remove all instances of a character from a string, specify the character to be removed in charsout and a null string in charsin. For example, to remove the # character from mystring: CONVERT "#" TO "" IN mystring
To replace all instances of a character in a string with another character, specify the character to be replaced in charsout and the replacement character in charsin. For example, to replace all instances of the # character with the * character in mystring: CONVERT "#" TO "*" IN mystring
To replace all instances of a list of single characters with corresponding other single characters, specify those characters to be replaced in charsout and the corresponding replacement characters in charsin. For example, to replace all instances in mystring of the each lowercase letter a, b, c, and d with the corresponding uppercase letter: CONVERT "abcd" TO "ABCD" IN mystring
To both replace some single characters and remove others, specify those characters to be replaced or removed in charsout. First specify those to be replaced, then those to be removed. Specify the corresponding replacement characters in charsin, and nothing for the characters to be removed. For example, to replace all instances of + with &, and to remove all instances of # in mystring: CONVERT "+#" TO "&" IN mystring

The value of charsout and charsin can be a string or a numeric. If numeric, the value is converted to canonical form (plus sign, leading and trailing zeros removed) before performing the CONVERT operation.

If charsout contains more characters than charsin, the unpaired characters are deleted from string. If charsin contains more characters than charsout, the unpaired characters are ignored and have no effect.

Note:

CONVERT performs single character one-for-one substitution for all instances in a string. The CHANGE function performs substring replacement, and can specify how many instances to replace and where to begin replacement.

The CONVERT statement and the CONVERT function perform the same operation, with the following difference: the CONVERT statement changes the supplied string; the CONVERT function returns a new string with the specified changes and leaves the supplied string unchanged.

Examples

The following example illustrates use of the CONVERT statement in converting a string to a dynamic array by replacing the # character with a Value Mark level delimiter character:

cities="New York#Chicago#Boston#Los Angeles"
CONVERT "#" TO CHAR(253) IN cities
PRINT cities