1 | // |
2 | // TextIterator.h |
3 | // |
4 | // Library: Foundation |
5 | // Package: Text |
6 | // Module: TextIterator |
7 | // |
8 | // Definition of the TextIterator class. |
9 | // |
10 | // Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH. |
11 | // and Contributors. |
12 | // |
13 | // SPDX-License-Identifier: BSL-1.0 |
14 | // |
15 | |
16 | |
17 | #ifndef Foundation_TextIterator_INCLUDED |
18 | #define Foundation_TextIterator_INCLUDED |
19 | |
20 | |
21 | #include "Poco/Foundation.h" |
22 | |
23 | |
24 | namespace Poco { |
25 | |
26 | |
27 | class TextEncoding; |
28 | |
29 | |
30 | class Foundation_API TextIterator |
31 | /// An unidirectional iterator for iterating over characters in a string. |
32 | /// The TextIterator uses a TextEncoding object to |
33 | /// work with multi-byte character encodings like UTF-8. |
34 | /// Characters are reported in Unicode. |
35 | /// |
36 | /// Example: Count the number of UTF-8 characters in a string. |
37 | /// |
38 | /// UTF8Encoding utf8Encoding; |
39 | /// std::string utf8String("...."); |
40 | /// TextIterator it(utf8String, utf8Encoding); |
41 | /// TextIterator end(utf8String); |
42 | /// int n = 0; |
43 | /// while (it != end) { ++n; ++it; } |
44 | /// |
45 | /// NOTE: When an UTF-16 encoding is used, surrogate pairs will be |
46 | /// reported as two separate characters, due to restrictions of |
47 | /// the TextEncoding class. |
48 | /// |
49 | /// For iterating over char buffers, see the TextBufferIterator class. |
50 | { |
51 | public: |
52 | TextIterator(); |
53 | /// Creates an uninitialized TextIterator. |
54 | |
55 | TextIterator(const std::string& str, const TextEncoding& encoding); |
56 | /// Creates a TextIterator for the given string. |
57 | /// The encoding object must not be deleted as long as the iterator |
58 | /// is in use. |
59 | |
60 | TextIterator(const std::string::const_iterator& begin, const std::string::const_iterator& end, const TextEncoding& encoding); |
61 | /// Creates a TextIterator for the given range. |
62 | /// The encoding object must not be deleted as long as the iterator |
63 | /// is in use. |
64 | |
65 | TextIterator(const std::string& str); |
66 | /// Creates an end TextIterator for the given string. |
67 | |
68 | TextIterator(const std::string::const_iterator& end); |
69 | /// Creates an end TextIterator. |
70 | |
71 | ~TextIterator(); |
72 | /// Destroys the TextIterator. |
73 | |
74 | TextIterator(const TextIterator& it); |
75 | /// Copy constructor. |
76 | |
77 | TextIterator& operator = (const TextIterator& it); |
78 | /// Assignment operator. |
79 | |
80 | void swap(TextIterator& it); |
81 | /// Swaps the iterator with another one. |
82 | |
83 | int operator * () const; |
84 | /// Returns the Unicode value of the current character. |
85 | /// If there is no valid character at the current position, |
86 | /// -1 is returned. |
87 | |
88 | TextIterator& operator ++ (); |
89 | /// Prefix increment operator. |
90 | |
91 | TextIterator operator ++ (int); |
92 | /// Postfix increment operator. |
93 | |
94 | bool operator == (const TextIterator& it) const; |
95 | /// Compares two iterators for equality. |
96 | |
97 | bool operator != (const TextIterator& it) const; |
98 | /// Compares two iterators for inequality. |
99 | |
100 | TextIterator end() const; |
101 | /// Returns the end iterator for the range handled |
102 | /// by the iterator. |
103 | |
104 | private: |
105 | const TextEncoding* _pEncoding; |
106 | std::string::const_iterator _it; |
107 | std::string::const_iterator _end; |
108 | }; |
109 | |
110 | |
111 | // |
112 | // inlines |
113 | // |
114 | inline bool TextIterator::operator == (const TextIterator& it) const |
115 | { |
116 | return _it == it._it; |
117 | } |
118 | |
119 | |
120 | inline bool TextIterator::operator != (const TextIterator& it) const |
121 | { |
122 | return _it != it._it; |
123 | } |
124 | |
125 | |
126 | inline void swap(TextIterator& it1, TextIterator& it2) |
127 | { |
128 | it1.swap(it2); |
129 | } |
130 | |
131 | |
132 | inline TextIterator TextIterator::end() const |
133 | { |
134 | return TextIterator(_end); |
135 | } |
136 | |
137 | |
138 | } // namespace Poco |
139 | |
140 | |
141 | #endif // Foundation_TextIterator_INCLUDED |
142 | |