source/i18n/unicode/fieldpos.h

   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      */
 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
 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