src/third_party/icu/source/common/unicode/uenum.h

   1 /*
   2 *******************************************************************************
   3 *
   4 *   Copyright (C) 2002-2013, International Business Machines
   5 *   Corporation and others.  All Rights Reserved.
   6 *
   7 *******************************************************************************
   8 *   file name:  uenum.h
   9 *   encoding:   US-ASCII
  10 *   tab size:   8 (not used)
  11 *   indentation:2
  12 *
  13 *   created on: 2002jul08
  14 *   created by: Vladimir Weinstein
  15 */
  16
  17 #ifndef __UENUM_H
  18 #define __UENUM_H
  19
  20 #include "unicode/utypes.h"
  21 #include "unicode/localpointer.h"
  22
  23 #if U_SHOW_CPLUSPLUS_API
  24 #include "unicode/strenum.h"
  25 #endif
  26
  27 /**
  28  * \file
  29  * \brief C API: String Enumeration
  30  */
  31
  32 /**
  33  * An enumeration object.
  34  * For usage in C programs.
  35  * @stable ICU 2.2
  36  */
  37 struct UEnumeration;
  38 /** structure representing an enumeration object instance @stable ICU 2.2 */
  39 typedef struct UEnumeration UEnumeration;
  40
  41 /**
  42  * Disposes of resources in use by the iterator.  If en is NULL,
  43  * does nothing.  After this call, any char* or UChar* pointer
  44  * returned by uenum_unext() or uenum_next() is invalid.
  45  * @param en UEnumeration structure pointer
  46  * @stable ICU 2.2
  47  */
  48 U_STABLE void U_EXPORT2
  49 uenum_close(UEnumeration* en);
  50
  51 #if U_SHOW_CPLUSPLUS_API
  52
  53 U_NAMESPACE_BEGIN
  54
  55 /**
  56  * \class LocalUEnumerationPointer
  57  * "Smart pointer" class, closes a UEnumeration via uenum_close().
  58  * For most methods see the LocalPointerBase base class.
  59  *
  60  * @see LocalPointerBase
  61  * @see LocalPointer
  62  * @stable ICU 4.4
  63  */
  64 U_DEFINE_LOCAL_OPEN_POINTER(LocalUEnumerationPointer, UEnumeration, uenum_close);
  65
  66 U_NAMESPACE_END
  67
  68 #endif
  69
  70 /**
  71  * Returns the number of elements that the iterator traverses.  If
  72  * the iterator is out-of-sync with its service, status is set to
  73  * U_ENUM_OUT_OF_SYNC_ERROR.
  74  * This is a convenience function. It can end up being very
  75  * expensive as all the items might have to be pre-fetched (depending
  76  * on the type of data being traversed). Use with caution and only
  77  * when necessary.
  78  * @param en UEnumeration structure pointer
  79  * @param status error code, can be U_ENUM_OUT_OF_SYNC_ERROR if the
  80  *               iterator is out of sync.
  81  * @return number of elements in the iterator
  82  * @stable ICU 2.2
  83  */
  84 U_STABLE int32_t U_EXPORT2
  85 uenum_count(UEnumeration* en, UErrorCode* status);
  86
  87 /**
  88  * Returns the next element in the iterator's list.  If there are
  89  * no more elements, returns NULL.  If the iterator is out-of-sync
  90  * with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and
  91  * NULL is returned.  If the native service string is a char* string,
  92  * it is converted to UChar* with the invariant converter.
  93  * The result is terminated by (UChar)0.
  94  * @param en the iterator object
  95  * @param resultLength pointer to receive the length of the result
  96  *                     (not including the terminating \\0).
  97  *                     If the pointer is NULL it is ignored.
  98  * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if
  99  *               the iterator is out of sync with its service.
 100  * @return a pointer to the string.  The string will be
 101  *         zero-terminated.  The return pointer is owned by this iterator
 102  *         and must not be deleted by the caller.  The pointer is valid
 103  *         until the next call to any uenum_... method, including
 104  *         uenum_next() or uenum_unext().  When all strings have been
 105  *         traversed, returns NULL.
 106  * @stable ICU 2.2
 107  */
 108 U_STABLE const UChar* U_EXPORT2
 109 uenum_unext(UEnumeration* en,
 110             int32_t* resultLength,
 111             UErrorCode* status);
 112
 113 /**
 114  * Returns the next element in the iterator's list.  If there are
 115  * no more elements, returns NULL.  If the iterator is out-of-sync
 116  * with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and
 117  * NULL is returned.  If the native service string is a UChar*
 118  * string, it is converted to char* with the invariant converter.
 119  * The result is terminated by (char)0.  If the conversion fails
 120  * (because a character cannot be converted) then status is set to
 121  * U_INVARIANT_CONVERSION_ERROR and the return value is undefined
 122  * (but non-NULL).
 123  * @param en the iterator object
 124  * @param resultLength pointer to receive the length of the result
 125  *                     (not including the terminating \\0).
 126  *                     If the pointer is NULL it is ignored.
 127  * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if
 128  *               the iterator is out of sync with its service.  Set to
 129  *               U_INVARIANT_CONVERSION_ERROR if the underlying native string is
 130  *               UChar* and conversion to char* with the invariant converter
 131  *               fails. This error pertains only to current string, so iteration
 132  *               might be able to continue successfully.
 133  * @return a pointer to the string.  The string will be
 134  *         zero-terminated.  The return pointer is owned by this iterator
 135  *         and must not be deleted by the caller.  The pointer is valid
 136  *         until the next call to any uenum_... method, including
 137  *         uenum_next() or uenum_unext().  When all strings have been
 138  *         traversed, returns NULL.
 139  * @stable ICU 2.2
 140  */
 141 U_STABLE const char* U_EXPORT2
 142 uenum_next(UEnumeration* en,
 143            int32_t* resultLength,
 144            UErrorCode* status);
 145
 146 /**
 147  * Resets the iterator to the current list of service IDs.  This
 148  * re-establishes sync with the service and rewinds the iterator
 149  * to start at the first element.
 150  * @param en the iterator object
 151  * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if
 152  *               the iterator is out of sync with its service.
 153  * @stable ICU 2.2
 154  */
 155 U_STABLE void U_EXPORT2
 156 uenum_reset(UEnumeration* en, UErrorCode* status);
 157
 158 #if U_SHOW_CPLUSPLUS_API
 159
 160 /**
 161  * Given a StringEnumeration, wrap it in a UEnumeration.  The
 162  * StringEnumeration is adopted; after this call, the caller must not
 163  * delete it (regardless of error status).
 164  * @param adopted the C++ StringEnumeration to be wrapped in a UEnumeration.
 165  * @param ec the error code.
 166  * @return a UEnumeration wrapping the adopted StringEnumeration.
 167  * @stable ICU 4.2
 168  */
 169 U_STABLE UEnumeration* U_EXPORT2
 170 uenum_openFromStringEnumeration(icu::StringEnumeration* adopted, UErrorCode* ec);
 171
 172 #endif
 173
 174 /**
 175  * Given an array of const UChar* strings, return a UEnumeration.  String pointers from 0..count-1 must not be null.
 176  * Do not free or modify either the string array or the characters it points to until this object has been destroyed with uenum_close.
 177  * \snippet test/cintltst/uenumtst.c uenum_openUCharStringsEnumeration
 178  * @param strings array of const UChar* strings (each null terminated). All storage is owned by the caller.
 179  * @param count length of the array
 180  * @param ec error code
 181  * @return the new UEnumeration object. Caller is responsible for calling uenum_close to free memory.
 182  * @see uenum_close
 183  * @stable ICU 50
 184  */
 185 U_STABLE UEnumeration* U_EXPORT2
 186 uenum_openUCharStringsEnumeration(const UChar* const strings[], int32_t count,
 187                                  UErrorCode* ec);
 188
 189 /* Note:  next function is not hidden as draft, as it is used internally (it was formerly an internal function). */
 190
 191 /**
 192  * Given an array of const char* strings (invariant chars only), return a UEnumeration.  String pointers from 0..count-1 must not be null.
 193  * Do not free or modify either the string array or the characters it points to until this object has been destroyed with uenum_close.
 194  * \snippet test/cintltst/uenumtst.c uenum_openCharStringsEnumeration
 195  * @param strings array of char* strings (each null terminated).  All storage is owned by the caller.
 196  * @param count length of the array
 197  * @param ec error code
 198  * @return the new UEnumeration object. Caller is responsible for calling uenum_close to free memory
 199  * @see uenum_close
 200  * @stable ICU 50
 201  */
 202 U_STABLE UEnumeration* U_EXPORT2
 203 uenum_openCharStringsEnumeration(const char* const strings[], int32_t count,
 204                                  UErrorCode* ec);
 205
 206 #endif