$TRANSLATE (ObjectScript)
Synopsis
$TRANSLATE(string,identifier,associator)
$TR(string,identifier,associator)
Arguments
Argument | Description |
---|---|
string | The source string. It can be a numeric value, a string literal, the name of a variable, or any valid ObjectScript expression. |
identifier | Search characters. A string consisting of one or more characters to search for in string. It can be a numeric value, a string literal, the name of a variable, or any valid ObjectScript expression. |
associator | Optional — Replacement characters. A string consisting of one or more replacement characters that correspond positionally to each character in identifier. It can be a numeric value, a string literal, the name of a variable, or any valid ObjectScript expression. |
Description
The $TRANSLATE function returns a new string that consists of a one or more character-for-character replacements of the source string. A $TRANSLATE operation can replace multiple different characters, but it can only replace a single character with (at most) a single character. It processes the string argument one character at a time. It compares each character in the input string with each character in the identifier argument. If $TRANSLATE finds a match, it performs one of the following actions on that character:
-
The two-argument form of $TRANSLATE removes those characters in the identifier argument from the returned string.
-
The three-argument form of $TRANSLATE replaces the identifier character(s) found in the string with the positionally corresponding character(s) from the associator argument and returns the resulting string. Replacement is performed on a character, not a string, basis. If the identifier argument contains fewer characters than the associator argument, the excess character(s) in the associator argument are ignored. If the identifier argument contains more characters than the associator argument, the excess character(s) in the identifier argument are deleted in the output string.
$TRANSLATE is case-sensitive.
The string, identifier, and associator arguments are normally specified as quoted strings. If the value of one of these arguments is purely numeric, string quotes are not required; however, because InterSystems IRIS will convert the argument value to a canonical number before supplying the value to $TRANSLATE, this usage is not recommended.
Examples
The following example shows two ways of using $TRANSLATE. The first $TRANSLATE does not change the input string value. The second $TRANSLATE changes the input string value by setting it equal to the function’s return value:
SET str="The quick brown fox"
SET newstr=$TRANSLATE(str,"qbf","QBF")
WRITE "source string: ",str,!,"new string: ",newstr,!!
// creates a new string, does not change str value
SET str=$TRANSLATE(str,"qbf","QBF")
WRITE "revised string: ",str
// creates a new string and replaces str with new string value
In the following example, a two-argument $TRANSLATE removes Numeric Group Separators based on the setting for the current locale:
AppropriateInput
SET ds=##class(%SYS.NLS.Format).GetFormatItem("DecimalSeparator")
IF ds="." {SET x="+1,462,543.33"}
ELSE {SET x="+1.462.543,33"}
TranslateNum
WRITE !,"before translation ",x
SET ngs=##class(%SYS.NLS.Format).GetFormatItem("NumericGroupSeparator")
IF ngs="," {SET x=$TRANSLATE(x,",") }
ELSEIF ngs="." {SET x=$TRANSLATE(x,".") }
ELSEIF ngs=" " {SET x=$TRANSLATE(x," ") }
ELSE {WRITE "Non-standard NumericGroupSeparator:", ngs
RETURN }
WRITE !,"after translation ",x
In the following example, a three-argument $TRANSLATE replaces various Date Separator Characters with slashes. Note that the associator must specify “/” as many times as the number of characters in identifier:
SET x(1)="06-23-2014"
SET x(2)="06.24.2014"
SET x(3)="06/25/2014"
SET x(4)="06|26|2014"
SET x(5)="06 27 2014"
FOR i=1:1:5{
SET x(i)=$TRANSLATE(x(i),"- .|","////")
WRITE "x(",i,") :",x(i),!
}
In the following example, a three-argument $TRANSLATE “simplifies” Spanish to basic ASCII by replacing accented letters with non-accented letters and removing the question and exclamation sentence prefix punctuation:
SET esp="¿Sabes lo que ocurrirá en el año 2016?"
WRITE "Spanish:",!,esp,!
SET iden=$CHAR(225)_$CHAR(233)_$CHAR(237)_$CHAR(241)_$CHAR(243)_$CHAR(250)_$CHAR(161)_$CHAR(191)
SET asso="aeinou"
WRITE "Identifier: ",iden,!
WRITE "Associator: ",asso,!
SET spanglish=$TRANSLATE(esp,iden,asso)
WRITE "Spanglish:",!,spanglish
Needless to say, this is not a recommended conversion for use on actual Spanish text.
$TRANSLATE, $REPLACE, and $CHANGE
$TRANSLATE performs character-for-character matching and replacement. $REPLACE and $CHANGE perform string-for-string matching and replacement. $REPLACE and $CHANGE can replace a single specified substring of one or more characters with another substring of any length. $TRANSLATE can replace multiple specified characters with corresponding specified replacement characters. All three functions can remove matching characters or substrings — replacing with null.
$TRANSLATE matching is always case-sensitive. $REPLACE matching is case-sensitive by default, but can be invoked as not case-sensitive. $CHANGE is always case-sensitive.
$TRANSLATE always replaces all matches in the source string. $REPLACE and $CHANGE can specify the starting point for matching and/or the number of replacements to perform. $REPLACE and $CHANGE differ in how they define the starting point.