TRANSLATE
Substitutes one set of specified characters for another set in text.
Invokes the RTL procedure STR$TRANSLATE to replace one or more
characters. For more information, see the VMS System Routines volumes.
Optionally, returns a string, range, or buffer containing the changed
text.
Syntax
[returned_buffer |
returned_range |
returned_string := ] TRANSLATE (buffer | range | string1}, string2,
string3 [, {IN_PLACE | NOT_IN_PLACE}])
Parameters
buffer A buffer in which one or more characters are to be
replaced. Note that you cannot use the keyword
NOT_IN_PLACE if you specify a buffer for the first
parameter.
range A range in which one or more characters are to be
replaced. Note that you cannot use the keyword
NOT_IN_PLACE if you specify a range for the first
parameter.
string1 A string in which one or more characters are to be
replaced. If a return value is specified, the
substitution is performed in the returned string.
If you specify IN_PLACE for the third parameter,
TRANSLATE makes the specified change to the string
specified in the first parameter. TRANSLATE has no
effect on string constants.
string2 The string of replacement characters.
string3 The literal characters within the text specified by
parameter1 that are to be replaced.
IN_PLACE A keyword directing DECTPU to make the indicated
change in the buffer, range, or string specified.
This is the default.
NOT_IN_PLACE A keyword directing DECTPU to leave the specified
string unchanged and return a string that is the
result of the specified translation. You cannot use
NOT_IN_PLACE if the first parameter is specified as
a range or buffer. To use NOT_IN_PLACE, you must
specify a return value for TRANSLATE.
returned_buffer A variable of type buffer pointing to the buffer
containing the modified text, if you specify a
buffer for the first parameter. The variable
"returned_buffer" points to the same buffer pointed
to by the buffer variable specified as the first
parameter.
returned_range A range containing the modified text, if you specify
a range for first parameter. The returned range
spans the same text as the range specified as a
parameter, but they are two separate ranges. If you
subsequently change or delete one of the ranges,
this has no effect on the other range.
returned_string A string containing the modified text, if you
specify a string for the first parameter.
Comments
TRANSLATE searches the text specified by parameter1 for the characters
specified by parameter3. When a character specified by parameter3 is
found, the character at the same string offset in parameter2 is
substituted into the text.
Examples
1. TRANSLATE (main_buffer, "X", "x");
Replaces all lowercase x's in the main buffer with uppercase X's.
2. The following statements show how the word "darn" could be replaced
with "da*n" during an interactive session. Suppose the following
text is written in a buffer and that the variable "the_range" spans
this text:
This darned wind is a darned nuisance, darn it!
The following statement assigns to "the_string" the characters in
"the_range":
the_string := STR (the_range)
The following statement assigns to "translated_string" the text
that results when an asterisk is substituted for each "r":
translated_string := TRANSLATE (the_string, "*", "r", NOT_IN_PLACE)
The variable "translated_string" then contains the following text:
This da*ned wind is a da*ned nuisance, da*n it!
Note that if the text contained other r's, they would also replaced
by asterisks.