1 // Copyright (C) 2016 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 /* 4 ******************************************************************************* 5 * 6 * Copyright (C) 1999-2015, International Business Machines 7 * Corporation and others. All Rights Reserved. 8 * 9 ******************************************************************************* 10 * file name: utf8.h 11 * encoding: US-ASCII 12 * tab size: 8 (not used) 13 * indentation:4 14 * 15 * created on: 1999sep13 16 * created by: Markus W. Scherer 17 */ 18 19 /** 20 * \file 21 * \brief C API: 8-bit Unicode handling macros 22 * 23 * This file defines macros to deal with 8-bit Unicode (UTF-8) code units (bytes) and strings. 24 * 25 * For more information see utf.h and the ICU User Guide Strings chapter 26 * (http://userguide.icu-project.org/strings). 27 * 28 * <em>Usage:</em> 29 * ICU coding guidelines for if() statements should be followed when using these macros. 30 * Compound statements (curly braces {}) must be used for if-else-while... 31 * bodies and all macro statements should be terminated with semicolon. 32 */ 33 34 #ifndef __UTF8_H__ 35 #define __UTF8_H__ 36 37 #include "unicode/umachine.h" 38 #ifndef __UTF_H__ 39 # include "unicode/utf.h" 40 #endif 41 42 /* internal definitions ----------------------------------------------------- */ 43 44 /** 45 * \var utf8_countTrailBytes 46 * Internal array with numbers of trail bytes for any given byte used in 47 * lead byte position. 48 * 49 * This is internal since it is not meant to be called directly by external clients; 50 * however it is called by public macros in this file and thus must remain stable, 51 * and should not be hidden when other internal functions are hidden (otherwise 52 * public macros would fail to compile). 53 * @internal 54 */ 55 #ifdef U_UTF8_IMPL 56 U_EXPORT const uint8_t 57 #elif defined(U_STATIC_IMPLEMENTATION) || defined(U_COMMON_IMPLEMENTATION) 58 U_CFUNC const uint8_t 59 #else 60 U_CFUNC U_IMPORT const uint8_t /* U_IMPORT2? */ /*U_IMPORT*/ 61 #endif 62 utf8_countTrailBytes[256]; 63 64 /** 65 * Counts the trail bytes for a UTF-8 lead byte. 66 * Returns 0 for 0..0xbf as well as for 0xfe and 0xff. 67 * 68 * This is internal since it is not meant to be called directly by external clients; 69 * however it is called by public macros in this file and thus must remain stable. 70 * 71 * Note: Beginning with ICU 50, the implementation uses a multi-condition expression 72 * which was shown in 2012 (on x86-64) to compile to fast, branch-free code. 73 * leadByte is evaluated multiple times. 74 * 75 * The pre-ICU 50 implementation used the exported array utf8_countTrailBytes: 76 * #define U8_COUNT_TRAIL_BYTES(leadByte) (utf8_countTrailBytes[leadByte]) 77 * leadByte was evaluated exactly once. 78 * 79 * @param leadByte The first byte of a UTF-8 sequence. Must be 0..0xff. 80 * @internal 81 */ 82 #define U8_COUNT_TRAIL_BYTES(leadByte) \ 83 ((uint8_t)(leadByte)<0xf0 ? \ 84 ((uint8_t)(leadByte)>=0xc0)+((uint8_t)(leadByte)>=0xe0) : \ 85 (uint8_t)(leadByte)<0xfe ? 3+((uint8_t)(leadByte)>=0xf8)+((uint8_t)(leadByte)>=0xfc) : 0) 86 87 /** 88 * Counts the trail bytes for a UTF-8 lead byte of a valid UTF-8 sequence. 89 * The maximum supported lead byte is 0xf4 corresponding to U+10FFFF. 90 * leadByte might be evaluated multiple times. 91 * 92 * This is internal since it is not meant to be called directly by external clients; 93 * however it is called by public macros in this file and thus must remain stable. 94 * 95 * @param leadByte The first byte of a UTF-8 sequence. Must be 0..0xff. 96 * @internal 97 */ 98 #define U8_COUNT_TRAIL_BYTES_UNSAFE(leadByte) \ 99 (((leadByte)>=0xc0)+((leadByte)>=0xe0)+((leadByte)>=0xf0)) 100 101 /** 102 * Mask a UTF-8 lead byte, leave only the lower bits that form part of the code point value. 103 * 104 * This is internal since it is not meant to be called directly by external clients; 105 * however it is called by public macros in this file and thus must remain stable. 106 * @internal 107 */ 108 #define U8_MASK_LEAD_BYTE(leadByte, countTrailBytes) ((leadByte)&=(1<<(6-(countTrailBytes)))-1) 109 110 /** 111 * Function for handling "next code point" with error-checking. 112 * 113 * This is internal since it is not meant to be called directly by external clients; 114 * however it is U_STABLE (not U_INTERNAL) since it is called by public macros in this 115 * file and thus must remain stable, and should not be hidden when other internal 116 * functions are hidden (otherwise public macros would fail to compile). 117 * @internal 118 */ 119 U_STABLE UChar32 U_EXPORT2 120 utf8_nextCharSafeBody(const uint8_t *s, int32_t *pi, int32_t length, UChar32 c, UBool strict); 121 122 /** 123 * Function for handling "append code point" with error-checking. 124 * 125 * This is internal since it is not meant to be called directly by external clients; 126 * however it is U_STABLE (not U_INTERNAL) since it is called by public macros in this 127 * file and thus must remain stable, and should not be hidden when other internal 128 * functions are hidden (otherwise public macros would fail to compile). 129 * @internal 130 */ 131 U_STABLE int32_t U_EXPORT2 132 utf8_appendCharSafeBody(uint8_t *s, int32_t i, int32_t length, UChar32 c, UBool *pIsError); 133 134 /** 135 * Function for handling "previous code point" with error-checking. 136 * 137 * This is internal since it is not meant to be called directly by external clients; 138 * however it is U_STABLE (not U_INTERNAL) since it is called by public macros in this 139 * file and thus must remain stable, and should not be hidden when other internal 140 * functions are hidden (otherwise public macros would fail to compile). 141 * @internal 142 */ 143 U_STABLE UChar32 U_EXPORT2 144 utf8_prevCharSafeBody(const uint8_t *s, int32_t start, int32_t *pi, UChar32 c, UBool strict); 145 146 /** 147 * Function for handling "skip backward one code point" with error-checking. 148 * 149 * This is internal since it is not meant to be called directly by external clients; 150 * however it is U_STABLE (not U_INTERNAL) since it is called by public macros in this 151 * file and thus must remain stable, and should not be hidden when other internal 152 * functions are hidden (otherwise public macros would fail to compile). 153 * @internal 154 */ 155 U_STABLE int32_t U_EXPORT2 156 utf8_back1SafeBody(const uint8_t *s, int32_t start, int32_t i); 157 158 /* single-code point definitions -------------------------------------------- */ 159 160 /** 161 * Does this code unit (byte) encode a code point by itself (US-ASCII 0..0x7f)? 162 * @param c 8-bit code unit (byte) 163 * @return TRUE or FALSE 164 * @stable ICU 2.4 165 */ 166 #define U8_IS_SINGLE(c) (((c)&0x80)==0) 167 168 /** 169 * Is this code unit (byte) a UTF-8 lead byte? 170 * @param c 8-bit code unit (byte) 171 * @return TRUE or FALSE 172 * @stable ICU 2.4 173 */ 174 #define U8_IS_LEAD(c) ((uint8_t)((c)-0xc0)<0x3e) 175 176 /** 177 * Is this code unit (byte) a UTF-8 trail byte? 178 * @param c 8-bit code unit (byte) 179 * @return TRUE or FALSE 180 * @stable ICU 2.4 181 */ 182 #define U8_IS_TRAIL(c) (((c)&0xc0)==0x80) 183 184 /** 185 * How many code units (bytes) are used for the UTF-8 encoding 186 * of this Unicode code point? 187 * @param c 32-bit code point 188 * @return 1..4, or 0 if c is a surrogate or not a Unicode code point 189 * @stable ICU 2.4 190 */ 191 #define U8_LENGTH(c) \ 192 ((uint32_t)(c)<=0x7f ? 1 : \ 193 ((uint32_t)(c)<=0x7ff ? 2 : \ 194 ((uint32_t)(c)<=0xd7ff ? 3 : \ 195 ((uint32_t)(c)<=0xdfff || (uint32_t)(c)>0x10ffff ? 0 : \ 196 ((uint32_t)(c)<=0xffff ? 3 : 4)\ 197 ) \ 198 ) \ 199 ) \ 200 ) 201 202 /** 203 * The maximum number of UTF-8 code units (bytes) per Unicode code point (U+0000..U+10ffff). 204 * @return 4 205 * @stable ICU 2.4 206 */ 207 #define U8_MAX_LENGTH 4 208 209 /** 210 * Get a code point from a string at a random-access offset, 211 * without changing the offset. 212 * The offset may point to either the lead byte or one of the trail bytes 213 * for a code point, in which case the macro will read all of the bytes 214 * for the code point. 215 * The result is undefined if the offset points to an illegal UTF-8 216 * byte sequence. 217 * Iteration through a string is more efficient with U8_NEXT_UNSAFE or U8_NEXT. 218 * 219 * @param s const uint8_t * string 220 * @param i string offset 221 * @param c output UChar32 variable 222 * @see U8_GET 223 * @stable ICU 2.4 224 */ 225 #define U8_GET_UNSAFE(s, i, c) { \ 226 int32_t _u8_get_unsafe_index=(int32_t)(i); \ 227 U8_SET_CP_START_UNSAFE(s, _u8_get_unsafe_index); \ 228 U8_NEXT_UNSAFE(s, _u8_get_unsafe_index, c); \ 229 } 230 231 /** 232 * Get a code point from a string at a random-access offset, 233 * without changing the offset. 234 * The offset may point to either the lead byte or one of the trail bytes 235 * for a code point, in which case the macro will read all of the bytes 236 * for the code point. 237 * 238 * The length can be negative for a NUL-terminated string. 239 * 240 * If the offset points to an illegal UTF-8 byte sequence, then 241 * c is set to a negative value. 242 * Iteration through a string is more efficient with U8_NEXT_UNSAFE or U8_NEXT. 243 * 244 * @param s const uint8_t * string 245 * @param start int32_t starting string offset 246 * @param i int32_t string offset, must be start<=i<length 247 * @param length int32_t string length 248 * @param c output UChar32 variable, set to <0 in case of an error 249 * @see U8_GET_UNSAFE 250 * @stable ICU 2.4 251 */ 252 #define U8_GET(s, start, i, length, c) { \ 253 int32_t _u8_get_index=(i); \ 254 U8_SET_CP_START(s, start, _u8_get_index); \ 255 U8_NEXT(s, _u8_get_index, length, c); \ 256 } 257 258 /** 259 * Get a code point from a string at a random-access offset, 260 * without changing the offset. 261 * The offset may point to either the lead byte or one of the trail bytes 262 * for a code point, in which case the macro will read all of the bytes 263 * for the code point. 264 * 265 * The length can be negative for a NUL-terminated string. 266 * 267 * If the offset points to an illegal UTF-8 byte sequence, then 268 * c is set to U+FFFD. 269 * Iteration through a string is more efficient with U8_NEXT_UNSAFE or U8_NEXT_OR_FFFD. 270 * 271 * This macro does not distinguish between a real U+FFFD in the text 272 * and U+FFFD returned for an ill-formed sequence. 273 * Use U8_GET() if that distinction is important. 274 * 275 * @param s const uint8_t * string 276 * @param start int32_t starting string offset 277 * @param i int32_t string offset, must be start<=i<length 278 * @param length int32_t string length 279 * @param c output UChar32 variable, set to U+FFFD in case of an error 280 * @see U8_GET 281 * @stable ICU 51 282 */ 283 #define U8_GET_OR_FFFD(s, start, i, length, c) { \ 284 int32_t _u8_get_index=(i); \ 285 U8_SET_CP_START(s, start, _u8_get_index); \ 286 U8_NEXT_OR_FFFD(s, _u8_get_index, length, c); \ 287 } 288 289 /* definitions with forward iteration --------------------------------------- */ 290 291 /** 292 * Get a code point from a string at a code point boundary offset, 293 * and advance the offset to the next code point boundary. 294 * (Post-incrementing forward iteration.) 295 * "Unsafe" macro, assumes well-formed UTF-8. 296 * 297 * The offset may point to the lead byte of a multi-byte sequence, 298 * in which case the macro will read the whole sequence. 299 * The result is undefined if the offset points to a trail byte 300 * or an illegal UTF-8 sequence. 301 * 302 * @param s const uint8_t * string 303 * @param i string offset 304 * @param c output UChar32 variable 305 * @see U8_NEXT 306 * @stable ICU 2.4 307 */ 308 #define U8_NEXT_UNSAFE(s, i, c) { \ 309 (c)=(uint8_t)(s)[(i)++]; \ 310 if((c)>=0x80) { \ 311 if((c)<0xe0) { \ 312 (c)=(((c)&0x1f)<<6)|((s)[(i)++]&0x3f); \ 313 } else if((c)<0xf0) { \ 314 /* no need for (c&0xf) because the upper bits are truncated after <<12 in the cast to (UChar) */ \ 315 (c)=(UChar)(((c)<<12)|(((s)[i]&0x3f)<<6)|((s)[(i)+1]&0x3f)); \ 316 (i)+=2; \ 317 } else { \ 318 (c)=(((c)&7)<<18)|(((s)[i]&0x3f)<<12)|(((s)[(i)+1]&0x3f)<<6)|((s)[(i)+2]&0x3f); \ 319 (i)+=3; \ 320 } \ 321 } \ 322 } 323 324 /** 325 * Get a code point from a string at a code point boundary offset, 326 * and advance the offset to the next code point boundary. 327 * (Post-incrementing forward iteration.) 328 * "Safe" macro, checks for illegal sequences and for string boundaries. 329 * 330 * The length can be negative for a NUL-terminated string. 331 * 332 * The offset may point to the lead byte of a multi-byte sequence, 333 * in which case the macro will read the whole sequence. 334 * If the offset points to a trail byte or an illegal UTF-8 sequence, then 335 * c is set to a negative value. 336 * 337 * @param s const uint8_t * string 338 * @param i int32_t string offset, must be i<length 339 * @param length int32_t string length 340 * @param c output UChar32 variable, set to <0 in case of an error 341 * @see U8_NEXT_UNSAFE 342 * @stable ICU 2.4 343 */ 344 #define U8_NEXT(s, i, length, c) { \ 345 (c)=(uint8_t)(s)[(i)++]; \ 346 if((c)>=0x80) { \ 347 uint8_t __t1, __t2; \ 348 if( /* handle U+1000..U+CFFF inline */ \ 349 (0xe0<(c) && (c)<=0xec) && \ 350 (((i)+1)<(length) || (length)<0) && \ 351 (__t1=(uint8_t)((s)[i]-0x80))<=0x3f && \ 352 (__t2=(uint8_t)((s)[(i)+1]-0x80))<= 0x3f \ 353 ) { \ 354 /* no need for (c&0xf) because the upper bits are truncated after <<12 in the cast to (UChar) */ \ 355 (c)=(UChar)(((c)<<12)|(__t1<<6)|__t2); \ 356 (i)+=2; \ 357 } else if( /* handle U+0080..U+07FF inline */ \ 358 ((c)<0xe0 && (c)>=0xc2) && \ 359 ((i)!=(length)) && \ 360 (__t1=(uint8_t)((s)[i]-0x80))<=0x3f \ 361 ) { \ 362 (c)=(((c)&0x1f)<<6)|__t1; \ 363 ++(i); \ 364 } else { \ 365 /* function call for "complicated" and error cases */ \ 366 (c)=utf8_nextCharSafeBody((const uint8_t *)s, &(i), (length), c, -1); \ 367 } \ 368 } \ 369 } 370 371 /** 372 * Get a code point from a string at a code point boundary offset, 373 * and advance the offset to the next code point boundary. 374 * (Post-incrementing forward iteration.) 375 * "Safe" macro, checks for illegal sequences and for string boundaries. 376 * 377 * The length can be negative for a NUL-terminated string. 378 * 379 * The offset may point to the lead byte of a multi-byte sequence, 380 * in which case the macro will read the whole sequence. 381 * If the offset points to a trail byte or an illegal UTF-8 sequence, then 382 * c is set to U+FFFD. 383 * 384 * This macro does not distinguish between a real U+FFFD in the text 385 * and U+FFFD returned for an ill-formed sequence. 386 * Use U8_NEXT() if that distinction is important. 387 * 388 * @param s const uint8_t * string 389 * @param i int32_t string offset, must be i<length 390 * @param length int32_t string length 391 * @param c output UChar32 variable, set to U+FFFD in case of an error 392 * @see U8_NEXT 393 * @stable ICU 51 394 */ 395 #define U8_NEXT_OR_FFFD(s, i, length, c) { \ 396 (c)=(uint8_t)(s)[(i)++]; \ 397 if((c)>=0x80) { \ 398 uint8_t __t1, __t2; \ 399 if( /* handle U+1000..U+CFFF inline */ \ 400 (0xe0<(c) && (c)<=0xec) && \ 401 (((i)+1)<(length) || (length)<0) && \ 402 (__t1=(uint8_t)((s)[i]-0x80))<=0x3f && \ 403 (__t2=(uint8_t)((s)[(i)+1]-0x80))<= 0x3f \ 404 ) { \ 405 /* no need for (c&0xf) because the upper bits are truncated after <<12 in the cast to (UChar) */ \ 406 (c)=(UChar)(((c)<<12)|(__t1<<6)|__t2); \ 407 (i)+=2; \ 408 } else if( /* handle U+0080..U+07FF inline */ \ 409 ((c)<0xe0 && (c)>=0xc2) && \ 410 ((i)!=(length)) && \ 411 (__t1=(uint8_t)((s)[i]-0x80))<=0x3f \ 412 ) { \ 413 (c)=(((c)&0x1f)<<6)|__t1; \ 414 ++(i); \ 415 } else { \ 416 /* function call for "complicated" and error cases */ \ 417 (c)=utf8_nextCharSafeBody((const uint8_t *)s, &(i), (length), c, -3); \ 418 } \ 419 } \ 420 } 421 422 /** 423 * Append a code point to a string, overwriting 1 to 4 bytes. 424 * The offset points to the current end of the string contents 425 * and is advanced (post-increment). 426 * "Unsafe" macro, assumes a valid code point and sufficient space in the string. 427 * Otherwise, the result is undefined. 428 * 429 * @param s const uint8_t * string buffer 430 * @param i string offset 431 * @param c code point to append 432 * @see U8_APPEND 433 * @stable ICU 2.4 434 */ 435 #define U8_APPEND_UNSAFE(s, i, c) { \ 436 if((uint32_t)(c)<=0x7f) { \ 437 (s)[(i)++]=(uint8_t)(c); \ 438 } else { \ 439 if((uint32_t)(c)<=0x7ff) { \ 440 (s)[(i)++]=(uint8_t)(((c)>>6)|0xc0); \ 441 } else { \ 442 if((uint32_t)(c)<=0xffff) { \ 443 (s)[(i)++]=(uint8_t)(((c)>>12)|0xe0); \ 444 } else { \ 445 (s)[(i)++]=(uint8_t)(((c)>>18)|0xf0); \ 446 (s)[(i)++]=(uint8_t)((((c)>>12)&0x3f)|0x80); \ 447 } \ 448 (s)[(i)++]=(uint8_t)((((c)>>6)&0x3f)|0x80); \ 449 } \ 450 (s)[(i)++]=(uint8_t)(((c)&0x3f)|0x80); \ 451 } \ 452 } 453 454 /** 455 * Append a code point to a string, overwriting 1 to 4 bytes. 456 * The offset points to the current end of the string contents 457 * and is advanced (post-increment). 458 * "Safe" macro, checks for a valid code point. 459 * If a non-ASCII code point is written, checks for sufficient space in the string. 460 * If the code point is not valid or trail bytes do not fit, 461 * then isError is set to TRUE. 462 * 463 * @param s const uint8_t * string buffer 464 * @param i int32_t string offset, must be i<capacity 465 * @param capacity int32_t size of the string buffer 466 * @param c UChar32 code point to append 467 * @param isError output UBool set to TRUE if an error occurs, otherwise not modified 468 * @see U8_APPEND_UNSAFE 469 * @stable ICU 2.4 470 */ 471 #define U8_APPEND(s, i, capacity, c, isError) { \ 472 if((uint32_t)(c)<=0x7f) { \ 473 (s)[(i)++]=(uint8_t)(c); \ 474 } else if((uint32_t)(c)<=0x7ff && (i)+1<(capacity)) { \ 475 (s)[(i)++]=(uint8_t)(((c)>>6)|0xc0); \ 476 (s)[(i)++]=(uint8_t)(((c)&0x3f)|0x80); \ 477 } else if((uint32_t)(c)<=0xd7ff && (i)+2<(capacity)) { \ 478 (s)[(i)++]=(uint8_t)(((c)>>12)|0xe0); \ 479 (s)[(i)++]=(uint8_t)((((c)>>6)&0x3f)|0x80); \ 480 (s)[(i)++]=(uint8_t)(((c)&0x3f)|0x80); \ 481 } else { \ 482 (i)=utf8_appendCharSafeBody(s, (i), (capacity), c, &(isError)); \ 483 } \ 484 } 485 486 /** 487 * Advance the string offset from one code point boundary to the next. 488 * (Post-incrementing iteration.) 489 * "Unsafe" macro, assumes well-formed UTF-8. 490 * 491 * @param s const uint8_t * string 492 * @param i string offset 493 * @see U8_FWD_1 494 * @stable ICU 2.4 495 */ 496 #define U8_FWD_1_UNSAFE(s, i) { \ 497 (i)+=1+U8_COUNT_TRAIL_BYTES_UNSAFE((uint8_t)(s)[i]); \ 498 } 499 500 /** 501 * Advance the string offset from one code point boundary to the next. 502 * (Post-incrementing iteration.) 503 * "Safe" macro, checks for illegal sequences and for string boundaries. 504 * 505 * The length can be negative for a NUL-terminated string. 506 * 507 * @param s const uint8_t * string 508 * @param i int32_t string offset, must be i<length 509 * @param length int32_t string length 510 * @see U8_FWD_1_UNSAFE 511 * @stable ICU 2.4 512 */ 513 #define U8_FWD_1(s, i, length) { \ 514 uint8_t __b=(uint8_t)(s)[(i)++]; \ 515 if(U8_IS_LEAD(__b)) { \ 516 uint8_t __count=U8_COUNT_TRAIL_BYTES(__b); \ 517 if((i)+__count>(length) && (length)>=0) { \ 518 __count=(uint8_t)((length)-(i)); \ 519 } \ 520 while(__count>0 && U8_IS_TRAIL((s)[i])) { \ 521 ++(i); \ 522 --__count; \ 523 } \ 524 } \ 525 } 526 527 /** 528 * Advance the string offset from one code point boundary to the n-th next one, 529 * i.e., move forward by n code points. 530 * (Post-incrementing iteration.) 531 * "Unsafe" macro, assumes well-formed UTF-8. 532 * 533 * @param s const uint8_t * string 534 * @param i string offset 535 * @param n number of code points to skip 536 * @see U8_FWD_N 537 * @stable ICU 2.4 538 */ 539 #define U8_FWD_N_UNSAFE(s, i, n) { \ 540 int32_t __N=(n); \ 541 while(__N>0) { \ 542 U8_FWD_1_UNSAFE(s, i); \ 543 --__N; \ 544 } \ 545 } 546 547 /** 548 * Advance the string offset from one code point boundary to the n-th next one, 549 * i.e., move forward by n code points. 550 * (Post-incrementing iteration.) 551 * "Safe" macro, checks for illegal sequences and for string boundaries. 552 * 553 * The length can be negative for a NUL-terminated string. 554 * 555 * @param s const uint8_t * string 556 * @param i int32_t string offset, must be i<length 557 * @param length int32_t string length 558 * @param n number of code points to skip 559 * @see U8_FWD_N_UNSAFE 560 * @stable ICU 2.4 561 */ 562 #define U8_FWD_N(s, i, length, n) { \ 563 int32_t __N=(n); \ 564 while(__N>0 && ((i)<(length) || ((length)<0 && (s)[i]!=0))) { \ 565 U8_FWD_1(s, i, length); \ 566 --__N; \ 567 } \ 568 } 569 570 /** 571 * Adjust a random-access offset to a code point boundary 572 * at the start of a code point. 573 * If the offset points to a UTF-8 trail byte, 574 * then the offset is moved backward to the corresponding lead byte. 575 * Otherwise, it is not modified. 576 * "Unsafe" macro, assumes well-formed UTF-8. 577 * 578 * @param s const uint8_t * string 579 * @param i string offset 580 * @see U8_SET_CP_START 581 * @stable ICU 2.4 582 */ 583 #define U8_SET_CP_START_UNSAFE(s, i) { \ 584 while(U8_IS_TRAIL((s)[i])) { --(i); } \ 585 } 586 587 /** 588 * Adjust a random-access offset to a code point boundary 589 * at the start of a code point. 590 * If the offset points to a UTF-8 trail byte, 591 * then the offset is moved backward to the corresponding lead byte. 592 * Otherwise, it is not modified. 593 * "Safe" macro, checks for illegal sequences and for string boundaries. 594 * 595 * @param s const uint8_t * string 596 * @param start int32_t starting string offset (usually 0) 597 * @param i int32_t string offset, must be start<=i 598 * @see U8_SET_CP_START_UNSAFE 599 * @stable ICU 2.4 600 */ 601 #define U8_SET_CP_START(s, start, i) { \ 602 if(U8_IS_TRAIL((s)[(i)])) { \ 603 (i)=utf8_back1SafeBody(s, start, (i)); \ 604 } \ 605 } 606 607 /* definitions with backward iteration -------------------------------------- */ 608 609 /** 610 * Move the string offset from one code point boundary to the previous one 611 * and get the code point between them. 612 * (Pre-decrementing backward iteration.) 613 * "Unsafe" macro, assumes well-formed UTF-8. 614 * 615 * The input offset may be the same as the string length. 616 * If the offset is behind a multi-byte sequence, then the macro will read 617 * the whole sequence. 618 * If the offset is behind a lead byte, then that itself 619 * will be returned as the code point. 620 * The result is undefined if the offset is behind an illegal UTF-8 sequence. 621 * 622 * @param s const uint8_t * string 623 * @param i string offset 624 * @param c output UChar32 variable 625 * @see U8_PREV 626 * @stable ICU 2.4 627 */ 628 #define U8_PREV_UNSAFE(s, i, c) { \ 629 (c)=(uint8_t)(s)[--(i)]; \ 630 if(U8_IS_TRAIL(c)) { \ 631 uint8_t __b, __count=1, __shift=6; \ 632 \ 633 /* c is a trail byte */ \ 634 (c)&=0x3f; \ 635 for(;;) { \ 636 __b=(uint8_t)(s)[--(i)]; \ 637 if(__b>=0xc0) { \ 638 U8_MASK_LEAD_BYTE(__b, __count); \ 639 (c)|=(UChar32)__b<<__shift; \ 640 break; \ 641 } else { \ 642 (c)|=(UChar32)(__b&0x3f)<<__shift; \ 643 ++__count; \ 644 __shift+=6; \ 645 } \ 646 } \ 647 } \ 648 } 649 650 /** 651 * Move the string offset from one code point boundary to the previous one 652 * and get the code point between them. 653 * (Pre-decrementing backward iteration.) 654 * "Safe" macro, checks for illegal sequences and for string boundaries. 655 * 656 * The input offset may be the same as the string length. 657 * If the offset is behind a multi-byte sequence, then the macro will read 658 * the whole sequence. 659 * If the offset is behind a lead byte, then that itself 660 * will be returned as the code point. 661 * If the offset is behind an illegal UTF-8 sequence, then c is set to a negative value. 662 * 663 * @param s const uint8_t * string 664 * @param start int32_t starting string offset (usually 0) 665 * @param i int32_t string offset, must be start<i 666 * @param c output UChar32 variable, set to <0 in case of an error 667 * @see U8_PREV_UNSAFE 668 * @stable ICU 2.4 669 */ 670 #define U8_PREV(s, start, i, c) { \ 671 (c)=(uint8_t)(s)[--(i)]; \ 672 if((c)>=0x80) { \ 673 (c)=utf8_prevCharSafeBody((const uint8_t *)s, start, &(i), c, -1); \ 674 } \ 675 } 676 677 /** 678 * Move the string offset from one code point boundary to the previous one 679 * and get the code point between them. 680 * (Pre-decrementing backward iteration.) 681 * "Safe" macro, checks for illegal sequences and for string boundaries. 682 * 683 * The input offset may be the same as the string length. 684 * If the offset is behind a multi-byte sequence, then the macro will read 685 * the whole sequence. 686 * If the offset is behind a lead byte, then that itself 687 * will be returned as the code point. 688 * If the offset is behind an illegal UTF-8 sequence, then c is set to U+FFFD. 689 * 690 * This macro does not distinguish between a real U+FFFD in the text 691 * and U+FFFD returned for an ill-formed sequence. 692 * Use U8_PREV() if that distinction is important. 693 * 694 * @param s const uint8_t * string 695 * @param start int32_t starting string offset (usually 0) 696 * @param i int32_t string offset, must be start<i 697 * @param c output UChar32 variable, set to U+FFFD in case of an error 698 * @see U8_PREV 699 * @stable ICU 51 700 */ 701 #define U8_PREV_OR_FFFD(s, start, i, c) { \ 702 (c)=(uint8_t)(s)[--(i)]; \ 703 if((c)>=0x80) { \ 704 (c)=utf8_prevCharSafeBody((const uint8_t *)s, start, &(i), c, -3); \ 705 } \ 706 } 707 708 /** 709 * Move the string offset from one code point boundary to the previous one. 710 * (Pre-decrementing backward iteration.) 711 * The input offset may be the same as the string length. 712 * "Unsafe" macro, assumes well-formed UTF-8. 713 * 714 * @param s const uint8_t * string 715 * @param i string offset 716 * @see U8_BACK_1 717 * @stable ICU 2.4 718 */ 719 #define U8_BACK_1_UNSAFE(s, i) { \ 720 while(U8_IS_TRAIL((s)[--(i)])) {} \ 721 } 722 723 /** 724 * Move the string offset from one code point boundary to the previous one. 725 * (Pre-decrementing backward iteration.) 726 * The input offset may be the same as the string length. 727 * "Safe" macro, checks for illegal sequences and for string boundaries. 728 * 729 * @param s const uint8_t * string 730 * @param start int32_t starting string offset (usually 0) 731 * @param i int32_t string offset, must be start<i 732 * @see U8_BACK_1_UNSAFE 733 * @stable ICU 2.4 734 */ 735 #define U8_BACK_1(s, start, i) { \ 736 if(U8_IS_TRAIL((s)[--(i)])) { \ 737 (i)=utf8_back1SafeBody(s, start, (i)); \ 738 } \ 739 } 740 741 /** 742 * Move the string offset from one code point boundary to the n-th one before it, 743 * i.e., move backward by n code points. 744 * (Pre-decrementing backward iteration.) 745 * The input offset may be the same as the string length. 746 * "Unsafe" macro, assumes well-formed UTF-8. 747 * 748 * @param s const uint8_t * string 749 * @param i string offset 750 * @param n number of code points to skip 751 * @see U8_BACK_N 752 * @stable ICU 2.4 753 */ 754 #define U8_BACK_N_UNSAFE(s, i, n) { \ 755 int32_t __N=(n); \ 756 while(__N>0) { \ 757 U8_BACK_1_UNSAFE(s, i); \ 758 --__N; \ 759 } \ 760 } 761 762 /** 763 * Move the string offset from one code point boundary to the n-th one before it, 764 * i.e., move backward by n code points. 765 * (Pre-decrementing backward iteration.) 766 * The input offset may be the same as the string length. 767 * "Safe" macro, checks for illegal sequences and for string boundaries. 768 * 769 * @param s const uint8_t * string 770 * @param start int32_t index of the start of the string 771 * @param i int32_t string offset, must be start<i 772 * @param n number of code points to skip 773 * @see U8_BACK_N_UNSAFE 774 * @stable ICU 2.4 775 */ 776 #define U8_BACK_N(s, start, i, n) { \ 777 int32_t __N=(n); \ 778 while(__N>0 && (i)>(start)) { \ 779 U8_BACK_1(s, start, i); \ 780 --__N; \ 781 } \ 782 } 783 784 /** 785 * Adjust a random-access offset to a code point boundary after a code point. 786 * If the offset is behind a partial multi-byte sequence, 787 * then the offset is incremented to behind the whole sequence. 788 * Otherwise, it is not modified. 789 * The input offset may be the same as the string length. 790 * "Unsafe" macro, assumes well-formed UTF-8. 791 * 792 * @param s const uint8_t * string 793 * @param i string offset 794 * @see U8_SET_CP_LIMIT 795 * @stable ICU 2.4 796 */ 797 #define U8_SET_CP_LIMIT_UNSAFE(s, i) { \ 798 U8_BACK_1_UNSAFE(s, i); \ 799 U8_FWD_1_UNSAFE(s, i); \ 800 } 801 802 /** 803 * Adjust a random-access offset to a code point boundary after a code point. 804 * If the offset is behind a partial multi-byte sequence, 805 * then the offset is incremented to behind the whole sequence. 806 * Otherwise, it is not modified. 807 * The input offset may be the same as the string length. 808 * "Safe" macro, checks for illegal sequences and for string boundaries. 809 * 810 * The length can be negative for a NUL-terminated string. 811 * 812 * @param s const uint8_t * string 813 * @param start int32_t starting string offset (usually 0) 814 * @param i int32_t string offset, must be start<=i<=length 815 * @param length int32_t string length 816 * @see U8_SET_CP_LIMIT_UNSAFE 817 * @stable ICU 2.4 818 */ 819 #define U8_SET_CP_LIMIT(s, start, i, length) { \ 820 if((start)<(i) && ((i)<(length) || (length)<0)) { \ 821 U8_BACK_1(s, start, i); \ 822 U8_FWD_1(s, i, length); \ 823 } \ 824 } 825 826 #endif 827