REGRESSION(Variation Fonts): Specifying Skia by PostScript name does not yield the...
[WebKit-https.git] / Source / WTF / icu / unicode / ufieldpositer.h
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