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