/usr/include/thunderbird/unicode/chariter.h is in thunderbird-dev 1:52.8.0-1~deb8u1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 | // Copyright (C) 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
/*
********************************************************************
*
* Copyright (C) 1997-2011, International Business Machines
* Corporation and others. All Rights Reserved.
*
********************************************************************
*/
#ifndef CHARITER_H
#define CHARITER_H
#include "unicode/utypes.h"
#include "unicode/uobject.h"
#include "unicode/unistr.h"
/**
* \file
* \brief C++ API: Character Iterator
*/
U_NAMESPACE_BEGIN
/**
* Abstract class that defines an API for forward-only iteration
* on text objects.
* This is a minimal interface for iteration without random access
* or backwards iteration. It is especially useful for wrapping
* streams with converters into an object for collation or
* normalization.
*
* <p>Characters can be accessed in two ways: as code units or as
* code points.
* Unicode code points are 21-bit integers and are the scalar values
* of Unicode characters. ICU uses the type UChar32 for them.
* Unicode code units are the storage units of a given
* Unicode/UCS Transformation Format (a character encoding scheme).
* With UTF-16, all code points can be represented with either one
* or two code units ("surrogates").
* String storage is typically based on code units, while properties
* of characters are typically determined using code point values.
* Some processes may be designed to work with sequences of code units,
* or it may be known that all characters that are important to an
* algorithm can be represented with single code units.
* Other processes will need to use the code point access functions.</p>
*
* <p>ForwardCharacterIterator provides nextPostInc() to access
* a code unit and advance an internal position into the text object,
* similar to a <code>return text[position++]</code>.<br>
* It provides next32PostInc() to access a code point and advance an internal
* position.</p>
*
* <p>next32PostInc() assumes that the current position is that of
* the beginning of a code point, i.e., of its first code unit.
* After next32PostInc(), this will be true again.
* In general, access to code units and code points in the same
* iteration loop should not be mixed. In UTF-16, if the current position
* is on a second code unit (Low Surrogate), then only that code unit
* is returned even by next32PostInc().</p>
*
* <p>For iteration with either function, there are two ways to
* check for the end of the iteration. When there are no more
* characters in the text object:
* <ul>
* <li>The hasNext() function returns FALSE.</li>
* <li>nextPostInc() and next32PostInc() return DONE
* when one attempts to read beyond the end of the text object.</li>
* </ul>
*
* Example:
* \code
* void function1(ForwardCharacterIterator &it) {
* UChar32 c;
* while(it.hasNext()) {
* c=it.next32PostInc();
* // use c
* }
* }
*
* void function1(ForwardCharacterIterator &it) {
* UChar c;
* while((c=it.nextPostInc())!=ForwardCharacterIterator::DONE) {
* // use c
* }
* }
* \endcode
* </p>
*
* @stable ICU 2.0
*/
class U_COMMON_API ForwardCharacterIterator : public UObject {
public:
/**
* Value returned by most of ForwardCharacterIterator's functions
* when the iterator has reached the limits of its iteration.
* @stable ICU 2.0
*/
enum { DONE = 0xffff };
/**
* Destructor.
* @stable ICU 2.0
*/
virtual ~ForwardCharacterIterator();
/**
* Returns true when both iterators refer to the same
* character in the same character-storage object.
* @param that The ForwardCharacterIterator to be compared for equality
* @return true when both iterators refer to the same
* character in the same character-storage object
* @stable ICU 2.0
*/
virtual UBool operator==(const ForwardCharacterIterator& that) const = 0;
/**
* Returns true when the iterators refer to different
* text-storage objects, or to different characters in the
* same text-storage object.
* @param that The ForwardCharacterIterator to be compared for inequality
* @return true when the iterators refer to different
* text-storage objects, or to different characters in the
* same text-storage object
* @stable ICU 2.0
*/
inline UBool operator!=(const ForwardCharacterIterator& that) const;
/**
* Generates a hash code for this iterator.
* @return the hash code.
* @stable ICU 2.0
*/
virtual int32_t hashCode(void) const = 0;
/**
* Returns a UClassID for this ForwardCharacterIterator ("poor man's
* RTTI").<P> Despite the fact that this function is public,
* DO NOT CONSIDER IT PART OF CHARACTERITERATOR'S API!
* @return a UClassID for this ForwardCharacterIterator
* @stable ICU 2.0
*/
virtual UClassID getDynamicClassID(void) const = 0;
/**
* Gets the current code unit for returning and advances to the next code unit
* in the iteration range
* (toward endIndex()). If there are
* no more code units to return, returns DONE.
* @return the current code unit.
* @stable ICU 2.0
*/
virtual UChar nextPostInc(void) = 0;
/**
* Gets the current code point for returning and advances to the next code point
* in the iteration range
* (toward endIndex()). If there are
* no more code points to return, returns DONE.
* @return the current code point.
* @stable ICU 2.0
*/
virtual UChar32 next32PostInc(void) = 0;
/**
* Returns FALSE if there are no more code units or code points
* at or after the current position in the iteration range.
* This is used with nextPostInc() or next32PostInc() in forward
* iteration.
* @returns FALSE if there are no more code units or code points
* at or after the current position in the iteration range.
* @stable ICU 2.0
*/
virtual UBool hasNext() = 0;
protected:
/** Default constructor to be overridden in the implementing class. @stable ICU 2.0*/
ForwardCharacterIterator();
/** Copy constructor to be overridden in the implementing class. @stable ICU 2.0*/
ForwardCharacterIterator(const ForwardCharacterIterator &other);
/**
* Assignment operator to be overridden in the implementing class.
* @stable ICU 2.0
*/
ForwardCharacterIterator &operator=(const ForwardCharacterIterator&) { return *this; }
};
/**
* Abstract class that defines an API for iteration
* on text objects.
* This is an interface for forward and backward iteration
* and random access into a text object.
*
* <p>The API provides backward compatibility to the Java and older ICU
* CharacterIterator classes but extends them significantly:
* <ol>
* <li>CharacterIterator is now a subclass of ForwardCharacterIterator.</li>
* <li>While the old API functions provided forward iteration with
* "pre-increment" semantics, the new one also provides functions
* with "post-increment" semantics. They are more efficient and should
* be the preferred iterator functions for new implementations.
* The backward iteration always had "pre-decrement" semantics, which
* are efficient.</li>
* <li>Just like ForwardCharacterIterator, it provides access to
* both code units and code points. Code point access versions are available
* for the old and the new iteration semantics.</li>
* <li>There are new functions for setting and moving the current position
* without returning a character, for efficiency.</li>
* </ol>
*
* See ForwardCharacterIterator for examples for using the new forward iteration
* functions. For backward iteration, there is also a hasPrevious() function
* that can be used analogously to hasNext().
* The old functions work as before and are shown below.</p>
*
* <p>Examples for some of the new functions:</p>
*
* Forward iteration with hasNext():
* \code
* void forward1(CharacterIterator &it) {
* UChar32 c;
* for(it.setToStart(); it.hasNext();) {
* c=it.next32PostInc();
* // use c
* }
* }
* \endcode
* Forward iteration more similar to loops with the old forward iteration,
* showing a way to convert simple for() loops:
* \code
* void forward2(CharacterIterator &it) {
* UChar c;
* for(c=it.firstPostInc(); c!=CharacterIterator::DONE; c=it.nextPostInc()) {
* // use c
* }
* }
* \endcode
* Backward iteration with setToEnd() and hasPrevious():
* \code
* void backward1(CharacterIterator &it) {
* UChar32 c;
* for(it.setToEnd(); it.hasPrevious();) {
* c=it.previous32();
* // use c
* }
* }
* \endcode
* Backward iteration with a more traditional for() loop:
* \code
* void backward2(CharacterIterator &it) {
* UChar c;
* for(c=it.last(); c!=CharacterIterator::DONE; c=it.previous()) {
* // use c
* }
* }
* \endcode
*
* Example for random access:
* \code
* void random(CharacterIterator &it) {
* // set to the third code point from the beginning
* it.move32(3, CharacterIterator::kStart);
* // get a code point from here without moving the position
* UChar32 c=it.current32();
* // get the position
* int32_t pos=it.getIndex();
* // get the previous code unit
* UChar u=it.previous();
* // move back one more code unit
* it.move(-1, CharacterIterator::kCurrent);
* // set the position back to where it was
* // and read the same code point c and move beyond it
* it.setIndex(pos);
* if(c!=it.next32PostInc()) {
* exit(1); // CharacterIterator inconsistent
* }
* }
* \endcode
*
* <p>Examples, especially for the old API:</p>
*
* Function processing characters, in this example simple output
* <pre>
* \code
* void processChar( UChar c )
* {
* cout << " " << c;
* }
* \endcode
* </pre>
* Traverse the text from start to finish
* <pre>
* \code
* void traverseForward(CharacterIterator& iter)
* {
* for(UChar c = iter.first(); c != CharacterIterator.DONE; c = iter.next()) {
* processChar(c);
* }
* }
* \endcode
* </pre>
* Traverse the text backwards, from end to start
* <pre>
* \code
* void traverseBackward(CharacterIterator& iter)
* {
* for(UChar c = iter.last(); c != CharacterIterator.DONE; c = iter.previous()) {
* processChar(c);
* }
* }
* \endcode
* </pre>
* Traverse both forward and backward from a given position in the text.
* Calls to notBoundary() in this example represents some additional stopping criteria.
* <pre>
* \code
* void traverseOut(CharacterIterator& iter, int32_t pos)
* {
* UChar c;
* for (c = iter.setIndex(pos);
* c != CharacterIterator.DONE && (Unicode::isLetter(c) || Unicode::isDigit(c));
* c = iter.next()) {}
* int32_t end = iter.getIndex();
* for (c = iter.setIndex(pos);
* c != CharacterIterator.DONE && (Unicode::isLetter(c) || Unicode::isDigit(c));
* c = iter.previous()) {}
* int32_t start = iter.getIndex() + 1;
*
* cout << "start: " << start << " end: " << end << endl;
* for (c = iter.setIndex(start); iter.getIndex() < end; c = iter.next() ) {
* processChar(c);
* }
* }
* \endcode
* </pre>
* Creating a StringCharacterIterator and calling the test functions
* <pre>
* \code
* void CharacterIterator_Example( void )
* {
* cout << endl << "===== CharacterIterator_Example: =====" << endl;
* UnicodeString text("Ein kleiner Satz.");
* StringCharacterIterator iterator(text);
* cout << "----- traverseForward: -----------" << endl;
* traverseForward( iterator );
* cout << endl << endl << "----- traverseBackward: ----------" << endl;
* traverseBackward( iterator );
* cout << endl << endl << "----- traverseOut: ---------------" << endl;
* traverseOut( iterator, 7 );
* cout << endl << endl << "-----" << endl;
* }
* \endcode
* </pre>
*
* @stable ICU 2.0
*/
class U_COMMON_API CharacterIterator : public ForwardCharacterIterator {
public:
/**
* Origin enumeration for the move() and move32() functions.
* @stable ICU 2.0
*/
enum EOrigin { kStart, kCurrent, kEnd };
/**
* Destructor.
* @stable ICU 2.0
*/
virtual ~CharacterIterator();
/**
* Returns a pointer to a new CharacterIterator of the same
* concrete class as this one, and referring to the same
* character in the same text-storage object as this one. The
* caller is responsible for deleting the new clone.
* @return a pointer to a new CharacterIterator
* @stable ICU 2.0
*/
virtual CharacterIterator* clone(void) const = 0;
/**
* Sets the iterator to refer to the first code unit in its
* iteration range, and returns that code unit.
* This can be used to begin an iteration with next().
* @return the first code unit in its iteration range.
* @stable ICU 2.0
*/
virtual UChar first(void) = 0;
/**
* Sets the iterator to refer to the first code unit in its
* iteration range, returns that code unit, and moves the position
* to the second code unit. This is an alternative to setToStart()
* for forward iteration with nextPostInc().
* @return the first code unit in its iteration range.
* @stable ICU 2.0
*/
virtual UChar firstPostInc(void);
/**
* Sets the iterator to refer to the first code point in its
* iteration range, and returns that code unit,
* This can be used to begin an iteration with next32().
* Note that an iteration with next32PostInc(), beginning with,
* e.g., setToStart() or firstPostInc(), is more efficient.
* @return the first code point in its iteration range.
* @stable ICU 2.0
*/
virtual UChar32 first32(void) = 0;
/**
* Sets the iterator to refer to the first code point in its
* iteration range, returns that code point, and moves the position
* to the second code point. This is an alternative to setToStart()
* for forward iteration with next32PostInc().
* @return the first code point in its iteration range.
* @stable ICU 2.0
*/
virtual UChar32 first32PostInc(void);
/**
* Sets the iterator to refer to the first code unit or code point in its
* iteration range. This can be used to begin a forward
* iteration with nextPostInc() or next32PostInc().
* @return the start position of the iteration range
* @stable ICU 2.0
*/
inline int32_t setToStart();
/**
* Sets the iterator to refer to the last code unit in its
* iteration range, and returns that code unit.
* This can be used to begin an iteration with previous().
* @return the last code unit.
* @stable ICU 2.0
*/
virtual UChar last(void) = 0;
/**
* Sets the iterator to refer to the last code point in its
* iteration range, and returns that code unit.
* This can be used to begin an iteration with previous32().
* @return the last code point.
* @stable ICU 2.0
*/
virtual UChar32 last32(void) = 0;
/**
* Sets the iterator to the end of its iteration range, just behind
* the last code unit or code point. This can be used to begin a backward
* iteration with previous() or previous32().
* @return the end position of the iteration range
* @stable ICU 2.0
*/
inline int32_t setToEnd();
/**
* Sets the iterator to refer to the "position"-th code unit
* in the text-storage object the iterator refers to, and
* returns that code unit.
* @param position the "position"-th code unit in the text-storage object
* @return the "position"-th code unit.
* @stable ICU 2.0
*/
virtual UChar setIndex(int32_t position) = 0;
/**
* Sets the iterator to refer to the beginning of the code point
* that contains the "position"-th code unit
* in the text-storage object the iterator refers to, and
* returns that code point.
* The current position is adjusted to the beginning of the code point
* (its first code unit).
* @param position the "position"-th code unit in the text-storage object
* @return the "position"-th code point.
* @stable ICU 2.0
*/
virtual UChar32 setIndex32(int32_t position) = 0;
/**
* Returns the code unit the iterator currently refers to.
* @return the current code unit.
* @stable ICU 2.0
*/
virtual UChar current(void) const = 0;
/**
* Returns the code point the iterator currently refers to.
* @return the current code point.
* @stable ICU 2.0
*/
virtual UChar32 current32(void) const = 0;
/**
* Advances to the next code unit in the iteration range
* (toward endIndex()), and returns that code unit. If there are
* no more code units to return, returns DONE.
* @return the next code unit.
* @stable ICU 2.0
*/
virtual UChar next(void) = 0;
/**
* Advances to the next code point in the iteration range
* (toward endIndex()), and returns that code point. If there are
* no more code points to return, returns DONE.
* Note that iteration with "pre-increment" semantics is less
* efficient than iteration with "post-increment" semantics
* that is provided by next32PostInc().
* @return the next code point.
* @stable ICU 2.0
*/
virtual UChar32 next32(void) = 0;
/**
* Advances to the previous code unit in the iteration range
* (toward startIndex()), and returns that code unit. If there are
* no more code units to return, returns DONE.
* @return the previous code unit.
* @stable ICU 2.0
*/
virtual UChar previous(void) = 0;
/**
* Advances to the previous code point in the iteration range
* (toward startIndex()), and returns that code point. If there are
* no more code points to return, returns DONE.
* @return the previous code point.
* @stable ICU 2.0
*/
virtual UChar32 previous32(void) = 0;
/**
* Returns FALSE if there are no more code units or code points
* before the current position in the iteration range.
* This is used with previous() or previous32() in backward
* iteration.
* @return FALSE if there are no more code units or code points
* before the current position in the iteration range, return TRUE otherwise.
* @stable ICU 2.0
*/
virtual UBool hasPrevious() = 0;
/**
* Returns the numeric index in the underlying text-storage
* object of the character returned by first(). Since it's
* possible to create an iterator that iterates across only
* part of a text-storage object, this number isn't
* necessarily 0.
* @returns the numeric index in the underlying text-storage
* object of the character returned by first().
* @stable ICU 2.0
*/
inline int32_t startIndex(void) const;
/**
* Returns the numeric index in the underlying text-storage
* object of the position immediately BEYOND the character
* returned by last().
* @return the numeric index in the underlying text-storage
* object of the position immediately BEYOND the character
* returned by last().
* @stable ICU 2.0
*/
inline int32_t endIndex(void) const;
/**
* Returns the numeric index in the underlying text-storage
* object of the character the iterator currently refers to
* (i.e., the character returned by current()).
* @return the numberic index in the text-storage object of
* the character the iterator currently refers to
* @stable ICU 2.0
*/
inline int32_t getIndex(void) const;
/**
* Returns the length of the entire text in the underlying
* text-storage object.
* @return the length of the entire text in the text-storage object
* @stable ICU 2.0
*/
inline int32_t getLength() const;
/**
* Moves the current position relative to the start or end of the
* iteration range, or relative to the current position itself.
* The movement is expressed in numbers of code units forward
* or backward by specifying a positive or negative delta.
* @param delta the position relative to origin. A positive delta means forward;
* a negative delta means backward.
* @param origin Origin enumeration {kStart, kCurrent, kEnd}
* @return the new position
* @stable ICU 2.0
*/
virtual int32_t move(int32_t delta, EOrigin origin) = 0;
/**
* Moves the current position relative to the start or end of the
* iteration range, or relative to the current position itself.
* The movement is expressed in numbers of code points forward
* or backward by specifying a positive or negative delta.
* @param delta the position relative to origin. A positive delta means forward;
* a negative delta means backward.
* @param origin Origin enumeration {kStart, kCurrent, kEnd}
* @return the new position
* @stable ICU 2.0
*/
virtual int32_t move32(int32_t delta, EOrigin origin) = 0;
/**
* Copies the text under iteration into the UnicodeString
* referred to by "result".
* @param result Receives a copy of the text under iteration.
* @stable ICU 2.0
*/
virtual void getText(UnicodeString& result) = 0;
protected:
/**
* Empty constructor.
* @stable ICU 2.0
*/
CharacterIterator();
/**
* Constructor, just setting the length field in this base class.
* @stable ICU 2.0
*/
CharacterIterator(int32_t length);
/**
* Constructor, just setting the length and position fields in this base class.
* @stable ICU 2.0
*/
CharacterIterator(int32_t length, int32_t position);
/**
* Constructor, just setting the length, start, end, and position fields in this base class.
* @stable ICU 2.0
*/
CharacterIterator(int32_t length, int32_t textBegin, int32_t textEnd, int32_t position);
/**
* Copy constructor.
*
* @param that The CharacterIterator to be copied
* @stable ICU 2.0
*/
CharacterIterator(const CharacterIterator &that);
/**
* Assignment operator. Sets this CharacterIterator to have the same behavior,
* as the one passed in.
* @param that The CharacterIterator passed in.
* @return the newly set CharacterIterator.
* @stable ICU 2.0
*/
CharacterIterator &operator=(const CharacterIterator &that);
/**
* Base class text length field.
* Necessary this for correct getText() and hashCode().
* @stable ICU 2.0
*/
int32_t textLength;
/**
* Base class field for the current position.
* @stable ICU 2.0
*/
int32_t pos;
/**
* Base class field for the start of the iteration range.
* @stable ICU 2.0
*/
int32_t begin;
/**
* Base class field for the end of the iteration range.
* @stable ICU 2.0
*/
int32_t end;
};
inline UBool
ForwardCharacterIterator::operator!=(const ForwardCharacterIterator& that) const {
return !operator==(that);
}
inline int32_t
CharacterIterator::setToStart() {
return move(0, kStart);
}
inline int32_t
CharacterIterator::setToEnd() {
return move(0, kEnd);
}
inline int32_t
CharacterIterator::startIndex(void) const {
return begin;
}
inline int32_t
CharacterIterator::endIndex(void) const {
return end;
}
inline int32_t
CharacterIterator::getIndex(void) const {
return pos;
}
inline int32_t
CharacterIterator::getLength(void) const {
return textLength;
}
U_NAMESPACE_END
#endif
|