Caché ObjectScript Reference
$TRANSLATE
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

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
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:
$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.
See Also