1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/common/unicode/uchriter.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,381 @@
1.4 +/*
1.5 +**********************************************************************
1.6 +* Copyright (C) 1998-2005, International Business Machines
1.7 +* Corporation and others. All Rights Reserved.
1.8 +**********************************************************************
1.9 +*/
1.10 +
1.11 +#ifndef UCHRITER_H
1.12 +#define UCHRITER_H
1.13 +
1.14 +#include "unicode/utypes.h"
1.15 +#include "unicode/chariter.h"
1.16 +
1.17 +/**
1.18 + * \file
1.19 + * \brief C++ API: UChar Character Iterator
1.20 + */
1.21 +
1.22 +U_NAMESPACE_BEGIN
1.23 +
1.24 +/**
1.25 + * A concrete subclass of CharacterIterator that iterates over the
1.26 + * characters (code units or code points) in a UChar array.
1.27 + * It's possible not only to create an
1.28 + * iterator that iterates over an entire UChar array, but also to
1.29 + * create one that iterates over only a subrange of a UChar array
1.30 + * (iterators over different subranges of the same UChar array don't
1.31 + * compare equal).
1.32 + * @see CharacterIterator
1.33 + * @see ForwardCharacterIterator
1.34 + * @stable ICU 2.0
1.35 + */
1.36 +class U_COMMON_API UCharCharacterIterator : public CharacterIterator {
1.37 +public:
1.38 + /**
1.39 + * Create an iterator over the UChar array referred to by "textPtr".
1.40 + * The iteration range is 0 to <code>length-1</code>.
1.41 + * text is only aliased, not adopted (the
1.42 + * destructor will not delete it).
1.43 + * @param textPtr The UChar array to be iterated over
1.44 + * @param length The length of the UChar array
1.45 + * @stable ICU 2.0
1.46 + */
1.47 + UCharCharacterIterator(const UChar* textPtr, int32_t length);
1.48 +
1.49 + /**
1.50 + * Create an iterator over the UChar array referred to by "textPtr".
1.51 + * The iteration range is 0 to <code>length-1</code>.
1.52 + * text is only aliased, not adopted (the
1.53 + * destructor will not delete it).
1.54 + * The starting
1.55 + * position is specified by "position". If "position" is outside the valid
1.56 + * iteration range, the behavior of this object is undefined.
1.57 + * @param textPtr The UChar array to be iteratd over
1.58 + * @param length The length of the UChar array
1.59 + * @param position The starting position of the iteration
1.60 + * @stable ICU 2.0
1.61 + */
1.62 + UCharCharacterIterator(const UChar* textPtr, int32_t length,
1.63 + int32_t position);
1.64 +
1.65 + /**
1.66 + * Create an iterator over the UChar array referred to by "textPtr".
1.67 + * The iteration range is 0 to <code>end-1</code>.
1.68 + * text is only aliased, not adopted (the
1.69 + * destructor will not delete it).
1.70 + * The starting
1.71 + * position is specified by "position". If begin and end do not
1.72 + * form a valid iteration range or "position" is outside the valid
1.73 + * iteration range, the behavior of this object is undefined.
1.74 + * @param textPtr The UChar array to be iterated over
1.75 + * @param length The length of the UChar array
1.76 + * @param textBegin The begin position of the iteration range
1.77 + * @param textEnd The end position of the iteration range
1.78 + * @param position The starting position of the iteration
1.79 + * @stable ICU 2.0
1.80 + */
1.81 + UCharCharacterIterator(const UChar* textPtr, int32_t length,
1.82 + int32_t textBegin,
1.83 + int32_t textEnd,
1.84 + int32_t position);
1.85 +
1.86 + /**
1.87 + * Copy constructor. The new iterator iterates over the same range
1.88 + * of the same string as "that", and its initial position is the
1.89 + * same as "that"'s current position.
1.90 + * @param that The UCharCharacterIterator to be copied
1.91 + * @stable ICU 2.0
1.92 + */
1.93 + UCharCharacterIterator(const UCharCharacterIterator& that);
1.94 +
1.95 + /**
1.96 + * Destructor.
1.97 + * @stable ICU 2.0
1.98 + */
1.99 + virtual ~UCharCharacterIterator();
1.100 +
1.101 + /**
1.102 + * Assignment operator. *this is altered to iterate over the sane
1.103 + * range of the same string as "that", and refers to the same
1.104 + * character within that string as "that" does.
1.105 + * @param that The object to be copied
1.106 + * @return the newly created object
1.107 + * @stable ICU 2.0
1.108 + */
1.109 + UCharCharacterIterator&
1.110 + operator=(const UCharCharacterIterator& that);
1.111 +
1.112 + /**
1.113 + * Returns true if the iterators iterate over the same range of the
1.114 + * same string and are pointing at the same character.
1.115 + * @param that The ForwardCharacterIterator used to be compared for equality
1.116 + * @return true if the iterators iterate over the same range of the
1.117 + * same string and are pointing at the same character.
1.118 + * @stable ICU 2.0
1.119 + */
1.120 + virtual UBool operator==(const ForwardCharacterIterator& that) const;
1.121 +
1.122 + /**
1.123 + * Generates a hash code for this iterator.
1.124 + * @return the hash code.
1.125 + * @stable ICU 2.0
1.126 + */
1.127 + virtual int32_t hashCode(void) const;
1.128 +
1.129 + /**
1.130 + * Returns a new UCharCharacterIterator referring to the same
1.131 + * character in the same range of the same string as this one. The
1.132 + * caller must delete the new iterator.
1.133 + * @return the CharacterIterator newly created
1.134 + * @stable ICU 2.0
1.135 + */
1.136 + virtual CharacterIterator* clone(void) const;
1.137 +
1.138 + /**
1.139 + * Sets the iterator to refer to the first code unit in its
1.140 + * iteration range, and returns that code unit.
1.141 + * This can be used to begin an iteration with next().
1.142 + * @return the first code unit in its iteration range.
1.143 + * @stable ICU 2.0
1.144 + */
1.145 + virtual UChar first(void);
1.146 +
1.147 + /**
1.148 + * Sets the iterator to refer to the first code unit in its
1.149 + * iteration range, returns that code unit, and moves the position
1.150 + * to the second code unit. This is an alternative to setToStart()
1.151 + * for forward iteration with nextPostInc().
1.152 + * @return the first code unit in its iteration range
1.153 + * @stable ICU 2.0
1.154 + */
1.155 + virtual UChar firstPostInc(void);
1.156 +
1.157 + /**
1.158 + * Sets the iterator to refer to the first code point in its
1.159 + * iteration range, and returns that code unit,
1.160 + * This can be used to begin an iteration with next32().
1.161 + * Note that an iteration with next32PostInc(), beginning with,
1.162 + * e.g., setToStart() or firstPostInc(), is more efficient.
1.163 + * @return the first code point in its iteration range
1.164 + * @stable ICU 2.0
1.165 + */
1.166 + virtual UChar32 first32(void);
1.167 +
1.168 + /**
1.169 + * Sets the iterator to refer to the first code point in its
1.170 + * iteration range, returns that code point, and moves the position
1.171 + * to the second code point. This is an alternative to setToStart()
1.172 + * for forward iteration with next32PostInc().
1.173 + * @return the first code point in its iteration range.
1.174 + * @stable ICU 2.0
1.175 + */
1.176 + virtual UChar32 first32PostInc(void);
1.177 +
1.178 + /**
1.179 + * Sets the iterator to refer to the last code unit in its
1.180 + * iteration range, and returns that code unit.
1.181 + * This can be used to begin an iteration with previous().
1.182 + * @return the last code unit in its iteration range.
1.183 + * @stable ICU 2.0
1.184 + */
1.185 + virtual UChar last(void);
1.186 +
1.187 + /**
1.188 + * Sets the iterator to refer to the last code point in its
1.189 + * iteration range, and returns that code unit.
1.190 + * This can be used to begin an iteration with previous32().
1.191 + * @return the last code point in its iteration range.
1.192 + * @stable ICU 2.0
1.193 + */
1.194 + virtual UChar32 last32(void);
1.195 +
1.196 + /**
1.197 + * Sets the iterator to refer to the "position"-th code unit
1.198 + * in the text-storage object the iterator refers to, and
1.199 + * returns that code unit.
1.200 + * @param position the position within the text-storage object
1.201 + * @return the code unit
1.202 + * @stable ICU 2.0
1.203 + */
1.204 + virtual UChar setIndex(int32_t position);
1.205 +
1.206 + /**
1.207 + * Sets the iterator to refer to the beginning of the code point
1.208 + * that contains the "position"-th code unit
1.209 + * in the text-storage object the iterator refers to, and
1.210 + * returns that code point.
1.211 + * The current position is adjusted to the beginning of the code point
1.212 + * (its first code unit).
1.213 + * @param position the position within the text-storage object
1.214 + * @return the code unit
1.215 + * @stable ICU 2.0
1.216 + */
1.217 + virtual UChar32 setIndex32(int32_t position);
1.218 +
1.219 + /**
1.220 + * Returns the code unit the iterator currently refers to.
1.221 + * @return the code unit the iterator currently refers to.
1.222 + * @stable ICU 2.0
1.223 + */
1.224 + virtual UChar current(void) const;
1.225 +
1.226 + /**
1.227 + * Returns the code point the iterator currently refers to.
1.228 + * @return the code point the iterator currently refers to.
1.229 + * @stable ICU 2.0
1.230 + */
1.231 + virtual UChar32 current32(void) const;
1.232 +
1.233 + /**
1.234 + * Advances to the next code unit in the iteration range (toward
1.235 + * endIndex()), and returns that code unit. If there are no more
1.236 + * code units to return, returns DONE.
1.237 + * @return the next code unit in the iteration range.
1.238 + * @stable ICU 2.0
1.239 + */
1.240 + virtual UChar next(void);
1.241 +
1.242 + /**
1.243 + * Gets the current code unit for returning and advances to the next code unit
1.244 + * in the iteration range
1.245 + * (toward endIndex()). If there are
1.246 + * no more code units to return, returns DONE.
1.247 + * @return the current code unit.
1.248 + * @stable ICU 2.0
1.249 + */
1.250 + virtual UChar nextPostInc(void);
1.251 +
1.252 + /**
1.253 + * Advances to the next code point in the iteration range (toward
1.254 + * endIndex()), and returns that code point. If there are no more
1.255 + * code points to return, returns DONE.
1.256 + * Note that iteration with "pre-increment" semantics is less
1.257 + * efficient than iteration with "post-increment" semantics
1.258 + * that is provided by next32PostInc().
1.259 + * @return the next code point in the iteration range.
1.260 + * @stable ICU 2.0
1.261 + */
1.262 + virtual UChar32 next32(void);
1.263 +
1.264 + /**
1.265 + * Gets the current code point for returning and advances to the next code point
1.266 + * in the iteration range
1.267 + * (toward endIndex()). If there are
1.268 + * no more code points to return, returns DONE.
1.269 + * @return the current point.
1.270 + * @stable ICU 2.0
1.271 + */
1.272 + virtual UChar32 next32PostInc(void);
1.273 +
1.274 + /**
1.275 + * Returns FALSE if there are no more code units or code points
1.276 + * at or after the current position in the iteration range.
1.277 + * This is used with nextPostInc() or next32PostInc() in forward
1.278 + * iteration.
1.279 + * @return FALSE if there are no more code units or code points
1.280 + * at or after the current position in the iteration range.
1.281 + * @stable ICU 2.0
1.282 + */
1.283 + virtual UBool hasNext();
1.284 +
1.285 + /**
1.286 + * Advances to the previous code unit in the iteration range (toward
1.287 + * startIndex()), and returns that code unit. If there are no more
1.288 + * code units to return, returns DONE.
1.289 + * @return the previous code unit in the iteration range.
1.290 + * @stable ICU 2.0
1.291 + */
1.292 + virtual UChar previous(void);
1.293 +
1.294 + /**
1.295 + * Advances to the previous code point in the iteration range (toward
1.296 + * startIndex()), and returns that code point. If there are no more
1.297 + * code points to return, returns DONE.
1.298 + * @return the previous code point in the iteration range.
1.299 + * @stable ICU 2.0
1.300 + */
1.301 + virtual UChar32 previous32(void);
1.302 +
1.303 + /**
1.304 + * Returns FALSE if there are no more code units or code points
1.305 + * before the current position in the iteration range.
1.306 + * This is used with previous() or previous32() in backward
1.307 + * iteration.
1.308 + * @return FALSE if there are no more code units or code points
1.309 + * before the current position in the iteration range.
1.310 + * @stable ICU 2.0
1.311 + */
1.312 + virtual UBool hasPrevious();
1.313 +
1.314 + /**
1.315 + * Moves the current position relative to the start or end of the
1.316 + * iteration range, or relative to the current position itself.
1.317 + * The movement is expressed in numbers of code units forward
1.318 + * or backward by specifying a positive or negative delta.
1.319 + * @param delta the position relative to origin. A positive delta means forward;
1.320 + * a negative delta means backward.
1.321 + * @param origin Origin enumeration {kStart, kCurrent, kEnd}
1.322 + * @return the new position
1.323 + * @stable ICU 2.0
1.324 + */
1.325 + virtual int32_t move(int32_t delta, EOrigin origin);
1.326 +
1.327 + /**
1.328 + * Moves the current position relative to the start or end of the
1.329 + * iteration range, or relative to the current position itself.
1.330 + * The movement is expressed in numbers of code points forward
1.331 + * or backward by specifying a positive or negative delta.
1.332 + * @param delta the position relative to origin. A positive delta means forward;
1.333 + * a negative delta means backward.
1.334 + * @param origin Origin enumeration {kStart, kCurrent, kEnd}
1.335 + * @return the new position
1.336 + * @stable ICU 2.0
1.337 + */
1.338 + virtual int32_t move32(int32_t delta, EOrigin origin);
1.339 +
1.340 + /**
1.341 + * Sets the iterator to iterate over a new range of text
1.342 + * @stable ICU 2.0
1.343 + */
1.344 + void setText(const UChar* newText, int32_t newTextLength);
1.345 +
1.346 + /**
1.347 + * Copies the UChar array under iteration into the UnicodeString
1.348 + * referred to by "result". Even if this iterator iterates across
1.349 + * only a part of this string, the whole string is copied.
1.350 + * @param result Receives a copy of the text under iteration.
1.351 + * @stable ICU 2.0
1.352 + */
1.353 + virtual void getText(UnicodeString& result);
1.354 +
1.355 + /**
1.356 + * Return a class ID for this class (not really public)
1.357 + * @return a class ID for this class
1.358 + * @stable ICU 2.0
1.359 + */
1.360 + static UClassID U_EXPORT2 getStaticClassID(void);
1.361 +
1.362 + /**
1.363 + * Return a class ID for this object (not really public)
1.364 + * @return a class ID for this object.
1.365 + * @stable ICU 2.0
1.366 + */
1.367 + virtual UClassID getDynamicClassID(void) const;
1.368 +
1.369 +protected:
1.370 + /**
1.371 + * Protected constructor
1.372 + * @stable ICU 2.0
1.373 + */
1.374 + UCharCharacterIterator();
1.375 + /**
1.376 + * Protected member text
1.377 + * @stable ICU 2.0
1.378 + */
1.379 + const UChar* text;
1.380 +
1.381 +};
1.382 +
1.383 +U_NAMESPACE_END
1.384 +#endif
