FieldPosition is a simple class used by Format
michael@0: * and its subclasses to identify fields in formatted output. Fields are
michael@0: * identified by constants, whose names typically end with _FIELD,
michael@0: * defined in the various subclasses of Format. See
michael@0: * ERA_FIELD and its friends in DateFormat for
michael@0: * an example.
michael@0: *
michael@0: *
michael@0: * FieldPosition keeps track of the position of the
michael@0: * field within the formatted output with two indices: the index
michael@0: * of the first character of the field and the index of the last
michael@0: * character of the field.
michael@0: *
michael@0: *
michael@0: * One version of the format method in the various
michael@0: * Format classes requires a FieldPosition
michael@0: * object as an argument. You use this format method
michael@0: * to perform partial formatting or to get information about the
michael@0: * formatted output (such as the position of a field).
michael@0: *
michael@0: * The FieldPosition class is not suitable for subclassing.
michael@0: *
michael@0: *
michael@0: * Below is an example of using FieldPosition to aid
michael@0: * alignment of an array of formatted floating-point numbers on
michael@0: * their decimal points:
michael@0: *
michael@0: * \code
michael@0: * double doubleNum[] = {123456789.0, -12345678.9, 1234567.89, -123456.789,
michael@0: * 12345.6789, -1234.56789, 123.456789, -12.3456789, 1.23456789};
michael@0: * int dNumSize = (int)(sizeof(doubleNum)/sizeof(double));
michael@0: *
michael@0: * UErrorCode status = U_ZERO_ERROR;
michael@0: * DecimalFormat* fmt = (DecimalFormat*) NumberFormat::createInstance(status);
michael@0: * fmt->setDecimalSeparatorAlwaysShown(true);
michael@0: *
michael@0: * const int tempLen = 20;
michael@0: * char temp[tempLen];
michael@0: *
michael@0: * for (int i=0; iformat(doubleNum[i], buf, pos), fmtText);
michael@0: * for (int j=0; j
michael@0: *
michael@0: * The code will generate the following output:
michael@0: *
michael@0: * \code
michael@0: * 123,456,789.000
michael@0: * -12,345,678.900
michael@0: * 1,234,567.880
michael@0: * -123,456.789
michael@0: * 12,345.678
michael@0: * -1,234.567
michael@0: * 123.456
michael@0: * -12.345
michael@0: * 1.234
michael@0: * \endcode
michael@0: *
michael@0: */
michael@0: class U_I18N_API FieldPosition : public UObject {
michael@0: public:
michael@0: /**
michael@0: * DONT_CARE may be specified as the field to indicate that the
michael@0: * caller doesn't need to specify a field. Do not subclass.
michael@0: */
michael@0: enum { DONT_CARE = -1 };
michael@0:
michael@0: /**
michael@0: * Creates a FieldPosition object with a non-specified field.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: FieldPosition()
michael@0: : UObject(), fField(DONT_CARE), fBeginIndex(0), fEndIndex(0) {}
michael@0:
michael@0: /**
michael@0: * Creates a FieldPosition object for the given field. Fields are
michael@0: * identified by constants, whose names typically end with _FIELD,
michael@0: * in the various subclasses of Format.
michael@0: *
michael@0: * @see NumberFormat#INTEGER_FIELD
michael@0: * @see NumberFormat#FRACTION_FIELD
michael@0: * @see DateFormat#YEAR_FIELD
michael@0: * @see DateFormat#MONTH_FIELD
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: FieldPosition(int32_t field)
michael@0: : UObject(), fField(field), fBeginIndex(0), fEndIndex(0) {}
michael@0:
michael@0: /**
michael@0: * Copy constructor
michael@0: * @param copy the object to be copied from.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: FieldPosition(const FieldPosition& copy)
michael@0: : UObject(copy), fField(copy.fField), fBeginIndex(copy.fBeginIndex), fEndIndex(copy.fEndIndex) {}
michael@0:
michael@0: /**
michael@0: * Destructor
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: virtual ~FieldPosition();
michael@0:
michael@0: /**
michael@0: * Assignment operator
michael@0: * @param copy the object to be copied from.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: FieldPosition& operator=(const FieldPosition& copy);
michael@0:
michael@0: /**
michael@0: * Equality operator.
michael@0: * @param that the object to be compared with.
michael@0: * @return TRUE if the two field positions are equal, FALSE otherwise.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: UBool operator==(const FieldPosition& that) const;
michael@0:
michael@0: /**
michael@0: * Equality operator.
michael@0: * @param that the object to be compared with.
michael@0: * @return TRUE if the two field positions are not equal, FALSE otherwise.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: UBool operator!=(const FieldPosition& that) const;
michael@0:
michael@0: /**
michael@0: * Clone this object.
michael@0: * Clones can be used concurrently in multiple threads.
michael@0: * If an error occurs, then NULL is returned.
michael@0: * The caller must delete the clone.
michael@0: *
michael@0: * @return a clone of this object
michael@0: *
michael@0: * @see getDynamicClassID
michael@0: * @stable ICU 2.8
michael@0: */
michael@0: FieldPosition *clone() const;
michael@0:
michael@0: /**
michael@0: * Retrieve the field identifier.
michael@0: * @return the field identifier.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: int32_t getField(void) const { return fField; }
michael@0:
michael@0: /**
michael@0: * Retrieve the index of the first character in the requested field.
michael@0: * @return the index of the first character in the requested field.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: int32_t getBeginIndex(void) const { return fBeginIndex; }
michael@0:
michael@0: /**
michael@0: * Retrieve the index of the character following the last character in the
michael@0: * requested field.
michael@0: * @return the index of the character following the last character in the
michael@0: * requested field.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: int32_t getEndIndex(void) const { return fEndIndex; }
michael@0:
michael@0: /**
michael@0: * Set the field.
michael@0: * @param f the new value of the field.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: void setField(int32_t f) { fField = f; }
michael@0:
michael@0: /**
michael@0: * Set the begin index. For use by subclasses of Format.
michael@0: * @param bi the new value of the begin index
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: void setBeginIndex(int32_t bi) { fBeginIndex = bi; }
michael@0:
michael@0: /**
michael@0: * Set the end index. For use by subclasses of Format.
michael@0: * @param ei the new value of the end index
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: void setEndIndex(int32_t ei) { fEndIndex = ei; }
michael@0:
michael@0: /**
michael@0: * ICU "poor man's RTTI", returns a UClassID for the actual class.
michael@0: *
michael@0: * @stable ICU 2.2
michael@0: */
michael@0: virtual UClassID getDynamicClassID() const;
michael@0:
michael@0: /**
michael@0: * ICU "poor man's RTTI", returns a UClassID for this class.
michael@0: *
michael@0: * @stable ICU 2.2
michael@0: */
michael@0: static UClassID U_EXPORT2 getStaticClassID();
michael@0:
michael@0: private:
michael@0: /**
michael@0: * Input: Desired field to determine start and end offsets for.
michael@0: * The meaning depends on the subclass of Format.
michael@0: */
michael@0: int32_t fField;
michael@0:
michael@0: /**
michael@0: * Output: Start offset of field in text.
michael@0: * If the field does not occur in the text, 0 is returned.
michael@0: */
michael@0: int32_t fBeginIndex;
michael@0:
michael@0: /**
michael@0: * Output: End offset of field in text.
michael@0: * If the field does not occur in the text, 0 is returned.
michael@0: */
michael@0: int32_t fEndIndex;
michael@0: };
michael@0:
michael@0: inline FieldPosition&
michael@0: FieldPosition::operator=(const FieldPosition& copy)
michael@0: {
michael@0: fField = copy.fField;
michael@0: fEndIndex = copy.fEndIndex;
michael@0: fBeginIndex = copy.fBeginIndex;
michael@0: return *this;
michael@0: }
michael@0:
michael@0: inline UBool
michael@0: FieldPosition::operator==(const FieldPosition& copy) const
michael@0: {
michael@0: return (fField == copy.fField &&
michael@0: fEndIndex == copy.fEndIndex &&
michael@0: fBeginIndex == copy.fBeginIndex);
michael@0: }
michael@0:
michael@0: inline UBool
michael@0: FieldPosition::operator!=(const FieldPosition& copy) const
michael@0: {
michael@0: return !operator==(copy);
michael@0: }
michael@0:
michael@0: U_NAMESPACE_END
michael@0:
michael@0: #endif /* #if !UCONFIG_NO_FORMATTING */
michael@0:
michael@0: #endif // _FIELDPOS
michael@0: //eof