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