icuSources/i18n/unicode/fieldpos.h

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