' TRANS$(0.0)  Translate Character String Symbols          05/30/1997-02/03/2010
' ------------------------------------------------------------------------------
' Copyright (C) 1997-2010 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.

' 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$)

' 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