icuSources/i18n/unicode/fieldpos.h

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