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