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
36U_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 */
106class U_I18N_API FieldPosition : public UObject {
107public:
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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
243private:
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
263inline FieldPosition&
264FieldPosition::operator=(const FieldPosition& copy)
265{
266    fField         = copy.fField;
267    fEndIndex     = copy.fEndIndex;
268    fBeginIndex = copy.fBeginIndex;
269    return *this;
270}
271
272inline UBool
273FieldPosition::operator==(const FieldPosition& copy) const
274{
275    return (fField == copy.fField &&
276        fEndIndex == copy.fEndIndex &&
277        fBeginIndex == copy.fBeginIndex);
278}
279
280inline UBool
281FieldPosition::operator!=(const FieldPosition& copy) const
282{
283    return !operator==(copy);
284}
285
286U_NAMESPACE_END
287
288#endif /* #if !UCONFIG_NO_FORMATTING */
289
290#endif // _FIELDPOS
291//eof
292