ULENGTH

Start of changeThe ULENGTH function returns an integer value that is equal to the number of UTF-8 or UTF-16 characters in a character data item argument that contains UTF-8 or UTF-16 data.End of change

The function type is integer.

Format

Read syntax diagramSkip visual syntax diagramFUNCTION ULENGTH(argument-1)
argument-1
Must be of class Start of changealphabetic, alphanumeric, or nationalEnd of change. Start of changeargument-1 must contain valid UTF-8 or UTF-16 encoded characters:End of changeStart of change
  • If argument-1 is of class alphabetic or alphanumeric, it must contain valid UTF-8 data.
  • If argument-1 is of class national, it must contain valid UTF-16 data.
End of change

The returned value is the number of UTF-8Start of change or UTF-16End of change characters in argument-1.

Example 1

IfStart of change argument-1 is a UTF-8 encoded item andEnd of change the UTF-8 argument contains composed characters, the combining characters are counted individually in determining the length. For example, when encoded in UTF-8, the Unicode character ä can be x'C3A4' or x'61CC88'. With either of the UTF-8 characters as argument-1, the returned values of the ULENGTH function are different. See the following table for details.
Table 1. ULENGTH function of character ä
Character Unicode encoding UTF-8 encoding Returned value of the ULENGTH function
ä
U+00E4
(precomposed form,
latin small letter a with diaeresis)
x'C3A4' 1
U+0061 + U+0308
(canonical decomposition,
latin small letter a + combining diaeresis)
x'61CC88' 2
Start of change

Example 2

If argument-1 is a national data item that contains UTF-16 data and argument-1 contains surrogate pairs, each pair of low and high surrogates will be counted as one UTF-16 character. For example, if B is a national item that contains the UTF-16 value x'005400F6006200750072D858DC6B0073' ('Töber𦁫s'), the returned value from ULENGTH(B) will be 7. Character 𦁫 = X'D858DC6B' is counted as one UTF-16 character.

End of change