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