ICU 76.1: common/unicode/utf16.h File Reference

ICU 76.1 76.1

Macros
utf16.h File Reference

C API: 16-bit Unicode handling macros. More...

`#include <stdbool.h>`
`#include "unicode/umachine.h"`
`#include "unicode/utf.h"`

Go to the source code of this file.

## Macros
#define | U16_IS_SINGLE(c)
| Does this code unit alone encode a code point (BMP, not a surrogate)?
#define | U16_IS_LEAD(c)
| Is this code unit a lead surrogate (U+d800..U+dbff)?
#define | U16_IS_TRAIL(c)
| Is this code unit a trail surrogate (U+dc00..U+dfff)?
#define | U16_IS_SURROGATE(c)
| Is this code unit a surrogate (U+d800..U+dfff)?
#define | U16_IS_SURROGATE_LEAD(c)
| Assuming c is a surrogate code point (U16_IS_SURROGATE(c)), is it a lead surrogate?
#define | U16_IS_SURROGATE_TRAIL(c)
| Assuming c is a surrogate code point (U16_IS_SURROGATE(c)), is it a trail surrogate?
#define | U16_SURROGATE_OFFSET ((0xd800<<10UL)+0xdc00-0x10000)
| Helper constant for U16_GET_SUPPLEMENTARY.
#define | U16_GET_SUPPLEMENTARY(lead, trail)
| Get a supplementary code point value (U+10000..U+10ffff) from its lead and trail surrogates.
#define | U16_LEAD(supplementary)
| Get the lead surrogate (0xd800..0xdbff) for a supplementary code point (0x10000..0x10ffff).
#define | U16_TRAIL(supplementary)
| Get the trail surrogate (0xdc00..0xdfff) for a supplementary code point (0x10000..0x10ffff).
#define | U16_LENGTH(c)
| How many 16-bit code units are used to encode this Unicode code point? (1 or 2) The result is not defined if c is not a Unicode code point (U+0000..U+10ffff).
#define | U16_MAX_LENGTH 2
| The maximum number of 16-bit code units per Unicode code point (U+0000..U+10ffff).
#define | U16_GET_UNSAFE(s, i, c)
| Get a code point from a string at a random-access offset, without changing the offset.
#define | U16_GET(s, start, i, length, c)
| Get a code point from a string at a random-access offset, without changing the offset.
#define | U16_GET_OR_FFFD(s, start, i, length, c)
| Get a code point from a string at a random-access offset, without changing the offset.
#define | U16_NEXT_UNSAFE(s, i, c)
| Get a code point from a string at a code point boundary offset, and advance the offset to the next code point boundary.
#define | U16_NEXT(s, i, length, c)
| Get a code point from a string at a code point boundary offset, and advance the offset to the next code point boundary.
#define | U16_NEXT_OR_FFFD(s, i, length, c)
| Get a code point from a string at a code point boundary offset, and advance the offset to the next code point boundary.
#define | U16_APPEND_UNSAFE(s, i, c)
| Append a code point to a string, overwriting 1 or 2 code units.
#define | U16_APPEND(s, i, capacity, c, isError)
| Append a code point to a string, overwriting 1 or 2 code units.
#define | U16_FWD_1_UNSAFE(s, i)
| Advance the string offset from one code point boundary to the next.
#define | U16_FWD_1(s, i, length)
| Advance the string offset from one code point boundary to the next.
#define | U16_FWD_N_UNSAFE(s, i, n)
| Advance the string offset from one code point boundary to the n-th next one, i.e., move forward by n code points.
#define | U16_FWD_N(s, i, length, n)
| Advance the string offset from one code point boundary to the n-th next one, i.e., move forward by n code points.
#define | U16_SET_CP_START_UNSAFE(s, i)
| Adjust a random-access offset to a code point boundary at the start of a code point.
#define | U16_SET_CP_START(s, start, i)
| Adjust a random-access offset to a code point boundary at the start of a code point.
#define | U16_PREV_UNSAFE(s, i, c)
| Move the string offset from one code point boundary to the previous one and get the code point between them.
#define | U16_PREV(s, start, i, c)
| Move the string offset from one code point boundary to the previous one and get the code point between them.
#define | U16_PREV_OR_FFFD(s, start, i, c)
| Move the string offset from one code point boundary to the previous one and get the code point between them.
#define | U16_BACK_1_UNSAFE(s, i)
| Move the string offset from one code point boundary to the previous one.
#define | U16_BACK_1(s, start, i)
| Move the string offset from one code point boundary to the previous one.
#define | U16_BACK_N_UNSAFE(s, i, n)
| Move the string offset from one code point boundary to the n-th one before it, i.e., move backward by n code points.
#define | U16_BACK_N(s, start, i, n)
| Move the string offset from one code point boundary to the n-th one before it, i.e., move backward by n code points.
#define | U16_SET_CP_LIMIT_UNSAFE(s, i)
| Adjust a random-access offset to a code point boundary after a code point.
#define | U16_SET_CP_LIMIT(s, start, i, length)
| Adjust a random-access offset to a code point boundary after a code point.

## Detailed Description

C API: 16-bit Unicode handling macros.

This file defines macros to deal with 16-bit Unicode (UTF-16) code units and strings.

For more information see utf.h and the ICU User Guide Strings chapter (https://unicode-org.github.io/icu/userguide/strings).

Usage: ICU coding guidelines for if() statements should be followed when using these macros. Compound statements (curly braces {}) must be used for if-else-while... bodies and all macro statements should be terminated with semicolon.

Definition in file utf16.h.

## Macro Definition Documentation

## ◆ U16_APPEND

#define U16_APPEND | ( |  | s,
|  |  | i,
|  |  | capacity,
|  |  | c,
|  |  | isError )

Value:
UPRV_BLOCK_MACRO_BEGIN { \
if((uint32_t)(c)<=0xffff) { \
(s)[(i)++]=(uint16_t)(c); \
} else if((uint32_t)(c)<=0x10ffff && (i)+1<(capacity)) { \
(s)[(i)++]=(uint16_t)(((c)>>10)+0xd7c0); \
(s)[(i)++]=(uint16_t)(((c)&0x3ff)|0xdc00); \
} else /* c>0x10ffff or not enough space */ { \
(isError)=true; \
} \
} UPRV_BLOCK_MACRO_END
UPRV_BLOCK_MACRO_END
#define UPRV_BLOCK_MACRO_END
Defined as "while (false)" by default.
Definition umachine.h:156
UPRV_BLOCK_MACRO_BEGIN
#define UPRV_BLOCK_MACRO_BEGIN
Defined as the "do" keyword by default.
Definition umachine.h:147

Append a code point to a string, overwriting 1 or 2 code units.

The offset points to the current end of the string contents and is advanced (post-increment). "Safe" macro, checks for a valid code point. If a surrogate pair is written, checks for sufficient space in the string. If the code point is not valid or a trail surrogate does not fit, then isError is set to true.

Parameters

  s | const UChar * string buffer
  i | string offset, must be i<capacity
  capacity | size of the string buffer
  c | code point to append
  isError | output UBool set to true if an error occurs, otherwise not modified

See also
  U16_APPEND_UNSAFE

Stable
  ICU 2.4

Definition at line 393 of file utf16.h.

## ◆ U16_APPEND_UNSAFE

#define U16_APPEND_UNSAFE | ( |  | s,
|  |  | i,
|  |  | c )

Value:
UPRV_BLOCK_MACRO_BEGIN { \
if((uint32_t)(c)<=0xffff) { \
(s)[(i)++]=(uint16_t)(c); \
} else { \
(s)[(i)++]=(uint16_t)(((c)>>10)+0xd7c0); \
(s)[(i)++]=(uint16_t)(((c)&0x3ff)|0xdc00); \
} \
} UPRV_BLOCK_MACRO_END

Append a code point to a string, overwriting 1 or 2 code units.

The offset points to the current end of the string contents and is advanced (post-increment). "Unsafe" macro, assumes a valid code point and sufficient space in the string. Otherwise, the result is undefined.

Parameters

  s | const UChar * string buffer
  i | string offset
  c | code point to append

See also
  U16_APPEND

Stable
  ICU 2.4

Definition at line 367 of file utf16.h.

## ◆ U16_BACK_1

#define U16_BACK_1 | ( |  | s,
|  |  | start,
|  |  | i )

Value:
UPRV_BLOCK_MACRO_BEGIN { \
if(U16_IS_TRAIL((s)[--(i)]) && (i)>(start) && U16_IS_LEAD((s)[(i)-1])) { \
--(i); \
} \
} UPRV_BLOCK_MACRO_END
U16_IS_LEAD
#define U16_IS_LEAD(c)
Is this code unit a lead surrogate (U+d800..U+dbff)?
Definition utf16.h:59
U16_IS_TRAIL
#define U16_IS_TRAIL(c)
Is this code unit a trail surrogate (U+dc00..U+dfff)?
Definition utf16.h:67

Move the string offset from one code point boundary to the previous one.

(Pre-decrementing backward iteration.) The input offset may be the same as the string length. "Safe" macro, handles unpaired surrogates and checks for string boundaries.

Parameters

  s | const UChar * string
  start | starting string offset (usually 0)
  i | string offset, must be start<i

See also
  U16_BACK_1_UNSAFE

Stable
  ICU 2.4

Definition at line 643 of file utf16.h.

## ◆ U16_BACK_1_UNSAFE

#define U16_BACK_1_UNSAFE | ( |  | s,
|  |  | i )

Value:
UPRV_BLOCK_MACRO_BEGIN { \
if(U16_IS_TRAIL((s)[--(i)])) { \
--(i); \
} \
} UPRV_BLOCK_MACRO_END

Move the string offset from one code point boundary to the previous one.

(Pre-decrementing backward iteration.) The input offset may be the same as the string length. "Unsafe" macro, assumes well-formed UTF-16.

Parameters

  s | const UChar * string
  i | string offset

See also
  U16_BACK_1

Stable
  ICU 2.4

Definition at line 625 of file utf16.h.

## ◆ U16_BACK_N

#define U16_BACK_N | ( |  | s,
|  |  | start,
|  |  | i,
|  |  | n )

Value:
UPRV_BLOCK_MACRO_BEGIN { \
int32_t __N=(n); \
while(__N>0 && (i)>(start)) { \
U16_BACK_1(s, start, i); \
--__N; \
} \
} UPRV_BLOCK_MACRO_END

Move the string offset from one code point boundary to the n-th one before it, i.e., move backward by n code points.

(Pre-decrementing backward iteration.) The input offset may be the same as the string length. "Safe" macro, handles unpaired surrogates and checks for string boundaries.

Parameters

  s | const UChar * string
  start | start of string
  i | string offset, must be start<i
  n | number of code points to skip

See also
  U16_BACK_N_UNSAFE

Stable
  ICU 2.4

Definition at line 684 of file utf16.h.

## ◆ U16_BACK_N_UNSAFE

#define U16_BACK_N_UNSAFE | ( |  | s,
|  |  | i,
|  |  | n )

Value:
UPRV_BLOCK_MACRO_BEGIN { \
int32_t __N=(n); \
while(__N>0) { \
U16_BACK_1_UNSAFE(s, i); \
--__N; \
} \
} UPRV_BLOCK_MACRO_END

Move the string offset from one code point boundary to the n-th one before it, i.e., move backward by n code points.

(Pre-decrementing backward iteration.) The input offset may be the same as the string length. "Unsafe" macro, assumes well-formed UTF-16.

Parameters

  s | const UChar * string
  i | string offset
  n | number of code points to skip

See also
  U16_BACK_N

Stable
  ICU 2.4

Definition at line 662 of file utf16.h.

## ◆ U16_FWD_1

#define U16_FWD_1 | ( |  | s,
|  |  | i,
|  |  | length )

Value:
UPRV_BLOCK_MACRO_BEGIN { \
if(U16_IS_LEAD((s)[(i)++]) && (i)!=(length) && U16_IS_TRAIL((s)[i])) { \
++(i); \
} \
} UPRV_BLOCK_MACRO_END

Advance the string offset from one code point boundary to the next.

(Post-incrementing iteration.) "Safe" macro, handles unpaired surrogates and checks for string boundaries.

The length can be negative for a NUL-terminated string.

Parameters

  s | const UChar * string
  i | string offset, must be i<length
  length | string length

See also
  U16_FWD_1_UNSAFE

Stable
  ICU 2.4

Definition at line 433 of file utf16.h.

## ◆ U16_FWD_1_UNSAFE

#define U16_FWD_1_UNSAFE | ( |  | s,
|  |  | i )

Value:
UPRV_BLOCK_MACRO_BEGIN { \
if(U16_IS_LEAD((s)[(i)++])) { \
++(i); \
} \
} UPRV_BLOCK_MACRO_END

Advance the string offset from one code point boundary to the next.

(Post-incrementing iteration.) "Unsafe" macro, assumes well-formed UTF-16.

Parameters

  s | const UChar * string
  i | string offset

See also
  U16_FWD_1

Stable
  ICU 2.4

Definition at line 414 of file utf16.h.

## ◆ U16_FWD_N

#define U16_FWD_N | ( |  | s,
|  |  | i,
|  |  | length,
|  |  | n )

Value:
UPRV_BLOCK_MACRO_BEGIN { \
int32_t __N=(n); \
while(__N>0 && ((i)<(length) || ((length)<0 && (s)[i]!=0))) { \
U16_FWD_1(s, i, length); \
--__N; \
} \
} UPRV_BLOCK_MACRO_END

Advance the string offset from one code point boundary to the n-th next one, i.e., move forward by n code points.

(Post-incrementing iteration.) "Safe" macro, handles unpaired surrogates and checks for string boundaries.

The length can be negative for a NUL-terminated string.

Parameters

  s | const UChar * string
  i | int32_t string offset, must be i<length
  length | int32_t string length
  n | number of code points to skip

See also
  U16_FWD_N_UNSAFE

Stable
  ICU 2.4

Definition at line 474 of file utf16.h.

## ◆ U16_FWD_N_UNSAFE

#define U16_FWD_N_UNSAFE | ( |  | s,
|  |  | i,
|  |  | n )

Value:
UPRV_BLOCK_MACRO_BEGIN { \
int32_t __N=(n); \
while(__N>0) { \
U16_FWD_1_UNSAFE(s, i); \
--__N; \
} \
} UPRV_BLOCK_MACRO_END

Advance the string offset from one code point boundary to the n-th next one, i.e., move forward by n code points.

(Post-incrementing iteration.) "Unsafe" macro, assumes well-formed UTF-16.

Parameters

  s | const UChar * string
  i | string offset
  n | number of code points to skip

See also
  U16_FWD_N

Stable
  ICU 2.4

Definition at line 451 of file utf16.h.

## ◆ U16_GET

#define U16_GET | ( |  | s,
|  |  | start,
|  |  | i,
|  |  | length,
|  |  | c )

Value:
UPRV_BLOCK_MACRO_BEGIN { \
(c)=(s)[i]; \
if(U16_IS_SURROGATE(c)) { \
uint16_t __c2; \
if(U16_IS_SURROGATE_LEAD(c)) { \
if((i)+1!=(length) && U16_IS_TRAIL(__c2=(s)[(i)+1])) { \
(c)=U16_GET_SUPPLEMENTARY((c), __c2); \
} \
} else { \
if((i)>(start) && U16_IS_LEAD(__c2=(s)[(i)-1])) { \
(c)=U16_GET_SUPPLEMENTARY(__c2, (c)); \
} \
} \
} \
} UPRV_BLOCK_MACRO_END
U16_IS_SURROGATE_LEAD
#define U16_IS_SURROGATE_LEAD(c)
Assuming c is a surrogate code point (U16_IS_SURROGATE(c)), is it a lead surrogate?
Definition utf16.h:84
U16_GET_SUPPLEMENTARY
#define U16_GET_SUPPLEMENTARY(lead, trail)
Get a supplementary code point value (U+10000..U+10ffff) from its lead and trail surrogates.
Definition utf16.h:112
U16_IS_SURROGATE
#define U16_IS_SURROGATE(c)
Is this code unit a surrogate (U+d800..U+dfff)?
Definition utf16.h:75

Get a code point from a string at a random-access offset, without changing the offset.

"Safe" macro, handles unpaired surrogates and checks for string boundaries.

The offset may point to either the lead or trail surrogate unit for a supplementary code point, in which case the macro will read the adjacent matching surrogate as well.

The length can be negative for a NUL-terminated string.

If the offset points to a single, unpaired surrogate, then c is set to that unpaired surrogate. Iteration through a string is more efficient with U16_NEXT_UNSAFE or U16_NEXT.

Parameters

  s | const UChar * string
  start | starting string offset (usually 0)
  i | string offset, must be start<=i<length
  length | string length
  c | output UChar32 variable

See also
  U16_GET_UNSAFE

Stable
  ICU 2.4

Definition at line 201 of file utf16.h.

## ◆ U16_GET_OR_FFFD

#define U16_GET_OR_FFFD | ( |  | s,
|  |  | start,
|  |  | i,
|  |  | length,
|  |  | c )

Value:
UPRV_BLOCK_MACRO_BEGIN { \
(c)=(s)[i]; \
if(U16_IS_SURROGATE(c)) { \
uint16_t __c2; \
if(U16_IS_SURROGATE_LEAD(c)) { \
if((i)+1!=(length) && U16_IS_TRAIL(__c2=(s)[(i)+1])) { \
(c)=U16_GET_SUPPLEMENTARY((c), __c2); \
} else { \
(c)=0xfffd; \
} \
} else { \
if((i)>(start) && U16_IS_LEAD(__c2=(s)[(i)-1])) { \
(c)=U16_GET_SUPPLEMENTARY(__c2, (c)); \
} else { \
(c)=0xfffd; \
} \
} \
} \
} UPRV_BLOCK_MACRO_END

Get a code point from a string at a random-access offset, without changing the offset.

"Safe" macro, handles unpaired surrogates and checks for string boundaries.

The offset may point to either the lead or trail surrogate unit for a supplementary code point, in which case the macro will read the adjacent matching surrogate as well.

The length can be negative for a NUL-terminated string.

If the offset points to a single, unpaired surrogate, then c is set to U+FFFD. Iteration through a string is more efficient with U16_NEXT_UNSAFE or U16_NEXT_OR_FFFD.

Parameters

  s | const UChar * string
  start | starting string offset (usually 0)
  i | string offset, must be start<=i<length
  length | string length
  c | output UChar32 variable

See also
  U16_GET_UNSAFE

Stable
  ICU 60

Definition at line 240 of file utf16.h.

## ◆ U16_GET_SUPPLEMENTARY

#define U16_GET_SUPPLEMENTARY | ( |  | lead,
|  |  | trail )

Value:
(((UChar32)(lead)<<10UL)+(UChar32)(trail)-U16_SURROGATE_OFFSET)
UChar32
int32_t UChar32
Define UChar32 as a type for single Unicode code points.
Definition umachine.h:427
U16_SURROGATE_OFFSET
#define U16_SURROGATE_OFFSET
Helper constant for U16_GET_SUPPLEMENTARY.
Definition utf16.h:99

Get a supplementary code point value (U+10000..U+10ffff) from its lead and trail surrogates.

The result is undefined if the input values are not lead and trail surrogates.

Parameters

  lead | lead surrogate (U+d800..U+dbff)
  trail | trail surrogate (U+dc00..U+dfff)

Returns
  supplementary code point (U+10000..U+10ffff)

Stable
  ICU 2.4

Definition at line 112 of file utf16.h.

## ◆ U16_GET_UNSAFE

#define U16_GET_UNSAFE | ( |  | s,
|  |  | i,
|  |  | c )

Value:
UPRV_BLOCK_MACRO_BEGIN { \
(c)=(s)[i]; \
if(U16_IS_SURROGATE(c)) { \
if(U16_IS_SURROGATE_LEAD(c)) { \
(c)=U16_GET_SUPPLEMENTARY((c), (s)[(i)+1]); \
} else { \
(c)=U16_GET_SUPPLEMENTARY((s)[(i)-1], (c)); \
} \
} \
} UPRV_BLOCK_MACRO_END

Get a code point from a string at a random-access offset, without changing the offset.

"Unsafe" macro, assumes well-formed UTF-16.

The offset may point to either the lead or trail surrogate unit for a supplementary code point, in which case the macro will read the adjacent matching surrogate as well. The result is undefined if the offset points to a single, unpaired surrogate. Iteration through a string is more efficient with U16_NEXT_UNSAFE or U16_NEXT.

Parameters

  s | const UChar * string
  i | string offset
  c | output UChar32 variable

See also
  U16_GET

Stable
  ICU 2.4

Definition at line 167 of file utf16.h.

## ◆ U16_IS_LEAD

#define U16_IS_LEAD | ( |  | c | ) |

Value:
(((c)&0xfffffc00)==0xd800)

Is this code unit a lead surrogate (U+d800..U+dbff)?

Parameters

  c | 16-bit code unit

Returns
  true or false

Stable
  ICU 2.4

Definition at line 59 of file utf16.h.

## ◆ U16_IS_SINGLE

#define U16_IS_SINGLE | ( |  | c | ) |

Value:
!U_IS_SURROGATE(c)
U_IS_SURROGATE
#define U_IS_SURROGATE(c)
Is this code point a surrogate (U+d800..U+dfff)?
Definition utf.h:193

Does this code unit alone encode a code point (BMP, not a surrogate)?

Parameters

  c | 16-bit code unit

Returns
  true or false

Stable
  ICU 2.4

Definition at line 51 of file utf16.h.

## ◆ U16_IS_SURROGATE

#define U16_IS_SURROGATE | ( |  | c | ) |

Value:
U_IS_SURROGATE(c)

Is this code unit a surrogate (U+d800..U+dfff)?

Parameters

  c | 16-bit code unit

Returns
  true or false

Stable
  ICU 2.4

Definition at line 75 of file utf16.h.

## ◆ U16_IS_SURROGATE_LEAD

#define U16_IS_SURROGATE_LEAD | ( |  | c | ) |

Value:
(((c)&0x400)==0)

Assuming c is a surrogate code point (U16_IS_SURROGATE(c)), is it a lead surrogate?

Parameters

  c | 16-bit code unit

Returns
  true or false

Stable
  ICU 2.4

Definition at line 84 of file utf16.h.

## ◆ U16_IS_SURROGATE_TRAIL

#define U16_IS_SURROGATE_TRAIL | ( |  | c | ) |

Value:
(((c)&0x400)!=0)

Assuming c is a surrogate code point (U16_IS_SURROGATE(c)), is it a trail surrogate?

Parameters

  c | 16-bit code unit

Returns
  true or false

Stable
  ICU 4.2

Definition at line 93 of file utf16.h.

## ◆ U16_IS_TRAIL

#define U16_IS_TRAIL | ( |  | c | ) |

Value:
(((c)&0xfffffc00)==0xdc00)

Is this code unit a trail surrogate (U+dc00..U+dfff)?

Parameters

  c | 16-bit code unit

Returns
  true or false

Stable
  ICU 2.4

Definition at line 67 of file utf16.h.

## ◆ U16_LEAD

#define U16_LEAD | ( |  | supplementary | ) |

Value:
(UChar)(((supplementary)>>10)+0xd7c0)
UChar
char16_t UChar
The base type for UTF-16 code units and pointers.
Definition umachine.h:378

Get the lead surrogate (0xd800..0xdbff) for a supplementary code point (0x10000..0x10ffff).

Parameters

  supplementary | 32-bit code point (U+10000..U+10ffff)

Returns
  lead surrogate (U+d800..U+dbff) for supplementary

Stable
  ICU 2.4

Definition at line 123 of file utf16.h.

## ◆ U16_LENGTH

#define U16_LENGTH | ( |  | c | ) |

Value:
((uint32_t)(c)<=0xffff ? 1 : 2)

How many 16-bit code units are used to encode this Unicode code point? (1 or 2) The result is not defined if c is not a Unicode code point (U+0000..U+10ffff).

Parameters

  c | 32-bit code point

Returns
  1 or 2

Stable
  ICU 2.4

Definition at line 141 of file utf16.h.

## ◆ U16_MAX_LENGTH

#define U16_MAX_LENGTH 2

The maximum number of 16-bit code units per Unicode code point (U+0000..U+10ffff).

Returns
  2

Stable
  ICU 2.4

Definition at line 148 of file utf16.h.

## ◆ U16_NEXT

#define U16_NEXT | ( |  | s,
|  |  | i,
|  |  | length,
|  |  | c )

Value:
UPRV_BLOCK_MACRO_BEGIN { \
(c)=(s)[(i)++]; \
if(U16_IS_LEAD(c)) { \
uint16_t __c2; \
if((i)!=(length) && U16_IS_TRAIL(__c2=(s)[(i)])) { \
++(i); \
(c)=U16_GET_SUPPLEMENTARY((c), __c2); \
} \
} \
} UPRV_BLOCK_MACRO_END

Get a code point from a string at a code point boundary offset, and advance the offset to the next code point boundary.

(Post-incrementing forward iteration.) "Safe" macro, handles unpaired surrogates and checks for string boundaries.

The length can be negative for a NUL-terminated string.

The offset may point to the lead surrogate unit for a supplementary code point, in which case the macro will read the following trail surrogate as well. If the offset points to a trail surrogate or to a single, unpaired lead surrogate, then c is set to that unpaired surrogate.

Parameters

  s | const UChar * string
  i | string offset, must be i<length
  length | string length
  c | output UChar32 variable

See also
  U16_NEXT_UNSAFE

Stable
  ICU 2.4

Definition at line 309 of file utf16.h.

## ◆ U16_NEXT_OR_FFFD

#define U16_NEXT_OR_FFFD | ( |  | s,
|  |  | i,
|  |  | length,
|  |  | c )

Value:
UPRV_BLOCK_MACRO_BEGIN { \
(c)=(s)[(i)++]; \
if(U16_IS_SURROGATE(c)) { \
uint16_t __c2; \
if(U16_IS_SURROGATE_LEAD(c) && (i)!=(length) && U16_IS_TRAIL(__c2=(s)[(i)])) { \
++(i); \
(c)=U16_GET_SUPPLEMENTARY((c), __c2); \
} else { \
(c)=0xfffd; \
} \
} \
} UPRV_BLOCK_MACRO_END

Get a code point from a string at a code point boundary offset, and advance the offset to the next code point boundary.

(Post-incrementing forward iteration.) "Safe" macro, handles unpaired surrogates and checks for string boundaries.

The length can be negative for a NUL-terminated string.

The offset may point to the lead surrogate unit for a supplementary code point, in which case the macro will read the following trail surrogate as well. If the offset points to a trail surrogate or to a single, unpaired lead surrogate, then c is set to U+FFFD.

Parameters

  s | const UChar * string
  i | string offset, must be i<length
  length | string length
  c | output UChar32 variable

See also
  U16_NEXT_UNSAFE

Stable
  ICU 60

Definition at line 341 of file utf16.h.

## ◆ U16_NEXT_UNSAFE

#define U16_NEXT_UNSAFE | ( |  | s,
|  |  | i,
|  |  | c )

Value:
UPRV_BLOCK_MACRO_BEGIN { \
(c)=(s)[(i)++]; \
if(U16_IS_LEAD(c)) { \
(c)=U16_GET_SUPPLEMENTARY((c), (s)[(i)++]); \
} \
} UPRV_BLOCK_MACRO_END

Get a code point from a string at a code point boundary offset, and advance the offset to the next code point boundary.

(Post-incrementing forward iteration.) "Unsafe" macro, assumes well-formed UTF-16.

The offset may point to the lead surrogate unit for a supplementary code point, in which case the macro will read the following trail surrogate as well. If the offset points to a trail surrogate, then that itself will be returned as the code point. The result is undefined if the offset points to a single, unpaired lead surrogate.

Parameters

  s | const UChar * string
  i | string offset
  c | output UChar32 variable

See also
  U16_NEXT

Stable
  ICU 2.4

Definition at line 281 of file utf16.h.

## ◆ U16_PREV

#define U16_PREV | ( |  | s,
|  |  | start,
|  |  | i,
|  |  | c )

Value:
UPRV_BLOCK_MACRO_BEGIN { \
(c)=(s)[--(i)]; \
if(U16_IS_TRAIL(c)) { \
uint16_t __c2; \
if((i)>(start) && U16_IS_LEAD(__c2=(s)[(i)-1])) { \
--(i); \
(c)=U16_GET_SUPPLEMENTARY(__c2, (c)); \
} \
} \
} UPRV_BLOCK_MACRO_END

Move the string offset from one code point boundary to the previous one and get the code point between them.

(Pre-decrementing backward iteration.) "Safe" macro, handles unpaired surrogates and checks for string boundaries.

The input offset may be the same as the string length. If the offset is behind a trail surrogate unit for a supplementary code point, then the macro will read the preceding lead surrogate as well. If the offset is behind a lead surrogate or behind a single, unpaired trail surrogate, then c is set to that unpaired surrogate.

Parameters

  s | const UChar * string
  start | starting string offset (usually 0)
  i | string offset, must be start<i
  c | output UChar32 variable

See also
  U16_PREV_UNSAFE

Stable
  ICU 2.4

Definition at line 570 of file utf16.h.

## ◆ U16_PREV_OR_FFFD

#define U16_PREV_OR_FFFD | ( |  | s,
|  |  | start,
|  |  | i,
|  |  | c )

Value:
UPRV_BLOCK_MACRO_BEGIN { \
(c)=(s)[--(i)]; \
if(U16_IS_SURROGATE(c)) { \
uint16_t __c2; \
if(U16_IS_SURROGATE_TRAIL(c) && (i)>(start) && U16_IS_LEAD(__c2=(s)[(i)-1])) { \
--(i); \
(c)=U16_GET_SUPPLEMENTARY(__c2, (c)); \
} else { \
(c)=0xfffd; \
} \
} \
} UPRV_BLOCK_MACRO_END
U16_IS_SURROGATE_TRAIL
#define U16_IS_SURROGATE_TRAIL(c)
Assuming c is a surrogate code point (U16_IS_SURROGATE(c)), is it a trail surrogate?
Definition utf16.h:93

Move the string offset from one code point boundary to the previous one and get the code point between them.

(Pre-decrementing backward iteration.) "Safe" macro, handles unpaired surrogates and checks for string boundaries.

The input offset may be the same as the string length. If the offset is behind a trail surrogate unit for a supplementary code point, then the macro will read the preceding lead surrogate as well. If the offset is behind a lead surrogate or behind a single, unpaired trail surrogate, then c is set to U+FFFD.

Parameters

  s | const UChar * string
  start | starting string offset (usually 0)
  i | string offset, must be start<i
  c | output UChar32 variable

See also
  U16_PREV_UNSAFE

Stable
  ICU 60

Definition at line 601 of file utf16.h.

## ◆ U16_PREV_UNSAFE

#define U16_PREV_UNSAFE | ( |  | s,
|  |  | i,
|  |  | c )

Value:
UPRV_BLOCK_MACRO_BEGIN { \
(c)=(s)[--(i)]; \
if(U16_IS_TRAIL(c)) { \
(c)=U16_GET_SUPPLEMENTARY((s)[--(i)], (c)); \
} \
} UPRV_BLOCK_MACRO_END

Move the string offset from one code point boundary to the previous one and get the code point between them.

(Pre-decrementing backward iteration.) "Unsafe" macro, assumes well-formed UTF-16.

The input offset may be the same as the string length. If the offset is behind a trail surrogate unit for a supplementary code point, then the macro will read the preceding lead surrogate as well. If the offset is behind a lead surrogate, then that itself will be returned as the code point. The result is undefined if the offset is behind a single, unpaired trail surrogate.

Parameters

  s | const UChar * string
  i | string offset
  c | output UChar32 variable

See also
  U16_PREV

Stable
  ICU 2.4

Definition at line 543 of file utf16.h.

## ◆ U16_SET_CP_LIMIT

#define U16_SET_CP_LIMIT | ( |  | s,
|  |  | start,
|  |  | i,
|  |  | length )

Value:
UPRV_BLOCK_MACRO_BEGIN { \
if((start)<(i) && ((i)<(length) || (length)<0) && U16_IS_LEAD((s)[(i)-1]) && U16_IS_TRAIL((s)[i])) { \
++(i); \
} \
} UPRV_BLOCK_MACRO_END

Adjust a random-access offset to a code point boundary after a code point.

If the offset is behind the lead surrogate of a surrogate pair, then the offset is incremented. Otherwise, it is not modified. The input offset may be the same as the string length. "Safe" macro, handles unpaired surrogates and checks for string boundaries.

The length can be negative for a NUL-terminated string.

Parameters

  s | const UChar * string
  start | int32_t starting string offset (usually 0)
  i | int32_t string offset, start<=i<=length
  length | int32_t string length

See also
  U16_SET_CP_LIMIT_UNSAFE

Stable
  ICU 2.4

Definition at line 728 of file utf16.h.

## ◆ U16_SET_CP_LIMIT_UNSAFE

#define U16_SET_CP_LIMIT_UNSAFE | ( |  | s,
|  |  | i )

Value:
UPRV_BLOCK_MACRO_BEGIN { \
if(U16_IS_LEAD((s)[(i)-1])) { \
++(i); \
} \
} UPRV_BLOCK_MACRO_END

Adjust a random-access offset to a code point boundary after a code point.

If the offset is behind the lead surrogate of a surrogate pair, then the offset is incremented. Otherwise, it is not modified. The input offset may be the same as the string length. "Unsafe" macro, assumes well-formed UTF-16.

Parameters

  s | const UChar * string
  i | string offset

See also
  U16_SET_CP_LIMIT

Stable
  ICU 2.4

Definition at line 705 of file utf16.h.

## ◆ U16_SET_CP_START

#define U16_SET_CP_START | ( |  | s,
|  |  | start,
|  |  | i )

Value:
UPRV_BLOCK_MACRO_BEGIN { \
if(U16_IS_TRAIL((s)[i]) && (i)>(start) && U16_IS_LEAD((s)[(i)-1])) { \
--(i); \
} \
} UPRV_BLOCK_MACRO_END

Adjust a random-access offset to a code point boundary at the start of a code point.

If the offset points to the trail surrogate of a surrogate pair, then the offset is decremented. Otherwise, it is not modified. "Safe" macro, handles unpaired surrogates and checks for string boundaries.

Parameters

  s | const UChar * string
  start | starting string offset (usually 0)
  i | string offset, must be start<=i

See also
  U16_SET_CP_START_UNSAFE

Stable
  ICU 2.4

Definition at line 515 of file utf16.h.

## ◆ U16_SET_CP_START_UNSAFE

#define U16_SET_CP_START_UNSAFE | ( |  | s,
|  |  | i )

Value:
UPRV_BLOCK_MACRO_BEGIN { \
if(U16_IS_TRAIL((s)[i])) { \
--(i); \
} \
} UPRV_BLOCK_MACRO_END

Adjust a random-access offset to a code point boundary at the start of a code point.

If the offset points to the trail surrogate of a surrogate pair, then the offset is decremented. Otherwise, it is not modified. "Unsafe" macro, assumes well-formed UTF-16.

Parameters

  s | const UChar * string
  i | string offset

See also
  U16_SET_CP_START

Stable
  ICU 2.4

Definition at line 495 of file utf16.h.

## ◆ U16_SURROGATE_OFFSET

#define U16_SURROGATE_OFFSET ((0xd800<<10UL)+0xdc00-0x10000)

Helper constant for U16_GET_SUPPLEMENTARY.

Internal
  Do not use. This API is for internal use only.

Definition at line 99 of file utf16.h.

## ◆ U16_TRAIL

#define U16_TRAIL | ( |  | supplementary | ) |

Value:
(UChar)(((supplementary)&0x3ff)|0xdc00)

Get the trail surrogate (0xdc00..0xdfff) for a supplementary code point (0x10000..0x10ffff).

Parameters

  supplementary | 32-bit code point (U+10000..U+10ffff)

Returns
  trail surrogate (U+dc00..U+dfff) for supplementary

Stable
  ICU 2.4

Definition at line 132 of file utf16.h.