include/unicode/ufieldpositer.h

0001 // © 2016 and later: Unicode, Inc. and others.
0002 // License & terms of use: http://www.unicode.org/copyright.html
0003 /*
0004 *****************************************************************************************
0005 * Copyright (C) 2015-2016, International Business Machines
0006 * Corporation and others. All Rights Reserved.
0007 *****************************************************************************************
0008 */
0009
0010 #ifndef UFIELDPOSITER_H
0011 #define UFIELDPOSITER_H
0012
0013 #include "unicode/utypes.h"
0014
0015 #if !UCONFIG_NO_FORMATTING
0016
0017 #if U_SHOW_CPLUSPLUS_API
0018 #include "unicode/localpointer.h"
0019 #endif   // U_SHOW_CPLUSPLUS_API
0020
0021 /**
0022  * \file
0023  * \brief C API: UFieldPositionIterator for use with format APIs.
0024  *
0025  * Usage:
0026  * ufieldpositer_open creates an empty (unset) UFieldPositionIterator.
0027  * This can be passed to format functions such as {@link #udat_formatForFields},
0028  * which will set it to apply to the fields in a particular formatted string.
0029  * ufieldpositer_next can then be used to iterate over those fields,
0030  * providing for each field its type (using values that are specific to the
0031  * particular format type, such as date or number formats), as well as the
0032  * start and end positions of the field in the formatted string.
0033  * A given UFieldPositionIterator can be re-used for different format calls;
0034  * each such call resets it to apply to that format string.
0035  * ufieldpositer_close should be called to dispose of the UFieldPositionIterator
0036  * when it is no longer needed.
0037  *
0038  * @see FieldPositionIterator
0039  */
0040
0041 /**
0042  * Opaque UFieldPositionIterator object for use in C.
0043  * @stable ICU 55
0044  */
0045 struct UFieldPositionIterator;
0046 typedef struct UFieldPositionIterator UFieldPositionIterator;  /**< C typedef for struct UFieldPositionIterator. @stable ICU 55 */
0047
0048 /**
0049  * Open a new, unset UFieldPositionIterator object.
0050  * @param status
0051  *          A pointer to a UErrorCode to receive any errors.
0052  * @return
0053  *          A pointer to an empty (unset) UFieldPositionIterator object,
0054  *          or NULL if an error occurred.
0055  * @stable ICU 55
0056  */
0057 U_CAPI UFieldPositionIterator* U_EXPORT2
0058 ufieldpositer_open(UErrorCode* status);
0059
0060 /**
0061  * Close a UFieldPositionIterator object. Once closed it may no longer be used.
0062  * @param fpositer
0063  *          A pointer to the UFieldPositionIterator object to close.
0064  * @stable ICU 55
0065  */
0066 U_CAPI void U_EXPORT2
0067 ufieldpositer_close(UFieldPositionIterator *fpositer);
0068
0069
0070 #if U_SHOW_CPLUSPLUS_API
0071
0072 U_NAMESPACE_BEGIN
0073
0074 /**
0075  * \class LocalUFieldPositionIteratorPointer
0076  * "Smart pointer" class, closes a UFieldPositionIterator via ufieldpositer_close().
0077  * For most methods see the LocalPointerBase base class.
0078  *
0079  * @see LocalPointerBase
0080  * @see LocalPointer
0081  * @stable ICU 55
0082  */
0083 U_DEFINE_LOCAL_OPEN_POINTER(LocalUFieldPositionIteratorPointer, UFieldPositionIterator, ufieldpositer_close);
0084
0085 U_NAMESPACE_END
0086
0087 #endif
0088
0089 /**
0090  * Get information for the next field in the formatted string to which this
0091  * UFieldPositionIterator currently applies, or return a negative value if there
0092  * are no more fields.
0093  * @param fpositer
0094  *          A pointer to the UFieldPositionIterator object containing iteration
0095  *          state for the format fields.
0096  * @param beginIndex
0097  *          A pointer to an int32_t to receive information about the start offset
0098  *          of the field in the formatted string (undefined if the function
0099  *          returns a negative value). May be NULL if this information is not needed.
0100  * @param endIndex
0101  *          A pointer to an int32_t to receive information about the end offset
0102  *          of the field in the formatted string (undefined if the function
0103  *          returns a negative value). May be NULL if this information is not needed.
0104  * @return
0105  *          The field type (non-negative value), or a negative value if there are
0106  *          no more fields for which to provide information. If negative, then any
0107  *          values pointed to by beginIndex and endIndex are undefined.
0108  *
0109  *          The values for field type depend on what type of formatter the
0110  *          UFieldPositionIterator has been set by; for a date formatter, the
0111  *          values from the UDateFormatField enum. For more information, see the
0112  *          descriptions of format functions that take a UFieldPositionIterator*
0113  *          parameter, such as {@link #udat_formatForFields}.
0114  *
0115  * @stable ICU 55
0116  */
0117 U_CAPI int32_t U_EXPORT2
0118 ufieldpositer_next(UFieldPositionIterator *fpositer,
0119                    int32_t *beginIndex, int32_t *endIndex);
0120
0121 #endif /* #if !UCONFIG_NO_FORMATTING */
0122
0123 #endif