[apple/icu.git] / icuSources / common / unicode / uenum.h

// © 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
/*
*******************************************************************************
*
*   Copyright (C) 2002-2013, International Business Machines
*   Corporation and others.  All Rights Reserved.
*
*******************************************************************************
*   file name:  uenum.h
*   encoding:   UTF-8
*   tab size:   8 (not used)
*   indentation:2
*
*   created on: 2002jul08
*   created by: Vladimir Weinstein
*/

#ifndef __UENUM_H
#define __UENUM_H

#include "unicode/utypes.h"
#include "unicode/localpointer.h"

#if U_SHOW_CPLUSPLUS_API
U_NAMESPACE_BEGIN
class StringEnumeration;
U_NAMESPACE_END
#endif // U_SHOW_CPLUSPLUS_API

/**
 * \file
 * \brief C API: String Enumeration 
 */
 
/**
 * An enumeration object.
 * For usage in C programs.
 * @stable ICU 2.2
 */
struct UEnumeration;
/** structure representing an enumeration object instance @stable ICU 2.2 */
typedef struct UEnumeration UEnumeration;

/**
 * Disposes of resources in use by the iterator.  If en is NULL,
 * does nothing.  After this call, any char* or UChar* pointer
 * returned by uenum_unext() or uenum_next() is invalid.
 * @param en UEnumeration structure pointer
 * @stable ICU 2.2
 */
U_STABLE void U_EXPORT2
uenum_close(UEnumeration* en);

#if U_SHOW_CPLUSPLUS_API

U_NAMESPACE_BEGIN

/**
 * \class LocalUEnumerationPointer
 * "Smart pointer" class, closes a UEnumeration via uenum_close().
 * For most methods see the LocalPointerBase base class.
 *
 * @see LocalPointerBase
 * @see LocalPointer
 * @stable ICU 4.4
 */
U_DEFINE_LOCAL_OPEN_POINTER(LocalUEnumerationPointer, UEnumeration, uenum_close);

U_NAMESPACE_END

#endif // U_SHOW_CPLUSPLUS_API

/**
 * Returns the number of elements that the iterator traverses.  If
 * the iterator is out-of-sync with its service, status is set to
 * U_ENUM_OUT_OF_SYNC_ERROR.
 * This is a convenience function. It can end up being very
 * expensive as all the items might have to be pre-fetched (depending
 * on the type of data being traversed). Use with caution and only 
 * when necessary.
 * @param en UEnumeration structure pointer
 * @param status error code, can be U_ENUM_OUT_OF_SYNC_ERROR if the
 *               iterator is out of sync.
 * @return number of elements in the iterator
 * @stable ICU 2.2
 */
U_STABLE int32_t U_EXPORT2
uenum_count(UEnumeration* en, UErrorCode* status);

/**
 * Returns the next element in the iterator's list.  If there are
 * no more elements, returns NULL.  If the iterator is out-of-sync
 * with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and
 * NULL is returned.  If the native service string is a char* string,
 * it is converted to UChar* with the invariant converter.
 * The result is terminated by (UChar)0.
 * @param en the iterator object
 * @param resultLength pointer to receive the length of the result
 *                     (not including the terminating \\0).
 *                     If the pointer is NULL it is ignored.
 * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if
 *               the iterator is out of sync with its service.
 * @return a pointer to the string.  The string will be
 *         zero-terminated.  The return pointer is owned by this iterator
 *         and must not be deleted by the caller.  The pointer is valid
 *         until the next call to any uenum_... method, including
 *         uenum_next() or uenum_unext().  When all strings have been
 *         traversed, returns NULL.
 * @stable ICU 2.2
 */
U_STABLE const UChar* U_EXPORT2
uenum_unext(UEnumeration* en,
            int32_t* resultLength,
            UErrorCode* status);

/**
 * Returns the next element in the iterator's list.  If there are
 * no more elements, returns NULL.  If the iterator is out-of-sync
 * with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and
 * NULL is returned.  If the native service string is a UChar*
 * string, it is converted to char* with the invariant converter.
 * The result is terminated by (char)0.  If the conversion fails
 * (because a character cannot be converted) then status is set to
 * U_INVARIANT_CONVERSION_ERROR and the return value is undefined
 * (but non-NULL).
 * @param en the iterator object
 * @param resultLength pointer to receive the length of the result
 *                     (not including the terminating \\0).
 *                     If the pointer is NULL it is ignored.
 * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if
 *               the iterator is out of sync with its service.  Set to
 *               U_INVARIANT_CONVERSION_ERROR if the underlying native string is
 *               UChar* and conversion to char* with the invariant converter
 *               fails. This error pertains only to current string, so iteration
 *               might be able to continue successfully.
 * @return a pointer to the string.  The string will be
 *         zero-terminated.  The return pointer is owned by this iterator
 *         and must not be deleted by the caller.  The pointer is valid
 *         until the next call to any uenum_... method, including
 *         uenum_next() or uenum_unext().  When all strings have been
 *         traversed, returns NULL.
 * @stable ICU 2.2
 */
U_STABLE const char* U_EXPORT2
uenum_next(UEnumeration* en,
           int32_t* resultLength,
           UErrorCode* status);

/**
 * Resets the iterator to the current list of service IDs.  This
 * re-establishes sync with the service and rewinds the iterator
 * to start at the first element.
 * @param en the iterator object
 * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if
 *               the iterator is out of sync with its service.  
 * @stable ICU 2.2
 */
U_STABLE void U_EXPORT2
uenum_reset(UEnumeration* en, UErrorCode* status);

#if U_SHOW_CPLUSPLUS_API

/**
 * Given a StringEnumeration, wrap it in a UEnumeration.  The
 * StringEnumeration is adopted; after this call, the caller must not
 * delete it (regardless of error status).
 * @param adopted the C++ StringEnumeration to be wrapped in a UEnumeration.
 * @param ec the error code.
 * @return a UEnumeration wrapping the adopted StringEnumeration.
 * @stable ICU 4.2
 */
U_STABLE UEnumeration* U_EXPORT2
uenum_openFromStringEnumeration(icu::StringEnumeration* adopted, UErrorCode* ec);

#endif // U_SHOW_CPLUSPLUS_API

/**
 * Given an array of const UChar* strings, return a UEnumeration.  String pointers from 0..count-1 must not be null.
 * Do not free or modify either the string array or the characters it points to until this object has been destroyed with uenum_close.
 * \snippet test/cintltst/uenumtst.c uenum_openUCharStringsEnumeration
 * @param strings array of const UChar* strings (each null terminated). All storage is owned by the caller.
 * @param count length of the array
 * @param ec error code
 * @return the new UEnumeration object. Caller is responsible for calling uenum_close to free memory.
 * @see uenum_close
 * @stable ICU 50
 */
U_STABLE UEnumeration* U_EXPORT2
uenum_openUCharStringsEnumeration(const UChar* const strings[], int32_t count,
                                 UErrorCode* ec);

/* Note:  next function is not hidden as draft, as it is used internally (it was formerly an internal function). */

/**
 * Given an array of const char* strings (invariant chars only), return a UEnumeration.  String pointers from 0..count-1 must not be null.
 * Do not free or modify either the string array or the characters it points to until this object has been destroyed with uenum_close.
 * \snippet test/cintltst/uenumtst.c uenum_openCharStringsEnumeration
 * @param strings array of char* strings (each null terminated).  All storage is owned by the caller.
 * @param count length of the array
 * @param ec error code
 * @return the new UEnumeration object. Caller is responsible for calling uenum_close to free memory
 * @see uenum_close
 * @stable ICU 50
 */
U_STABLE UEnumeration* U_EXPORT2
uenum_openCharStringsEnumeration(const char* const strings[], int32_t count,
                                 UErrorCode* ec);

#endif
Commit	Line	Data
f3c0d7a5 A	1	// © 2016 and later: Unicode, Inc. and others.
f3c0d7a5 A	2	// License & terms of use: http://www.unicode.org/copyright.html
b75a7d8f A	3	/*
	4	*******************************************************************************
	5	*
57a6839d	6	* Copyright (C) 2002-2013, International Business Machines
b75a7d8f A	7	* Corporation and others. All Rights Reserved.
	8	*
	9	*******************************************************************************
	10	* file name: uenum.h
f3c0d7a5	11	* encoding: UTF-8
b75a7d8f A	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"
729e4ab9 A	23	#include "unicode/localpointer.h"
	24
	25	#if U_SHOW_CPLUSPLUS_API
f3c0d7a5 A	26	U_NAMESPACE_BEGIN
	27	class StringEnumeration;
	28	U_NAMESPACE_END
	29	#endif // U_SHOW_CPLUSPLUS_API
b75a7d8f	30
73c04bcf A	31	/**
	32	* \file
	33	* \brief C API: String Enumeration
	34	*/
	35
b75a7d8f A	36	/**
	37	* An enumeration object.
	38	* For usage in C programs.
374ca955	39	* @stable ICU 2.2
b75a7d8f A	40	*/
b75a7d8f A	41	struct UEnumeration;
374ca955	42	/** structure representing an enumeration object instance @stable ICU 2.2 */
b75a7d8f A	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
374ca955	50	* @stable ICU 2.2
b75a7d8f	51	*/
374ca955	52	U_STABLE void U_EXPORT2
b75a7d8f A	53	uenum_close(UEnumeration* en);
b75a7d8f A	54
729e4ab9 A	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
f3c0d7a5	72	#endif // U_SHOW_CPLUSPLUS_API
729e4ab9	73
b75a7d8f A	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
374ca955	86	* @stable ICU 2.2
b75a7d8f	87	*/
374ca955	88	U_STABLE int32_t U_EXPORT2
b75a7d8f A	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
374ca955	100	* (not including the terminating \\0).
b75a7d8f A	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.
374ca955	110	* @stable ICU 2.2
b75a7d8f	111	*/
374ca955	112	U_STABLE const UChar* U_EXPORT2
b75a7d8f A	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
374ca955	129	* (not including the terminating \\0).
b75a7d8f A	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.
374ca955	143	* @stable ICU 2.2
b75a7d8f	144	*/
374ca955	145	U_STABLE const char* U_EXPORT2
b75a7d8f A	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.
374ca955	157	* @stable ICU 2.2
b75a7d8f	158	*/
374ca955	159	U_STABLE void U_EXPORT2
b75a7d8f A	160	uenum_reset(UEnumeration* en, UErrorCode* status);
b75a7d8f A	161
729e4ab9 A	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.
4388f060	171	* @stable ICU 4.2
729e4ab9	172	*/
51004dcb	173	U_STABLE UEnumeration* U_EXPORT2
4388f060	174	uenum_openFromStringEnumeration(icu::StringEnumeration* adopted, UErrorCode* ec);
729e4ab9	175
f3c0d7a5	176	#endif // U_SHOW_CPLUSPLUS_API
729e4ab9	177
51004dcb A	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
57a6839d	187	* @stable ICU 50
51004dcb	188	*/
57a6839d	189	U_STABLE UEnumeration* U_EXPORT2
51004dcb A	190	uenum_openUCharStringsEnumeration(const UChar* const strings[], int32_t count,
51004dcb A	191	UErrorCode* ec);
51004dcb A	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
57a6839d	204	* @stable ICU 50
51004dcb	205	*/
57a6839d	206	U_STABLE UEnumeration* U_EXPORT2
51004dcb A	207	uenum_openCharStringsEnumeration(const char* const strings[], int32_t count,
	208	UErrorCode* ec);
	209
b75a7d8f	210	#endif