1 // © 2016 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 /* 4 ***************************************************************************************** 5 * Copyright (C) 2015-2016, International Business Machines 6 * Corporation and others. All Rights Reserved. 7 ***************************************************************************************** 8 */ 9 10 #ifndef UFIELDPOSITER_H 11 #define UFIELDPOSITER_H 12 13 #include "unicode/utypes.h" 14 15 #if !UCONFIG_NO_FORMATTING 16 17 #if U_SHOW_CPLUSPLUS_API 18 #include "unicode/localpointer.h" 19 #endif // U_SHOW_CPLUSPLUS_API 20 21 /** 22 * \file 23 * \brief C API: UFieldPositionIterator for use with format APIs. 24 * 25 * Usage: 26 * ufieldpositer_open creates an empty (unset) UFieldPositionIterator. 27 * This can be passed to format functions such as {@link #udat_formatForFields}, 28 * which will set it to apply to the fields in a particular formatted string. 29 * ufieldpositer_next can then be used to iterate over those fields, 30 * providing for each field its type (using values that are specific to the 31 * particular format type, such as date or number formats), as well as the 32 * start and end positions of the field in the formatted string. 33 * A given UFieldPositionIterator can be re-used for different format calls; 34 * each such call resets it to apply to that format string. 35 * ufieldpositer_close should be called to dispose of the UFieldPositionIterator 36 * when it is no longer needed. 37 * 38 * @see FieldPositionIterator 39 */ 40 41 /** 42 * Opaque UFieldPositionIterator object for use in C. 43 * @stable ICU 55 44 */ 45 struct UFieldPositionIterator; 46 typedef struct UFieldPositionIterator UFieldPositionIterator; /**< C typedef for struct UFieldPositionIterator. @stable ICU 55 */ 47 48 /** 49 * Open a new, unset UFieldPositionIterator object. 50 * @param status 51 * A pointer to a UErrorCode to receive any errors. 52 * @return 53 * A pointer to an empty (unset) UFieldPositionIterator object, 54 * or NULL if an error occurred. 55 * @stable ICU 55 56 */ 57 U_CAPI UFieldPositionIterator* U_EXPORT2 58 ufieldpositer_open(UErrorCode* status); 59 60 /** 61 * Close a UFieldPositionIterator object. Once closed it may no longer be used. 62 * @param fpositer 63 * A pointer to the UFieldPositionIterator object to close. 64 * @stable ICU 55 65 */ 66 U_CAPI void U_EXPORT2 67 ufieldpositer_close(UFieldPositionIterator *fpositer); 68 69 70 #if U_SHOW_CPLUSPLUS_API 71 72 U_NAMESPACE_BEGIN 73 74 /** 75 * \class LocalUFieldPositionIteratorPointer 76 * "Smart pointer" class, closes a UFieldPositionIterator via ufieldpositer_close(). 77 * For most methods see the LocalPointerBase base class. 78 * 79 * @see LocalPointerBase 80 * @see LocalPointer 81 * @stable ICU 55 82 */ 83 U_DEFINE_LOCAL_OPEN_POINTER(LocalUFieldPositionIteratorPointer, UFieldPositionIterator, ufieldpositer_close); 84 85 U_NAMESPACE_END 86 87 #endif 88 89 /** 90 * Get information for the next field in the formatted string to which this 91 * UFieldPositionIterator currently applies, or return a negative value if there 92 * are no more fields. 93 * @param fpositer 94 * A pointer to the UFieldPositionIterator object containing iteration 95 * state for the format fields. 96 * @param beginIndex 97 * A pointer to an int32_t to receive information about the start offset 98 * of the field in the formatted string (undefined if the function 99 * returns a negative value). May be NULL if this information is not needed. 100 * @param endIndex 101 * A pointer to an int32_t to receive information about the end offset 102 * of the field in the formatted string (undefined if the function 103 * returns a negative value). May be NULL if this information is not needed. 104 * @return 105 * The field type (non-negative value), or a negative value if there are 106 * no more fields for which to provide information. If negative, then any 107 * values pointed to by beginIndex and endIndex are undefined. 108 * 109 * The values for field type depend on what type of formatter the 110 * UFieldPositionIterator has been set by; for a date formatter, the 111 * values from the UDateFormatField enum. For more information, see the 112 * descriptions of format functions that take a UFieldPositionIterator* 113 * parameter, such as {@link #udat_formatForFields}. 114 * 115 * @stable ICU 55 116 */ 117 U_CAPI int32_t U_EXPORT2 118 ufieldpositer_next(UFieldPositionIterator *fpositer, 119 int32_t *beginIndex, int32_t *endIndex); 120 121 #endif /* #if !UCONFIG_NO_FORMATTING */ 122 123 #endif 124