/* $DOC$
   $NAME$
      AddAscii()
   $CATEGORY$
      CT3 string functions
   $ONELINER$
      Add an integer value to an ascii value of a string
   $SYNTAX$
      AddAscii( <[@]cString>, <nValue>, [<nPosition>], [<lCarryOver>] ) --> cString
   $ARGUMENTS$
      <[@]cString>   is the string that should be edited
      <nValue>       is a integer value that should be added to the
                     ASCII value of the character at the <nPosition>th position
      [<nPosition>]  is the position of the character that should be edited.
                     If not supplied, the last character of <[@]cString> is
                     edited.
      [<lCarryOver>] NEW: is set to .T. if the substring from position 1 to
                     position <nPosition> should be treated as an integer
                     written to the base 256. Thus, the addition of <nValue>
                     can affect to whole substring (see EXAMPLES).
                     Default is .F., the original behaviour of this function.
   $RETURNS$
      The edited string is returned. The return value can be suppressed by
      using the CSetRef() function. The string must then be passed by
      reference [@].
   $DESCRIPTION$
      AddAscii() can be used to add or subtract integer values from
      ASCII values in a string. The new <lCarryOver> parameter allows
      to treat a string as an integer written to the base 256. Since
      <nValue> is limited to a signed long, only substrings 4 characters
      long can be affected by one AddAscii() call.
      If the length of <[@]cString> is smaller than <nPosition>, the
      string remains unchanged. The same happens, if uninterpretable
      parameters are passed to this function.
   $EXAMPLES$
      // Add 32 to the ASCII value of the character at the last position
      // in the string

      ? AddAscii( "SmitH", 32 ) // --> "Smith"
   $STATUS$
      Ready
   $COMPLIANCE$
      AddAscii() is compatible with CT3's AddAscii().
      A new, 4th, parameter has been added who defaults to the original
      behaviour if omitted.
   $PLATFORMS$
      All
   $FILES$
      Library is hbct.
   $SEEALSO$
      CSetRef()
   $END$
 */