ADDASCII()

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"

      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"

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()