/sys$common/syshlp/TPUHELP.HLB  —  TRANSLATE
  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.
Close Help