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