jpayne@69: // © 2016 and later: Unicode, Inc. and others.
jpayne@69: // License & terms of use: http://www.unicode.org/copyright.html
jpayne@69: /*
jpayne@69: *****************************************************************************************
jpayne@69: * Copyright (C) 2015-2016, International Business Machines
jpayne@69: * Corporation and others. All Rights Reserved.
jpayne@69: *****************************************************************************************
jpayne@69: */
jpayne@69: 
jpayne@69: #ifndef UFIELDPOSITER_H
jpayne@69: #define UFIELDPOSITER_H
jpayne@69: 
jpayne@69: #include "unicode/utypes.h"
jpayne@69: 
jpayne@69: #if !UCONFIG_NO_FORMATTING
jpayne@69: 
jpayne@69: #include "unicode/localpointer.h"
jpayne@69: 
jpayne@69: /**
jpayne@69:  * \file
jpayne@69:  * \brief C API: UFieldPositionIterator for use with format APIs.
jpayne@69:  *
jpayne@69:  * Usage:
jpayne@69:  * ufieldpositer_open creates an empty (unset) UFieldPositionIterator.
jpayne@69:  * This can be passed to format functions such as {@link #udat_formatForFields},
jpayne@69:  * which will set it to apply to the fields in a particular formatted string.
jpayne@69:  * ufieldpositer_next can then be used to iterate over those fields,
jpayne@69:  * providing for each field its type (using values that are specific to the
jpayne@69:  * particular format type, such as date or number formats), as well as the
jpayne@69:  * start and end positions of the field in the formatted string.
jpayne@69:  * A given UFieldPositionIterator can be re-used for different format calls;
jpayne@69:  * each such call resets it to apply to that format string.
jpayne@69:  * ufieldpositer_close should be called to dispose of the UFieldPositionIterator
jpayne@69:  * when it is no longer needed.
jpayne@69:  *
jpayne@69:  * @see FieldPositionIterator
jpayne@69:  */
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Opaque UFieldPositionIterator object for use in C.
jpayne@69:  * @stable ICU 55
jpayne@69:  */
jpayne@69: struct UFieldPositionIterator;
jpayne@69: typedef struct UFieldPositionIterator UFieldPositionIterator;  /**< C typedef for struct UFieldPositionIterator. @stable ICU 55 */
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Open a new, unset UFieldPositionIterator object.
jpayne@69:  * @param status
jpayne@69:  *          A pointer to a UErrorCode to receive any errors.
jpayne@69:  * @return
jpayne@69:  *          A pointer to an empty (unset) UFieldPositionIterator object,
jpayne@69:  *          or NULL if an error occurred.
jpayne@69:  * @stable ICU 55
jpayne@69:  */
jpayne@69: U_STABLE UFieldPositionIterator* U_EXPORT2
jpayne@69: ufieldpositer_open(UErrorCode* status);
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Close a UFieldPositionIterator object. Once closed it may no longer be used.
jpayne@69:  * @param fpositer
jpayne@69:  *          A pointer to the UFieldPositionIterator object to close.
jpayne@69:  * @stable ICU 55
jpayne@69:  */
jpayne@69: U_STABLE void U_EXPORT2
jpayne@69: ufieldpositer_close(UFieldPositionIterator *fpositer);
jpayne@69: 
jpayne@69: 
jpayne@69: #if U_SHOW_CPLUSPLUS_API
jpayne@69: 
jpayne@69: U_NAMESPACE_BEGIN
jpayne@69: 
jpayne@69: /**
jpayne@69:  * \class LocalUFieldPositionIteratorPointer
jpayne@69:  * "Smart pointer" class, closes a UFieldPositionIterator via ufieldpositer_close().
jpayne@69:  * For most methods see the LocalPointerBase base class.
jpayne@69:  *
jpayne@69:  * @see LocalPointerBase
jpayne@69:  * @see LocalPointer
jpayne@69:  * @stable ICU 55
jpayne@69:  */
jpayne@69: U_DEFINE_LOCAL_OPEN_POINTER(LocalUFieldPositionIteratorPointer, UFieldPositionIterator, ufieldpositer_close);
jpayne@69: 
jpayne@69: U_NAMESPACE_END
jpayne@69: 
jpayne@69: #endif
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Get information for the next field in the formatted string to which this
jpayne@69:  * UFieldPositionIterator currently applies, or return a negative value if there
jpayne@69:  * are no more fields.
jpayne@69:  * @param fpositer
jpayne@69:  *          A pointer to the UFieldPositionIterator object containing iteration
jpayne@69:  *          state for the format fields.
jpayne@69:  * @param beginIndex
jpayne@69:  *          A pointer to an int32_t to receive information about the start offset
jpayne@69:  *          of the field in the formatted string (undefined if the function
jpayne@69:  *          returns a negative value). May be NULL if this information is not needed.
jpayne@69:  * @param endIndex
jpayne@69:  *          A pointer to an int32_t to receive information about the end offset
jpayne@69:  *          of the field in the formatted string (undefined if the function
jpayne@69:  *          returns a negative value). May be NULL if this information is not needed.
jpayne@69:  * @return
jpayne@69:  *          The field type (non-negative value), or a negative value if there are
jpayne@69:  *          no more fields for which to provide information. If negative, then any
jpayne@69:  *          values pointed to by beginIndex and endIndex are undefined.
jpayne@69:  *
jpayne@69:  *          The values for field type depend on what type of formatter the
jpayne@69:  *          UFieldPositionIterator has been set by; for a date formatter, the
jpayne@69:  *          values from the UDateFormatField enum. For more information, see the
jpayne@69:  *          descriptions of format functions that take a UFieldPositionIterator*
jpayne@69:  *          parameter, such as {@link #udat_formatForFields}.
jpayne@69:  *
jpayne@69:  * @stable ICU 55
jpayne@69:  */
jpayne@69: U_STABLE int32_t U_EXPORT2
jpayne@69: ufieldpositer_next(UFieldPositionIterator *fpositer,
jpayne@69:                    int32_t *beginIndex, int32_t *endIndex);
jpayne@69: 
jpayne@69: #endif /* #if !UCONFIG_NO_FORMATTING */
jpayne@69: 
jpayne@69: #endif