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

source code of include/unicode/ufieldpositer.h