1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/common/unicode/strenum.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,276 @@
1.4 +/*
1.5 +*******************************************************************************
1.6 +*
1.7 +* Copyright (C) 2002-2012, International Business Machines
1.8 +* Corporation and others. All Rights Reserved.
1.9 +*
1.10 +*******************************************************************************
1.11 +*/
1.12 +
1.13 +#ifndef STRENUM_H
1.14 +#define STRENUM_H
1.15 +
1.16 +#include "unicode/uobject.h"
1.17 +#include "unicode/unistr.h"
1.18 +
1.19 +/**
1.20 + * \file
1.21 + * \brief C++ API: String Enumeration
1.22 + */
1.23 +
1.24 +U_NAMESPACE_BEGIN
1.25 +
1.26 +/**
1.27 + * Base class for 'pure' C++ implementations of uenum api. Adds a
1.28 + * method that returns the next UnicodeString since in C++ this can
1.29 + * be a common storage format for strings.
1.30 + *
1.31 + * <p>The model is that the enumeration is over strings maintained by
1.32 + * a 'service.' At any point, the service might change, invalidating
1.33 + * the enumerator (though this is expected to be rare). The iterator
1.34 + * returns an error if this has occurred. Lack of the error is no
1.35 + * guarantee that the service didn't change immediately after the
1.36 + * call, so the returned string still might not be 'valid' on
1.37 + * subsequent use.</p>
1.38 + *
1.39 + * <p>Strings may take the form of const char*, const UChar*, or const
1.40 + * UnicodeString*. The type you get is determine by the variant of
1.41 + * 'next' that you call. In general the StringEnumeration is
1.42 + * optimized for one of these types, but all StringEnumerations can
1.43 + * return all types. Returned strings are each terminated with a NUL.
1.44 + * Depending on the service data, they might also include embedded NUL
1.45 + * characters, so API is provided to optionally return the true
1.46 + * length, counting the embedded NULs but not counting the terminating
1.47 + * NUL.</p>
1.48 + *
1.49 + * <p>The pointers returned by next, unext, and snext become invalid
1.50 + * upon any subsequent call to the enumeration's destructor, next,
1.51 + * unext, snext, or reset.</p>
1.52 + *
1.53 + * ICU 2.8 adds some default implementations and helper functions
1.54 + * for subclasses.
1.55 + *
1.56 + * @stable ICU 2.4
1.57 + */
1.58 +class U_COMMON_API StringEnumeration : public UObject {
1.59 +public:
1.60 + /**
1.61 + * Destructor.
1.62 + * @stable ICU 2.4
1.63 + */
1.64 + virtual ~StringEnumeration();
1.65 +
1.66 + /**
1.67 + * Clone this object, an instance of a subclass of StringEnumeration.
1.68 + * Clones can be used concurrently in multiple threads.
1.69 + * If a subclass does not implement clone(), or if an error occurs,
1.70 + * then NULL is returned.
1.71 + * The clone functions in all subclasses return a base class pointer
1.72 + * because some compilers do not support covariant (same-as-this)
1.73 + * return types; cast to the appropriate subclass if necessary.
1.74 + * The caller must delete the clone.
1.75 + *
1.76 + * @return a clone of this object
1.77 + *
1.78 + * @see getDynamicClassID
1.79 + * @stable ICU 2.8
1.80 + */
1.81 + virtual StringEnumeration *clone() const;
1.82 +
1.83 + /**
1.84 + * <p>Return the number of elements that the iterator traverses. If
1.85 + * the iterator is out of sync with its service, status is set to
1.86 + * U_ENUM_OUT_OF_SYNC_ERROR, and the return value is zero.</p>
1.87 + *
1.88 + * <p>The return value will not change except possibly as a result of
1.89 + * a subsequent call to reset, or if the iterator becomes out of sync.</p>
1.90 + *
1.91 + * <p>This is a convenience function. It can end up being very
1.92 + * expensive as all the items might have to be pre-fetched
1.93 + * (depending on the storage format of the data being
1.94 + * traversed).</p>
1.95 + *
1.96 + * @param status the error code.
1.97 + * @return number of elements in the iterator.
1.98 + *
1.99 + * @stable ICU 2.4 */
1.100 + virtual int32_t count(UErrorCode& status) const = 0;
1.101 +
1.102 + /**
1.103 + * <p>Returns the next element as a NUL-terminated char*. If there
1.104 + * are no more elements, returns NULL. If the resultLength pointer
1.105 + * is not NULL, the length of the string (not counting the
1.106 + * terminating NUL) is returned at that address. If an error
1.107 + * status is returned, the value at resultLength is undefined.</p>
1.108 + *
1.109 + * <p>The returned pointer is owned by this iterator and must not be
1.110 + * deleted by the caller. The pointer is valid until the next call
1.111 + * to next, unext, snext, reset, or the enumerator's destructor.</p>
1.112 + *
1.113 + * <p>If the iterator is out of sync with its service, status is set
1.114 + * to U_ENUM_OUT_OF_SYNC_ERROR and NULL is returned.</p>
1.115 + *
1.116 + * <p>If the native service string is a UChar* string, it is
1.117 + * converted to char* with the invariant converter. If the
1.118 + * conversion fails (because a character cannot be converted) then
1.119 + * status is set to U_INVARIANT_CONVERSION_ERROR and the return
1.120 + * value is undefined (though not NULL).</p>
1.121 + *
1.122 + * Starting with ICU 2.8, the default implementation calls snext()
1.123 + * and handles the conversion.
1.124 + * Either next() or snext() must be implemented differently by a subclass.
1.125 + *
1.126 + * @param status the error code.
1.127 + * @param resultLength a pointer to receive the length, can be NULL.
1.128 + * @return a pointer to the string, or NULL.
1.129 + *
1.130 + * @stable ICU 2.4
1.131 + */
1.132 + virtual const char* next(int32_t *resultLength, UErrorCode& status);
1.133 +
1.134 + /**
1.135 + * <p>Returns the next element as a NUL-terminated UChar*. If there
1.136 + * are no more elements, returns NULL. If the resultLength pointer
1.137 + * is not NULL, the length of the string (not counting the
1.138 + * terminating NUL) is returned at that address. If an error
1.139 + * status is returned, the value at resultLength is undefined.</p>
1.140 + *
1.141 + * <p>The returned pointer is owned by this iterator and must not be
1.142 + * deleted by the caller. The pointer is valid until the next call
1.143 + * to next, unext, snext, reset, or the enumerator's destructor.</p>
1.144 + *
1.145 + * <p>If the iterator is out of sync with its service, status is set
1.146 + * to U_ENUM_OUT_OF_SYNC_ERROR and NULL is returned.</p>
1.147 + *
1.148 + * Starting with ICU 2.8, the default implementation calls snext()
1.149 + * and handles the conversion.
1.150 + *
1.151 + * @param status the error code.
1.152 + * @param resultLength a ponter to receive the length, can be NULL.
1.153 + * @return a pointer to the string, or NULL.
1.154 + *
1.155 + * @stable ICU 2.4
1.156 + */
1.157 + virtual const UChar* unext(int32_t *resultLength, UErrorCode& status);
1.158 +
1.159 + /**
1.160 + * <p>Returns the next element a UnicodeString*. If there are no
1.161 + * more elements, returns NULL.</p>
1.162 + *
1.163 + * <p>The returned pointer is owned by this iterator and must not be
1.164 + * deleted by the caller. The pointer is valid until the next call
1.165 + * to next, unext, snext, reset, or the enumerator's destructor.</p>
1.166 + *
1.167 + * <p>If the iterator is out of sync with its service, status is set
1.168 + * to U_ENUM_OUT_OF_SYNC_ERROR and NULL is returned.</p>
1.169 + *
1.170 + * Starting with ICU 2.8, the default implementation calls next()
1.171 + * and handles the conversion.
1.172 + * Either next() or snext() must be implemented differently by a subclass.
1.173 + *
1.174 + * @param status the error code.
1.175 + * @return a pointer to the string, or NULL.
1.176 + *
1.177 + * @stable ICU 2.4
1.178 + */
1.179 + virtual const UnicodeString* snext(UErrorCode& status);
1.180 +
1.181 + /**
1.182 + * <p>Resets the iterator. This re-establishes sync with the
1.183 + * service and rewinds the iterator to start at the first
1.184 + * element.</p>
1.185 + *
1.186 + * <p>Previous pointers returned by next, unext, or snext become
1.187 + * invalid, and the value returned by count might change.</p>
1.188 + *
1.189 + * @param status the error code.
1.190 + *
1.191 + * @stable ICU 2.4
1.192 + */
1.193 + virtual void reset(UErrorCode& status) = 0;
1.194 +
1.195 + /**
1.196 + * Compares this enumeration to other to check if both are equal
1.197 + *
1.198 + * @param that The other string enumeration to compare this object to
1.199 + * @return TRUE if the enumerations are equal. FALSE if not.
1.200 + * @stable ICU 3.6
1.201 + */
1.202 + virtual UBool operator==(const StringEnumeration& that)const;
1.203 + /**
1.204 + * Compares this enumeration to other to check if both are not equal
1.205 + *
1.206 + * @param that The other string enumeration to compare this object to
1.207 + * @return TRUE if the enumerations are equal. FALSE if not.
1.208 + * @stable ICU 3.6
1.209 + */
1.210 + virtual UBool operator!=(const StringEnumeration& that)const;
1.211 +
1.212 +protected:
1.213 + /**
1.214 + * UnicodeString field for use with default implementations and subclasses.
1.215 + * @stable ICU 2.8
1.216 + */
1.217 + UnicodeString unistr;
1.218 + /**
1.219 + * char * default buffer for use with default implementations and subclasses.
1.220 + * @stable ICU 2.8
1.221 + */
1.222 + char charsBuffer[32];
1.223 + /**
1.224 + * char * buffer for use with default implementations and subclasses.
1.225 + * Allocated in constructor and in ensureCharsCapacity().
1.226 + * @stable ICU 2.8
1.227 + */
1.228 + char *chars;
1.229 + /**
1.230 + * Capacity of chars, for use with default implementations and subclasses.
1.231 + * @stable ICU 2.8
1.232 + */
1.233 + int32_t charsCapacity;
1.234 +
1.235 + /**
1.236 + * Default constructor for use with default implementations and subclasses.
1.237 + * @stable ICU 2.8
1.238 + */
1.239 + StringEnumeration();
1.240 +
1.241 + /**
1.242 + * Ensures that chars is at least as large as the requested capacity.
1.243 + * For use with default implementations and subclasses.
1.244 + *
1.245 + * @param capacity Requested capacity.
1.246 + * @param status ICU in/out error code.
1.247 + * @stable ICU 2.8
1.248 + */
1.249 + void ensureCharsCapacity(int32_t capacity, UErrorCode &status);
1.250 +
1.251 + /**
1.252 + * Converts s to Unicode and sets unistr to the result.
1.253 + * For use with default implementations and subclasses,
1.254 + * especially for implementations of snext() in terms of next().
1.255 + * This is provided with a helper function instead of a default implementation
1.256 + * of snext() to avoid potential infinite loops between next() and snext().
1.257 + *
1.258 + * For example:
1.259 + * \code
1.260 + * const UnicodeString* snext(UErrorCode& status) {
1.261 + * int32_t resultLength=0;
1.262 + * const char *s=next(&resultLength, status);
1.263 + * return setChars(s, resultLength, status);
1.264 + * }
1.265 + * \endcode
1.266 + *
1.267 + * @param s String to be converted to Unicode.
1.268 + * @param length Length of the string.
1.269 + * @param status ICU in/out error code.
1.270 + * @return A pointer to unistr.
1.271 + * @stable ICU 2.8
1.272 + */
1.273 + UnicodeString *setChars(const char *s, int32_t length, UErrorCode &status);
1.274 +};
1.275 +
1.276 +U_NAMESPACE_END
1.277 +
1.278 +/* STRENUM_H */
1.279 +#endif
