base/i18n/char_iterator.h

   1 // Copyright 2011 The Chromium Authors
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef BASE_I18N_CHAR_ITERATOR_H_
   6 #define BASE_I18N_CHAR_ITERATOR_H_
   7
   8 #include <stdint.h>
   9
  10 #include "base/i18n/base_i18n_export.h"
  11 #include "base/strings/string_piece.h"
  12
  13 // The CharIterator classes iterate through the characters in UTF8 and
  14 // UTF16 strings.  Example usage:
  15 //
  16 //   for (UTF8CharIterator iter(str); !iter.end(); iter.Advance()) {
  17 //     VLOG(1) << iter.get();
  18 //   }
  19
  20 namespace base {
  21 namespace i18n {
  22
  23 class BASE_I18N_EXPORT UTF8CharIterator {
  24  public:
  25   // Requires |str| to live as long as the UTF8CharIterator does.
  26   explicit UTF8CharIterator(StringPiece str);
  27   UTF8CharIterator(const UTF8CharIterator&) = delete;
  28   UTF8CharIterator& operator=(const UTF8CharIterator&) = delete;
  29   ~UTF8CharIterator();
  30
  31   // Return the starting array index of the current character within the
  32   // string.
  33   size_t array_pos() const { return array_pos_; }
  34
  35   // Return the logical index of the current character, independent of the
  36   // number of bytes each character takes.
  37   size_t char_pos() const { return char_pos_; }
  38
  39   // Return the current char.
  40   int32_t get() const { return char_; }
  41
  42   // Returns true if we're at the end of the string.
  43   bool end() const { return array_pos_ == str_.length(); }
  44
  45   // Advance to the next actual character.  Returns false if we're at the
  46   // end of the string.
  47   bool Advance();
  48
  49  private:
  50   // The string we're iterating over.
  51   StringPiece str_;
  52
  53   // Array index.
  54   size_t array_pos_;
  55
  56   // The next array index.
  57   size_t next_pos_;
  58
  59   // Character index.
  60   size_t char_pos_;
  61
  62   // The current character.
  63   int32_t char_;
  64 };
  65
  66 class BASE_I18N_EXPORT UTF16CharIterator {
  67  public:
  68   // Requires |str| to live as long as the UTF16CharIterator does.
  69   explicit UTF16CharIterator(StringPiece16 str);
  70   UTF16CharIterator(UTF16CharIterator&& to_move);
  71   UTF16CharIterator& operator=(UTF16CharIterator&& to_move);
  72
  73   UTF16CharIterator(const UTF16CharIterator&) = delete;
  74   UTF16CharIterator operator=(const UTF16CharIterator&) = delete;
  75
  76   ~UTF16CharIterator();
  77
  78   // Returns an iterator starting on the unicode character at offset
  79   // |array_index| into the string, or the previous array offset if
  80   // |array_index| is the second half of a surrogate pair.
  81   static UTF16CharIterator LowerBound(StringPiece16 str, size_t array_index);
  82
  83   // Returns an iterator starting on the unicode character at offset
  84   // |array_index| into the string, or the next offset if |array_index| is the
  85   // second half of a surrogate pair.
  86   static UTF16CharIterator UpperBound(StringPiece16 str, size_t array_index);
  87
  88   // Return the starting array index of the current character within the
  89   // string.
  90   size_t array_pos() const { return array_pos_; }
  91
  92   // Returns the offset in code points from the initial iterator position, which
  93   // could be negative if Rewind() is called. The initial value is always zero,
  94   // regardless of how the iterator is constructed.
  95   int32_t char_offset() const { return char_offset_; }
  96
  97   // Returns the code point at the current position.
  98   int32_t get() const { return char_; }
  99
 100   // Returns the code point (i.e. the full Unicode character, not half of a
 101   // surrogate pair) following the current one. Should not be called if end() is
 102   // true. If the current code point is the last one in the string, returns
 103   // zero.
 104   int32_t NextCodePoint() const;
 105
 106   // Returns the code point (i.e. the full Unicode character, not half of a
 107   // surrogate pair) preceding the current one. Should not be called if start()
 108   // is true.
 109   int32_t PreviousCodePoint() const;
 110
 111   // Returns true if we're at the start of the string.
 112   bool start() const { return array_pos_ == 0; }
 113
 114   // Returns true if we're at the end of the string.
 115   bool end() const { return array_pos_ == str_.length(); }
 116
 117   // Advances to the next actual character.  Returns false if we're at the
 118   // end of the string.
 119   bool Advance();
 120
 121   // Moves to the previous actual character. Returns false if we're at the start
 122   // of the string.
 123   bool Rewind();
 124
 125  private:
 126   UTF16CharIterator(base::StringPiece16 str, size_t initial_pos);
 127
 128   // Fills in the current character we found and advances to the next
 129   // character, updating all flags as necessary.
 130   void ReadChar();
 131
 132   // The string we're iterating over.
 133   StringPiece16 str_;
 134
 135   // Array index.
 136   size_t array_pos_;
 137
 138   // The next array index.
 139   size_t next_pos_;
 140
 141   // Character offset from the initial position of the iterator.
 142   int32_t char_offset_;
 143
 144   // The current character.
 145   int32_t char_;
 146 };
 147
 148 }  // namespace i18n
 149 }  // namespace base
 150
 151 #endif  // BASE_I18N_CHAR_ITERATOR_H_