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 
40 U_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  */
110 class U_I18N_API FieldPosition : public UObject {
111 public:
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      */
FieldPosition()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      */
FieldPosition(int32_t field)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      */
FieldPosition(const FieldPosition & copy)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     bool               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     bool               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      */
getField(void)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      */
getBeginIndex(void)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      */
getEndIndex(void)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      */
setField(int32_t f)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      */
setBeginIndex(int32_t bi)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      */
setEndIndex(int32_t ei)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 override;
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 
248 private:
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 
268 inline FieldPosition&
269 FieldPosition::operator=(const FieldPosition& copy)
270 {
271     fField         = copy.fField;
272     fEndIndex     = copy.fEndIndex;
273     fBeginIndex = copy.fBeginIndex;
274     return *this;
275 }
276 
277 inline bool
278 FieldPosition::operator==(const FieldPosition& copy) const
279 {
280     return (fField == copy.fField &&
281         fEndIndex == copy.fEndIndex &&
282         fBeginIndex == copy.fBeginIndex);
283 }
284 
285 inline bool
286 FieldPosition::operator!=(const FieldPosition& copy) const
287 {
288     return !operator==(copy);
289 }
290 
291 U_NAMESPACE_END
292 
293 #endif /* #if !UCONFIG_NO_FORMATTING */
294 
295 #endif /* U_SHOW_CPLUSPLUS_API */
296 
297 #endif // _FIELDPOS
298 //eof
299