/*
 * $Id: addascii.txt 15102 2010-07-14 12:48:39Z vszakats $
 */

/*  $DOC$
 *  $FUNCNAME$
 *      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"
 *  $TESTS$
 *      addascii ("0000", 1, 1) == "1000"
 *      addascii ("0000", 1) == "0001"
 *      addascii ("AAAA", -255, 1) == "BAAA"
 *      addascii ("AAAA", -255) == "AAAB"
 *      addascii ("AAAA", 1, 2, .T.) == "ABAA"
 *      addascii ("AAAA", 257, 2, .T.) == "BBAA"
 *      addascii ("AAAA", 257, 2, .F.) == "ABAA"
 *      addascii ("AAAA", 258,, .T.) == "AABC"
 *      addascii ("ABBA", -257, 3, .T.) == "AAAA"
 *  $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$
 *      Source is addascii.c, library is ct3.
 *  $SEEALSO$
 *      CSETREF()
 *  $END$
 */
