207 lines
7.8 KiB
C
207 lines
7.8 KiB
C
/*
|
|
*******************************************************************************
|
|
*
|
|
* Copyright (C) 2002-2013, 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"
|
|
#include "unicode/localpointer.h"
|
|
|
|
#if U_SHOW_CPLUSPLUS_API
|
|
#include "unicode/strenum.h"
|
|
#endif
|
|
|
|
/**
|
|
* \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
|
|
|
|
/**
|
|
* 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
|
|
|
|
/**
|
|
* 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
|