1// © 2016 and later: Unicode, Inc. and others.
2// License & terms of use: http://www.unicode.org/copyright.html
3/*
4 ********************************************************************************
5 * Copyright (C) 1997-2006, International Business Machines
6 * Corporation and others. All Rights Reserved.
7 ********************************************************************************
8 *
9 * File FIELDPOS.H
10 *
11 * Modification History:
12 *
13 * Date Name Description
14 * 02/25/97 aliu Converted from java.
15 * 03/17/97 clhuang Updated per Format implementation.
16 * 07/17/98 stephen Added default/copy ctors, and operators =, ==, !=
17 ********************************************************************************
18 */
19
20// *****************************************************************************
21// This file was generated from the java source file FieldPosition.java
22// *****************************************************************************
23
24#ifndef FIELDPOS_H
25#define FIELDPOS_H
26
27#include "unicode/utypes.h"
28
29#if U_SHOW_CPLUSPLUS_API
30
31/**
32 * \file
33 * \brief C++ API: FieldPosition identifies the fields in a formatted output.
34 */
35
36#if !UCONFIG_NO_FORMATTING
37
38#include "unicode/uobject.h"
39
40U_NAMESPACE_BEGIN
41
42/**
43 * <code>FieldPosition</code> is a simple class used by <code>Format</code>
44 * and its subclasses to identify fields in formatted output. Fields are
45 * identified by constants, whose names typically end with <code>_FIELD</code>,
46 * defined in the various subclasses of <code>Format</code>. See
47 * <code>ERA_FIELD</code> and its friends in <code>DateFormat</code> for
48 * an example.
49 *
50 * <p>
51 * <code>FieldPosition</code> keeps track of the position of the
52 * field within the formatted output with two indices: the index
53 * of the first character of the field and the index of the last
54 * character of the field.
55 *
56 * <p>
57 * One version of the <code>format</code> method in the various
58 * <code>Format</code> classes requires a <code>FieldPosition</code>
59 * object as an argument. You use this <code>format</code> method
60 * to perform partial formatting or to get information about the
61 * formatted output (such as the position of a field).
62 *
63 * The FieldPosition class is not intended for public subclassing.
64 *
65 * <p>
66 * Below is an example of using <code>FieldPosition</code> to aid
67 * alignment of an array of formatted floating-point numbers on
68 * their decimal points:
69 * <pre>
70 * \code
71 * double doubleNum[] = {123456789.0, -12345678.9, 1234567.89, -123456.789,
72 * 12345.6789, -1234.56789, 123.456789, -12.3456789, 1.23456789};
73 * int dNumSize = (int)(sizeof(doubleNum)/sizeof(double));
74 *
75 * UErrorCode status = U_ZERO_ERROR;
76 * DecimalFormat* fmt = (DecimalFormat*) NumberFormat::createInstance(status);
77 * fmt->setDecimalSeparatorAlwaysShown(true);
78 *
79 * const int tempLen = 20;
80 * char temp[tempLen];
81 *
82 * for (int i=0; i<dNumSize; i++) {
83 * FieldPosition pos(NumberFormat::INTEGER_FIELD);
84 * UnicodeString buf;
85 * char fmtText[tempLen];
86 * ToCharString(fmt->format(doubleNum[i], buf, pos), fmtText);
87 * for (int j=0; j<tempLen; j++) temp[j] = ' '; // clear with spaces
88 * temp[__min(tempLen, tempLen-pos.getEndIndex())] = '\0';
89 * cout << temp << fmtText << endl;
90 * }
91 * delete fmt;
92 * \endcode
93 * </pre>
94 * <p>
95 * The code will generate the following output:
96 * <pre>
97 * \code
98 * 123,456,789.000
99 * -12,345,678.900
100 * 1,234,567.880
101 * -123,456.789
102 * 12,345.678
103 * -1,234.567
104 * 123.456
105 * -12.345
106 * 1.234
107 * \endcode
108 * </pre>
109 */
110class U_I18N_API FieldPosition : public UObject {
111public:
112 /**
113 * DONT_CARE may be specified as the field to indicate that the
114 * caller doesn't need to specify a field.
115 * @stable ICU 2.0
116 */
117 enum { DONT_CARE = -1 };
118
119 /**
120 * Creates a FieldPosition object with a non-specified field.
121 * @stable ICU 2.0
122 */
123 FieldPosition()
124 : UObject(), fField(DONT_CARE), fBeginIndex(0), fEndIndex(0) {}
125
126 /**
127 * Creates a FieldPosition object for the given field. Fields are
128 * identified by constants, whose names typically end with _FIELD,
129 * in the various subclasses of Format.
130 *
131 * @see NumberFormat#INTEGER_FIELD
132 * @see NumberFormat#FRACTION_FIELD
133 * @see DateFormat#YEAR_FIELD
134 * @see DateFormat#MONTH_FIELD
135 * @stable ICU 2.0
136 */
137 FieldPosition(int32_t field)
138 : UObject(), fField(field), fBeginIndex(0), fEndIndex(0) {}
139
140 /**
141 * Copy constructor
142 * @param copy the object to be copied from.
143 * @stable ICU 2.0
144 */
145 FieldPosition(const FieldPosition& copy)
146 : UObject(copy), fField(copy.fField), fBeginIndex(copy.fBeginIndex), fEndIndex(copy.fEndIndex) {}
147
148 /**
149 * Destructor
150 * @stable ICU 2.0
151 */
152 virtual ~FieldPosition();
153
154 /**
155 * Assignment operator
156 * @param copy the object to be copied from.
157 * @stable ICU 2.0
158 */
159 FieldPosition& operator=(const FieldPosition& copy);
160
161 /**
162 * Equality operator.
163 * @param that the object to be compared with.
164 * @return TRUE if the two field positions are equal, FALSE otherwise.
165 * @stable ICU 2.0
166 */
167 UBool operator==(const FieldPosition& that) const;
168
169 /**
170 * Equality operator.
171 * @param that the object to be compared with.
172 * @return TRUE if the two field positions are not equal, FALSE otherwise.
173 * @stable ICU 2.0
174 */
175 UBool operator!=(const FieldPosition& that) const;
176
177 /**
178 * Clone this object.
179 * Clones can be used concurrently in multiple threads.
180 * If an error occurs, then NULL is returned.
181 * The caller must delete the clone.
182 *
183 * @return a clone of this object
184 *
185 * @see getDynamicClassID
186 * @stable ICU 2.8
187 */
188 FieldPosition *clone() const;
189
190 /**
191 * Retrieve the field identifier.
192 * @return the field identifier.
193 * @stable ICU 2.0
194 */
195 int32_t getField(void) const { return fField; }
196
197 /**
198 * Retrieve the index of the first character in the requested field.
199 * @return the index of the first character in the requested field.
200 * @stable ICU 2.0
201 */
202 int32_t getBeginIndex(void) const { return fBeginIndex; }
203
204 /**
205 * Retrieve the index of the character following the last character in the
206 * requested field.
207 * @return the index of the character following the last character in the
208 * requested field.
209 * @stable ICU 2.0
210 */
211 int32_t getEndIndex(void) const { return fEndIndex; }
212
213 /**
214 * Set the field.
215 * @param f the new value of the field.
216 * @stable ICU 2.0
217 */
218 void setField(int32_t f) { fField = f; }
219
220 /**
221 * Set the begin index. For use by subclasses of Format.
222 * @param bi the new value of the begin index
223 * @stable ICU 2.0
224 */
225 void setBeginIndex(int32_t bi) { fBeginIndex = bi; }
226
227 /**
228 * Set the end index. For use by subclasses of Format.
229 * @param ei the new value of the end index
230 * @stable ICU 2.0
231 */
232 void setEndIndex(int32_t ei) { fEndIndex = ei; }
233
234 /**
235 * ICU "poor man's RTTI", returns a UClassID for the actual class.
236 *
237 * @stable ICU 2.2
238 */
239 virtual UClassID getDynamicClassID() const;
240
241 /**
242 * ICU "poor man's RTTI", returns a UClassID for this class.
243 *
244 * @stable ICU 2.2
245 */
246 static UClassID U_EXPORT2 getStaticClassID();
247
248private:
249 /**
250 * Input: Desired field to determine start and end offsets for.
251 * The meaning depends on the subclass of Format.
252 */
253 int32_t fField;
254
255 /**
256 * Output: Start offset of field in text.
257 * If the field does not occur in the text, 0 is returned.
258 */
259 int32_t fBeginIndex;
260
261 /**
262 * Output: End offset of field in text.
263 * If the field does not occur in the text, 0 is returned.
264 */
265 int32_t fEndIndex;
266};
267
268inline FieldPosition&
269FieldPosition::operator=(const FieldPosition& copy)
270{
271 fField = copy.fField;
272 fEndIndex = copy.fEndIndex;
273 fBeginIndex = copy.fBeginIndex;
274 return *this;
275}
276
277inline UBool
278FieldPosition::operator==(const FieldPosition& copy) const
279{
280 return (fField == copy.fField &&
281 fEndIndex == copy.fEndIndex &&
282 fBeginIndex == copy.fBeginIndex);
283}
284
285inline UBool
286FieldPosition::operator!=(const FieldPosition& copy) const
287{
288 return !operator==(copy);
289}
290
291U_NAMESPACE_END
292
293#endif /* #if !UCONFIG_NO_FORMATTING */
294
295#endif /* U_SHOW_CPLUSPLUS_API */
296
297#endif // _FIELDPOS
298//eof
299