UPREV8(

General Form:

UPREV8(strexpr, numexpr, numexpr (Optional))

Where:

strexpr	= an alphanumeric expression corresponding to a UTF-8 encoded string
numexpr	= a byte index into the string corresponding to the first byte of the current character. Counted from 1.
numexpr (Optional)	= the number of characters to retreat. If this is not specified, the function will return the position of the character immediately before the current character. Must be greater than 0.

The UPREV8( numeric function is used to return the byte index of the first byte of the previous character in a string expression which is presumed to represent a UTF-8 encoded Unicode string. In UTF-8 chracters are encoded as one, two or three byte sequences. The second argument must contain the byte index of the first byte of the current character. The third (optional) argument specifies how many characters to move backwards. If no argument is supplied, UNEXT8 will return the byte index of the first byte of the character immediately preceding the current character. If a larger argument is supplied, the byte index of the first byte of preceding characters will be returned. Any argument less than 1 will cause an error. The UPREV8( function is valid wherever a numeric function is legal.

Note that any trailing spaces at the end of the string can be returned by UPREV8( if called with appropriate arguments.

The function will return 0 if if the string does not contain enough characters to complete the request. This can occur either by calling it for the first character of the string, or using the optional argument to make it retreat beyond the start of the string.

It will return -1 if there is a problem with the current position passed in for the second argument. This can be the result of:

Current position is less than 1 (i.e. before the first byte in the string)
Current position is greater than the number of bytes in the string
Current position corresponds to a byte that is not the first byte of a character

The function will return -2 in the case of invalid UTF-8. In versions of KCML before 7.13, the function would return -1.

Example:

REM must be run with the USING_UTF8 environment variable set to true
DIM a$="$€£"
IF (a$ <> HEX(24E282ACC2A3)) THEN PANIC
REM these calls are made with prior knowledge of the starting positions of the characters
IF (UPREV8(a$,5)) <> 2 THEN PANIC
IF (UPREV8(a$,2)) <> 1 THEN PANIC
IF (UPREV8(a$,5,2)) <> 1 THEN PANIC