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 */
42struct UFieldPositionIterator;
43typedef 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 */
54U_DRAFT UFieldPositionIterator* U_EXPORT2
55ufieldpositer_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 */
63U_DRAFT void U_EXPORT2
64ufieldpositer_close(UFieldPositionIterator *fpositer);
65
66
67#if U_SHOW_CPLUSPLUS_API
68
69U_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 */
80U_DEFINE_LOCAL_OPEN_POINTER(LocalUFieldPositionIteratorPointer, UFieldPositionIterator, ufieldpositer_close);
81
82U_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 */
114U_DRAFT int32_t U_EXPORT2
115ufieldpositer_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
122