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