icuSources/common/unicode/uenum.h

   1 /*
   2 *******************************************************************************
   3 *
   4 *   Copyright (C) 2002-2005, 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
  22 /**
  23  * \file
  24  * \brief C API: String Enumeration
  25  */
  26
  27 /**
  28  * An enumeration object.
  29  * For usage in C programs.
  30  * @stable ICU 2.2
  31  */
  32 struct UEnumeration;
  33 /** structure representing an enumeration object instance @stable ICU 2.2 */
  34 typedef struct UEnumeration UEnumeration;
  35
  36 /**
  37  * Disposes of resources in use by the iterator.  If en is NULL,
  38  * does nothing.  After this call, any char* or UChar* pointer
  39  * returned by uenum_unext() or uenum_next() is invalid.
  40  * @param en UEnumeration structure pointer
  41  * @stable ICU 2.2
  42  */
  43 U_STABLE void U_EXPORT2
  44 uenum_close(UEnumeration* en);
  45
  46 /**
  47  * Returns the number of elements that the iterator traverses.  If
  48  * the iterator is out-of-sync with its service, status is set to
  49  * U_ENUM_OUT_OF_SYNC_ERROR.
  50  * This is a convenience function. It can end up being very
  51  * expensive as all the items might have to be pre-fetched (depending
  52  * on the type of data being traversed). Use with caution and only
  53  * when necessary.
  54  * @param en UEnumeration structure pointer
  55  * @param status error code, can be U_ENUM_OUT_OF_SYNC_ERROR if the
  56  *               iterator is out of sync.
  57  * @return number of elements in the iterator
  58  * @stable ICU 2.2
  59  */
  60 U_STABLE int32_t U_EXPORT2
  61 uenum_count(UEnumeration* en, UErrorCode* status);
  62
  63 /**
  64  * Returns the next element in the iterator's list.  If there are
  65  * no more elements, returns NULL.  If the iterator is out-of-sync
  66  * with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and
  67  * NULL is returned.  If the native service string is a char* string,
  68  * it is converted to UChar* with the invariant converter.
  69  * The result is terminated by (UChar)0.
  70  * @param en the iterator object
  71  * @param resultLength pointer to receive the length of the result
  72  *                     (not including the terminating \\0).
  73  *                     If the pointer is NULL it is ignored.
  74  * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if
  75  *               the iterator is out of sync with its service.
  76  * @return a pointer to the string.  The string will be
  77  *         zero-terminated.  The return pointer is owned by this iterator
  78  *         and must not be deleted by the caller.  The pointer is valid
  79  *         until the next call to any uenum_... method, including
  80  *         uenum_next() or uenum_unext().  When all strings have been
  81  *         traversed, returns NULL.
  82  * @stable ICU 2.2
  83  */
  84 U_STABLE const UChar* U_EXPORT2
  85 uenum_unext(UEnumeration* en,
  86             int32_t* resultLength,
  87             UErrorCode* status);
  88
  89 /**
  90  * Returns the next element in the iterator's list.  If there are
  91  * no more elements, returns NULL.  If the iterator is out-of-sync
  92  * with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and
  93  * NULL is returned.  If the native service string is a UChar*
  94  * string, it is converted to char* with the invariant converter.
  95  * The result is terminated by (char)0.  If the conversion fails
  96  * (because a character cannot be converted) then status is set to
  97  * U_INVARIANT_CONVERSION_ERROR and the return value is undefined
  98  * (but non-NULL).
  99  * @param en the iterator object
 100  * @param resultLength pointer to receive the length of the result
 101  *                     (not including the terminating \\0).
 102  *                     If the pointer is NULL it is ignored.
 103  * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if
 104  *               the iterator is out of sync with its service.  Set to
 105  *               U_INVARIANT_CONVERSION_ERROR if the underlying native string is
 106  *               UChar* and conversion to char* with the invariant converter
 107  *               fails. This error pertains only to current string, so iteration
 108  *               might be able to continue successfully.
 109  * @return a pointer to the string.  The string will be
 110  *         zero-terminated.  The return pointer is owned by this iterator
 111  *         and must not be deleted by the caller.  The pointer is valid
 112  *         until the next call to any uenum_... method, including
 113  *         uenum_next() or uenum_unext().  When all strings have been
 114  *         traversed, returns NULL.
 115  * @stable ICU 2.2
 116  */
 117 U_STABLE const char* U_EXPORT2
 118 uenum_next(UEnumeration* en,
 119            int32_t* resultLength,
 120            UErrorCode* status);
 121
 122 /**
 123  * Resets the iterator to the current list of service IDs.  This
 124  * re-establishes sync with the service and rewinds the iterator
 125  * to start at the first element.
 126  * @param en the iterator object
 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.
 129  * @stable ICU 2.2
 130  */
 131 U_STABLE void U_EXPORT2
 132 uenum_reset(UEnumeration* en, UErrorCode* status);
 133
 134 #endif