1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/common/unicode/uenum.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,206 @@
1.4 +/*
1.5 +*******************************************************************************
1.6 +*
1.7 +* Copyright (C) 2002-2013, International Business Machines
1.8 +* Corporation and others. All Rights Reserved.
1.9 +*
1.10 +*******************************************************************************
1.11 +* file name: uenum.h
1.12 +* encoding: US-ASCII
1.13 +* tab size: 8 (not used)
1.14 +* indentation:2
1.15 +*
1.16 +* created on: 2002jul08
1.17 +* created by: Vladimir Weinstein
1.18 +*/
1.19 +
1.20 +#ifndef __UENUM_H
1.21 +#define __UENUM_H
1.22 +
1.23 +#include "unicode/utypes.h"
1.24 +#include "unicode/localpointer.h"
1.25 +
1.26 +#if U_SHOW_CPLUSPLUS_API
1.27 +#include "unicode/strenum.h"
1.28 +#endif
1.29 +
1.30 +/**
1.31 + * \file
1.32 + * \brief C API: String Enumeration
1.33 + */
1.34 +
1.35 +/**
1.36 + * An enumeration object.
1.37 + * For usage in C programs.
1.38 + * @stable ICU 2.2
1.39 + */
1.40 +struct UEnumeration;
1.41 +/** structure representing an enumeration object instance @stable ICU 2.2 */
1.42 +typedef struct UEnumeration UEnumeration;
1.43 +
1.44 +/**
1.45 + * Disposes of resources in use by the iterator. If en is NULL,
1.46 + * does nothing. After this call, any char* or UChar* pointer
1.47 + * returned by uenum_unext() or uenum_next() is invalid.
1.48 + * @param en UEnumeration structure pointer
1.49 + * @stable ICU 2.2
1.50 + */
1.51 +U_STABLE void U_EXPORT2
1.52 +uenum_close(UEnumeration* en);
1.53 +
1.54 +#if U_SHOW_CPLUSPLUS_API
1.55 +
1.56 +U_NAMESPACE_BEGIN
1.57 +
1.58 +/**
1.59 + * \class LocalUEnumerationPointer
1.60 + * "Smart pointer" class, closes a UEnumeration via uenum_close().
1.61 + * For most methods see the LocalPointerBase base class.
1.62 + *
1.63 + * @see LocalPointerBase
1.64 + * @see LocalPointer
1.65 + * @stable ICU 4.4
1.66 + */
1.67 +U_DEFINE_LOCAL_OPEN_POINTER(LocalUEnumerationPointer, UEnumeration, uenum_close);
1.68 +
1.69 +U_NAMESPACE_END
1.70 +
1.71 +#endif
1.72 +
1.73 +/**
1.74 + * Returns the number of elements that the iterator traverses. If
1.75 + * the iterator is out-of-sync with its service, status is set to
1.76 + * U_ENUM_OUT_OF_SYNC_ERROR.
1.77 + * This is a convenience function. It can end up being very
1.78 + * expensive as all the items might have to be pre-fetched (depending
1.79 + * on the type of data being traversed). Use with caution and only
1.80 + * when necessary.
1.81 + * @param en UEnumeration structure pointer
1.82 + * @param status error code, can be U_ENUM_OUT_OF_SYNC_ERROR if the
1.83 + * iterator is out of sync.
1.84 + * @return number of elements in the iterator
1.85 + * @stable ICU 2.2
1.86 + */
1.87 +U_STABLE int32_t U_EXPORT2
1.88 +uenum_count(UEnumeration* en, UErrorCode* status);
1.89 +
1.90 +/**
1.91 + * Returns the next element in the iterator's list. If there are
1.92 + * no more elements, returns NULL. If the iterator is out-of-sync
1.93 + * with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and
1.94 + * NULL is returned. If the native service string is a char* string,
1.95 + * it is converted to UChar* with the invariant converter.
1.96 + * The result is terminated by (UChar)0.
1.97 + * @param en the iterator object
1.98 + * @param resultLength pointer to receive the length of the result
1.99 + * (not including the terminating \\0).
1.100 + * If the pointer is NULL it is ignored.
1.101 + * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if
1.102 + * the iterator is out of sync with its service.
1.103 + * @return a pointer to the string. The string will be
1.104 + * zero-terminated. The return pointer is owned by this iterator
1.105 + * and must not be deleted by the caller. The pointer is valid
1.106 + * until the next call to any uenum_... method, including
1.107 + * uenum_next() or uenum_unext(). When all strings have been
1.108 + * traversed, returns NULL.
1.109 + * @stable ICU 2.2
1.110 + */
1.111 +U_STABLE const UChar* U_EXPORT2
1.112 +uenum_unext(UEnumeration* en,
1.113 + int32_t* resultLength,
1.114 + UErrorCode* status);
1.115 +
1.116 +/**
1.117 + * Returns the next element in the iterator's list. If there are
1.118 + * no more elements, returns NULL. If the iterator is out-of-sync
1.119 + * with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and
1.120 + * NULL is returned. If the native service string is a UChar*
1.121 + * string, it is converted to char* with the invariant converter.
1.122 + * The result is terminated by (char)0. If the conversion fails
1.123 + * (because a character cannot be converted) then status is set to
1.124 + * U_INVARIANT_CONVERSION_ERROR and the return value is undefined
1.125 + * (but non-NULL).
1.126 + * @param en the iterator object
1.127 + * @param resultLength pointer to receive the length of the result
1.128 + * (not including the terminating \\0).
1.129 + * If the pointer is NULL it is ignored.
1.130 + * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if
1.131 + * the iterator is out of sync with its service. Set to
1.132 + * U_INVARIANT_CONVERSION_ERROR if the underlying native string is
1.133 + * UChar* and conversion to char* with the invariant converter
1.134 + * fails. This error pertains only to current string, so iteration
1.135 + * might be able to continue successfully.
1.136 + * @return a pointer to the string. The string will be
1.137 + * zero-terminated. The return pointer is owned by this iterator
1.138 + * and must not be deleted by the caller. The pointer is valid
1.139 + * until the next call to any uenum_... method, including
1.140 + * uenum_next() or uenum_unext(). When all strings have been
1.141 + * traversed, returns NULL.
1.142 + * @stable ICU 2.2
1.143 + */
1.144 +U_STABLE const char* U_EXPORT2
1.145 +uenum_next(UEnumeration* en,
1.146 + int32_t* resultLength,
1.147 + UErrorCode* status);
1.148 +
1.149 +/**
1.150 + * Resets the iterator to the current list of service IDs. This
1.151 + * re-establishes sync with the service and rewinds the iterator
1.152 + * to start at the first element.
1.153 + * @param en the iterator object
1.154 + * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if
1.155 + * the iterator is out of sync with its service.
1.156 + * @stable ICU 2.2
1.157 + */
1.158 +U_STABLE void U_EXPORT2
1.159 +uenum_reset(UEnumeration* en, UErrorCode* status);
1.160 +
1.161 +#if U_SHOW_CPLUSPLUS_API
1.162 +
1.163 +/**
1.164 + * Given a StringEnumeration, wrap it in a UEnumeration. The
1.165 + * StringEnumeration is adopted; after this call, the caller must not
1.166 + * delete it (regardless of error status).
1.167 + * @param adopted the C++ StringEnumeration to be wrapped in a UEnumeration.
1.168 + * @param ec the error code.
1.169 + * @return a UEnumeration wrapping the adopted StringEnumeration.
1.170 + * @stable ICU 4.2
1.171 + */
1.172 +U_STABLE UEnumeration* U_EXPORT2
1.173 +uenum_openFromStringEnumeration(icu::StringEnumeration* adopted, UErrorCode* ec);
1.174 +
1.175 +#endif
1.176 +
1.177 +/**
1.178 + * Given an array of const UChar* strings, return a UEnumeration. String pointers from 0..count-1 must not be null.
1.179 + * Do not free or modify either the string array or the characters it points to until this object has been destroyed with uenum_close.
1.180 + * \snippet test/cintltst/uenumtst.c uenum_openUCharStringsEnumeration
1.181 + * @param strings array of const UChar* strings (each null terminated). All storage is owned by the caller.
1.182 + * @param count length of the array
1.183 + * @param ec error code
1.184 + * @return the new UEnumeration object. Caller is responsible for calling uenum_close to free memory.
1.185 + * @see uenum_close
1.186 + * @stable ICU 50
1.187 + */
1.188 +U_STABLE UEnumeration* U_EXPORT2
1.189 +uenum_openUCharStringsEnumeration(const UChar* const strings[], int32_t count,
1.190 + UErrorCode* ec);
1.191 +
1.192 +/* Note: next function is not hidden as draft, as it is used internally (it was formerly an internal function). */
1.193 +
1.194 +/**
1.195 + * Given an array of const char* strings (invariant chars only), return a UEnumeration. String pointers from 0..count-1 must not be null.
1.196 + * Do not free or modify either the string array or the characters it points to until this object has been destroyed with uenum_close.
1.197 + * \snippet test/cintltst/uenumtst.c uenum_openCharStringsEnumeration
1.198 + * @param strings array of char* strings (each null terminated). All storage is owned by the caller.
1.199 + * @param count length of the array
1.200 + * @param ec error code
1.201 + * @return the new UEnumeration object. Caller is responsible for calling uenum_close to free memory
1.202 + * @see uenum_close
1.203 + * @stable ICU 50
1.204 + */
1.205 +U_STABLE UEnumeration* U_EXPORT2
1.206 +uenum_openCharStringsEnumeration(const char* const strings[], int32_t count,
1.207 + UErrorCode* ec);
1.208 +
1.209 +#endif
