icuSources/common/unicode/uenum.h

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