# Directives

TRANSLATE | Translate Contents of Variable

## Formats

1. | Translate from String: | TRANSLATE var$,table$,offset
2. | Translate from Variable to Variable: | TRANSLATE to_var$,translate_tbl$,offset
3. | Translate Single Character: | TRANSLATE var$,to_char$,from_char$
4. | Translate Character via Hex Value: | TRANSLATE var$,hex_string$

Where:

from_char$ | Character to be searched for and replaced.
translate_tbl$ | Conversion table to be used as the new value(s) in the translation. String expression.
hex_string$ | Formatted hex string indicating characters and replacement characters.
offset | Base value to subtract from the characters in the variable to calculate the offset into the translate table during conversion. Numeric expression.
table$ | Conversion table to be used as the new value(s) in the translation. String expression.
to_char$ | New character to replace the original from_char$. All instances of the from_char$ in the var$ string are replaced with the to_char$.
to_var$ | Variable in which the translation is performed. Starting at the offset, to_var$ receives the translation of its own old values to the corresponding new values (from the table or from_var$ string).
var$ | String variable to be translated.

## Description

Use the TRANSLATE directive to convert/translate a string variable on a character-by-character basis using a conversion table or value. Use this directive to convert data from one character set to another (e.g. ASCII to EBCDIC).

## Format 1

Translate from String
TRANSLATE var$,table$,offset

Use this format to replace a character in a string variable with a character from a table string/expression. PxPlus performs the conversion by taking each character from the variable, subtracting the offset from its binary value, and using the result as an offset into the table whose character will then replace the original character in the variable.

When PxPlus computes the offset into the table, it will treat an offset of zero as the first character from the table. If the result of the subtraction is an offset that exceeds the length of the table, then no conversion takes place for the character.

Example:

> 0110 let A$="ABCD"
> 0130 translate A$,"ZYXWVUTS",dec("A")
> 0140 print A$
> ->goto 110
> ->run
> ZYXW

## Format 2

Translate from Variable to Variable
TRANSLATE to_var$,from_var$,offset

Use this format to copy the character-by-character values from one variable to another variable up to the length of the shorter variable. In this format, PxPlus also uses a numeric starting offset into the target table.

Example:

> 0110 let A$="1234567890"
> 0120 let B$="ABCD"
> 0130 translate A$,B$,dec("3")
> 0140 print A$
> ->goto 110
> ->run
> 12ABCD7890

## Format 3

Translate Single Character
TRANSLATE var$,to_char$,from_char$

Use this format to replace all instances of a given character in a string variable with another character.

Example:

> STRVAR$="ABxDEFG xxx"
> translate STRVAR$,"C","x"
> print STRVAR$
> ->run
> ABCDEFG CCC

## Format 4

Translate Character via Hex Value
TRANSLATE var$,hex_string$

Use this format to replace a single character in a string variable with designated character(s).

hex_string$ consists of a string of hexadecimal values indicating the character to be replaced, the number of characters to replace that character, and then the replacement character(s).

Example:

> translate R$,$0A020D0A$

The line-feed character ($0A$) will be replaced by two ($02$) characters: carriage-return and line-feed ($0D0A$). Multiple sets of characters may be translated by extending the translation string:

> translate R$,$0A020D0A090120$

In this case, the line-feed character ($0A$) will be replaced by the two ($02$) carriage-return and a line-feed characters ($0D0A$), and the tab character ($09$) will be replaced by one ($01$) space character ($20$).