ENTMF 

The USUPPLEMENTARY Function

The USUPPLEMENTARY function returns an integer value that is equal to the index of the first Unicode supplementary character in a character string argument that is encoded in UTF-8 or UTF-16.

A Unicode supplementary character is a character above U+FFFF, that is, a character outside of the Basic Multilingual Plane (BMP). These characters are encoded in UTF-16 with a surrogate pair (two 16-bit code units), or are encoded in UTF-81 with a 4-byte representation.

The function type is integer.

General Format

Arguments

  1. Argument-1 must be alphabetic, alphanumeric, national, or UTF-8.
  2. Argument-1 must contain valid UTF-8 or UTF-16 data based on its class:
    • If argument-1 is of class alphabetic, alphanumeric, or UTF-8, it must contain valid UTF-8 data.
    • If argument-1 is of class national, it must contain valid UTF-16 data.

Returned Value

  1. The returned value is an integer, which differs based on the argument-1 value:
    • If argument-1 contains no supplementary characters, the returned value is zero.
    • If argument-1 is of class alphabetic, alphanumeric, or UTF-8, the returned value is the byte position of the first UTF-8 supplementary character in argument-1.
    • If argument-1 is of class national, the returned value is the index, in UTF-16 encoding units, of the first UTF-16 supplementary character in argument-1.
  2. Results can be unpredictable if the contents of argument-1 are not valid Unicode (UTF-8 or UTF-16, depending on class).
Parent topic: Definitions of Functions
Related reference
The ULENGTH Function
The UPOS Function
The USUBSTR Function
The UVALID Function
The UWIDTH Function