[apple/javascriptcore.git] / icu / unicode / uenum.h

/*
*******************************************************************************
*
*   Copyright (C) 2002-2004, International Business Machines
*   Corporation and others.  All Rights Reserved.
*
*******************************************************************************
*   file name:  uenum.h
*   encoding:   US-ASCII
*   tab size:   8 (not used)
*   indentation:2
*
*   created on: 2002jul08
*   created by: Vladimir Weinstein
*/

#ifndef __UENUM_H
#define __UENUM_H

#include "unicode/utypes.h"

/**
 * 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);

/**
 * 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);

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