$TRANSLATE

Returns a new string that consists of character-for-character replacement of a source string.

Synopsis

$TRANSLATE(string,identifier,associator)
$TR(string,identifier,associator)

Parameters

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	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 — 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 character-for-character replacement 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 parameter one character at a time. It compares each character in the input string with each character in the identifier parameter. If $TRANSLATE finds a match, it performs one of the following actions on that character:

The two-parameter form of $TRANSLATE removes those characters in the identifier parameter from the returned string.
The three-parameter form of $TRANSLATE replaces the identifier character(s) found in the string with the positionally corresponding character(s) from the associator parameter and returns the resulting string. Replacement is performed on a character, not a string, basis. If the identifier parameter contains fewer characters than the associator parameter, the excess character(s) in the associator parameter are ignored. If the identifier parameter contains more characters than the associator parameter, the excess character(s) in the identifier parameter are deleted in the output string.

$TRANSLATE is case-sensitive.

The string, identifier, and associator parameters are normally specified as quoted strings. If the value of one of these parameters is purely numeric, string quotes are not required; however, because Caché will convert the parameter value to a canonical number before supplying the value to $TRANSLATE, this usage is not recommended.

$TRANSLATE and $REPLACE

$TRANSLATE performs character-for-character matching and replacement. $REPLACE performs string-for-string matching and replacement. $REPLACE can replace a single specified substring of one or more characters with another substring, or remove multiple instances of a specified substring. $TRANSLATE can replace multiple specified characters with corresponding specified replacement characters.

$TRANSLATE matching is always case-sensitive; $REPLACE matching is case-sensitive by default, but can be invoked as not case-sensitive. $TRANSLATE always replaces all matches in the source string; $REPLACE can specify the starting point for matching and/or the number of replacements to perform.

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-parameter $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-parameter $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-parameter $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.