' TRANS$(0.0)  Translate Character String Symbols      05/30/1997-04/04/2002
' --------------------------------------------------------------------------
' Copyright (C) 1997-2002 by Vladimir Veytsel                  www.davar.net

' Type ---------------------------------------------------------------------

'    Function

' Description --------------------------------------------------------------

'    TRANS$ function returns the first parameter with its symbols translated
'    according to the rules specified by its other two parameters.

' Declaration --------------------------------------------------------------

'    DECLARE FUNCTION TRANS$(Strng$,Source$,Target$)

' Parameters ---------------------------------------------------------------

'    Strng$   - Source character string to be changed by translation
'    Source$  - Source symbols to be translated
'    Target$  - Target symbols for translation

' Value --------------------------------------------------------------------

'  - If specified string is EMPTY,
'       then empty string is returned to the point of invocation

'  - If specified string is   NOT empty and
'       source symbols are either empty or
'       not found within specified string,
'       THEN original string is returned to the point of invocation

'  - If specified string is NOT empty and
'       source symbols are found within specified string,
'       then result of replacement of every entry of source symbol
'            by corresponding (same position) target symbol
'            is returned to the point of invocation

' Note ---------------------------------------------------------------------

'    Since translation is in fact symbol-per-symbol replacement, Target$
'    parameter should have the SAME length as Source$ parameter.  If this is
'    not the case, the length of Target$ parameter gets adjusted to be equal
'    that of the Source$ parameter.  This is done either by truncating
'    Target$ parameter value, or padding it by blanks in order to match the
'    length of Source$ parameter value.

' Examples -----------------------------------------------------------------

'    TRANS$(""               ,"XYZ","*"  )=""
'    TRANS$("ABCDEF"         ,""   ,"*"  )="ABCDEF"
'    TRANS$("ABCDEF"         ,"XYZ","*"  )="ABCDEF"
'    TRANS$("XYZABCDEF"      ,"XYZ","xyz")="xyzABCDEF"
'    TRANS$("ABCXYZDEF"      ,"XYZ","xyz")="ABCxyzDEF"
'    TRANS$("ABCDEFXYZ"      ,"XYZ","xyz")="ABCDEFxyz"
'    TRANS$("XYZABCXYZDEFXYZ","XYZ","xyz")="xyzABCxyzDEFxyz"
'    TRANS$("XYZABCXYZDEFXYZ","XY" ,"xyz")="xyZABCxyZDEFxyZ"
'    TRANS$("XYZABCXYZDEFXYZ","XYZ",""   )="   ABC   DEF   "

' Start Function -----------------------------------------------------------

     DEFINT A-Z  ' All defaulted variables are integer

     FUNCTION TRANS$(Strng$,Source$,Target$) PUBLIC

' Check Special Cases (Translation is Impossible) --------------------------

     IF ((LEN(Strng$)=0) OR _
         (LEN(Source$)=0)) THEN
        TRANS$=Strng$
        EXIT FUNCTION
     END IF

' Adjust Target$ Value to Match the Length of Source$ Value ----------------

     Target.Str$=LEFT$(Target$+SPACE$(LEN(Source$)),LEN(Source$))

' Form and Return Function Value to the Point of Invocation ----------------

     Work.Strng$=Strng$
     REPLACE ANY Source$ WITH Target.Str$ IN Work.Strng$

     TRANS$=Work.Strng$

' Finish Function ----------------------------------------------------------

     END FUNCTION