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
24namespace Poco {
25
26
27class TextEncoding;
28
29
30class 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{
51public:
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
104private:
105 const TextEncoding* _pEncoding;
106 std::string::const_iterator _it;
107 std::string::const_iterator _end;
108};
109
110
111//
112// inlines
113//
114inline bool TextIterator::operator == (const TextIterator& it) const
115{
116 return _it == it._it;
117}
118
119
120inline bool TextIterator::operator != (const TextIterator& it) const
121{
122 return _it != it._it;
123}
124
125
126inline void swap(TextIterator& it1, TextIterator& it2)
127{
128 it1.swap(it2);
129}
130
131
132inline TextIterator TextIterator::end() const
133{
134 return TextIterator(_end);
135}
136
137
138} // namespace Poco
139
140
141#endif // Foundation_TextIterator_INCLUDED
142