OLD | NEW |
(Empty) | |
| 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 fo
r 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_clos
e(). |
| 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, UFieldPositionIt
erator, 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 offse
t |
| 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 ne
eded. |
| 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 ne
eded. |
| 101 * @return |
| 102 * The field type (non-negative value), or a negative value if there ar
e |
| 103 * no more fields for which to provide information. If negative, then a
ny |
| 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 |
OLD | NEW |