strmap(X;Y;Z;C)

Returns the given string with certain characters replaced or deleted according to a particular mapping.

Syntax

strmap(X;Y;Z;C)
bstrmap(X;Y;Z;C)

Input

Argument Type Description
X text The string on which to apply the function

A scalar value or the name of a column
Y text A string containing the set of characters (keys) used in the mapping

A scalar value or the name of a column
Z text A string containing the set of characters (values) used in the mapping

If Z is N/A, then matched characters are deleted from X.

A scalar value or the name of a column
C integer Specifies how the characters in X that are not in Y are handled in the result

If C is non-zero (including N/A), it is treated as if it were 1.

Return Value

Returns the text value corresponding to the string X with each character from the string Y replaced by the character at the corresponding position in Z.
Note: If Y and Z are of different lengths, then the longer is truncated to the length of the shorter.
For those characters in X that are not found in Y:
  • If C=0, those characters are unchanged in the result.
  • If C=1, those characters are deleted in the result.

If X is N/A, then the result is N/A.

If Y is N/A:
  • If C=0, the result is X unchanged.
  • If C=1, the result is N/A.
If Z is N/A:
  • If C=0, those characters that are in Y are deleted in the result.
  • If C=1, those characters that are not in Y are deleted in the result.

Sample Usage

string key value not_in_key strmap(string;key;value;not_in_key)
'abstemiously' 'aeiouy' 'AEIOUY' 0 'AbstEmiOUslY'
'abstemiously' 'aeiouy' 'AEIOUY' 1 'AEIOUY'
'abstemiously' 'aeiouy' 'AEI' 0 'AbstEmIously'
'abstemiously' 'aei' 'AEIOUY' 1 'AEI'
'abstemiously' '' 'AEIOUY' 0 'abstemiously'
'abstemiously' '' 'AEIOUY' 1
'abstemiously' 'aeiouy' '' 0 'bstmsl'
'abstemiously' 'aeiouy' '' 1 'aeiouy'

Additional Information

  • strmap is Unicode (UTF-8) compliant and will work with Unicode or plain ASCII text fields.
  • If passed a string argument that is not legal Unicode, it will by default signal an error (configurable as a user preference).
  • A corresponding function bstrmap can be used with non-Unicode strings (e.g., binary or legacy encodings).