[apple/icu.git] / icuSources / i18n / unicode / fieldpos.h

// © 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
/*
 ********************************************************************************
 *   Copyright (C) 1997-2006, International Business Machines
 *   Corporation and others.  All Rights Reserved.
 ********************************************************************************
 *
 * File FIELDPOS.H
 *
 * Modification History:
 *
 *   Date        Name        Description
 *   02/25/97    aliu        Converted from java.
 *   03/17/97    clhuang     Updated per Format implementation.
 *    07/17/98    stephen        Added default/copy ctors, and operators =, ==, !=
 ********************************************************************************
 */

// *****************************************************************************
// This file was generated from the java source file FieldPosition.java
// *****************************************************************************
 
#ifndef FIELDPOS_H
#define FIELDPOS_H

#include "unicode/utypes.h"

/**
 * \file 
 * \brief C++ API: FieldPosition identifies the fields in a formatted output.
 */

#if !UCONFIG_NO_FORMATTING

#include "unicode/uobject.h"

#if U_SHOW_CPLUSPLUS_API
U_NAMESPACE_BEGIN

/**
 * <code>FieldPosition</code> is a simple class used by <code>Format</code>
 * and its subclasses to identify fields in formatted output. Fields are
 * identified by constants, whose names typically end with <code>_FIELD</code>,
 * defined in the various subclasses of <code>Format</code>. See
 * <code>ERA_FIELD</code> and its friends in <code>DateFormat</code> for
 * an example.
 *
 * <p>
 * <code>FieldPosition</code> keeps track of the position of the
 * field within the formatted output with two indices: the index
 * of the first character of the field and the index of the last
 * character of the field.
 *
 * <p>
 * One version of the <code>format</code> method in the various
 * <code>Format</code> classes requires a <code>FieldPosition</code>
 * object as an argument. You use this <code>format</code> method
 * to perform partial formatting or to get information about the
 * formatted output (such as the position of a field).
 *
 * The FieldPosition class is not intended for public subclassing.
 *
 * <p>
 * Below is an example of using <code>FieldPosition</code> to aid
 * alignment of an array of formatted floating-point numbers on
 * their decimal points:
 * <pre>
 * \code
 *       double doubleNum[] = {123456789.0, -12345678.9, 1234567.89, -123456.789,
 *                  12345.6789, -1234.56789, 123.456789, -12.3456789, 1.23456789};
 *       int dNumSize = (int)(sizeof(doubleNum)/sizeof(double));
 *       
 *       UErrorCode status = U_ZERO_ERROR;
 *       DecimalFormat* fmt = (DecimalFormat*) NumberFormat::createInstance(status);
 *       fmt->setDecimalSeparatorAlwaysShown(true);
 *       
 *       const int tempLen = 20;
 *       char temp[tempLen];
 *       
 *       for (int i=0; i<dNumSize; i++) {
 *           FieldPosition pos(NumberFormat::INTEGER_FIELD);
 *           UnicodeString buf;
 *           char fmtText[tempLen];
 *           ToCharString(fmt->format(doubleNum[i], buf, pos), fmtText);
 *           for (int j=0; j<tempLen; j++) temp[j] = ' '; // clear with spaces
 *           temp[__min(tempLen, tempLen-pos.getEndIndex())] = '\0';
 *           cout << temp << fmtText   << endl;
 *       }
 *       delete fmt;
 * \endcode
 * </pre>
 * <p>
 * The code will generate the following output:
 * <pre>
 * \code
 *           123,456,789.000
 *           -12,345,678.900
 *             1,234,567.880
 *              -123,456.789
 *                12,345.678
 *                -1,234.567
 *                   123.456
 *                   -12.345
 *                     1.234
 *  \endcode
 * </pre>
 */
class U_I18N_API FieldPosition : public UObject {
public:
    /**
     * DONT_CARE may be specified as the field to indicate that the
     * caller doesn't need to specify a field.
     * @stable ICU 2.0
     */
    enum { DONT_CARE = -1 };

    /**
     * Creates a FieldPosition object with a non-specified field.
     * @stable ICU 2.0
     */
    FieldPosition() 
        : UObject(), fField(DONT_CARE), fBeginIndex(0), fEndIndex(0) {}

    /**
     * Creates a FieldPosition object for the given field.  Fields are
     * identified by constants, whose names typically end with _FIELD,
     * in the various subclasses of Format.
     *
     * @see NumberFormat#INTEGER_FIELD
     * @see NumberFormat#FRACTION_FIELD
     * @see DateFormat#YEAR_FIELD
     * @see DateFormat#MONTH_FIELD
     * @stable ICU 2.0
     */
    FieldPosition(int32_t field) 
        : UObject(), fField(field), fBeginIndex(0), fEndIndex(0) {}

    /**
     * Copy constructor
     * @param copy the object to be copied from.
     * @stable ICU 2.0
     */
    FieldPosition(const FieldPosition& copy) 
        : UObject(copy), fField(copy.fField), fBeginIndex(copy.fBeginIndex), fEndIndex(copy.fEndIndex) {}

    /**
     * Destructor
     * @stable ICU 2.0
     */
    virtual ~FieldPosition();

    /**
     * Assignment operator
     * @param copy the object to be copied from.
     * @stable ICU 2.0
     */
    FieldPosition&      operator=(const FieldPosition& copy);

    /** 
     * Equality operator.
     * @param that    the object to be compared with.
     * @return        TRUE if the two field positions are equal, FALSE otherwise.
     * @stable ICU 2.0
     */
    UBool              operator==(const FieldPosition& that) const;

    /** 
     * Equality operator.
     * @param that    the object to be compared with.
     * @return        TRUE if the two field positions are not equal, FALSE otherwise.
     * @stable ICU 2.0
     */
    UBool              operator!=(const FieldPosition& that) const;

    /**
     * Clone this object.
     * Clones can be used concurrently in multiple threads.
     * If an error occurs, then NULL is returned.
     * The caller must delete the clone.
     *
     * @return a clone of this object
     *
     * @see getDynamicClassID
     * @stable ICU 2.8
     */
    FieldPosition *clone() const;

    /**
     * Retrieve the field identifier.
     * @return    the field identifier.
     * @stable ICU 2.0
     */
    int32_t getField(void) const { return fField; }

    /**
     * Retrieve the index of the first character in the requested field.
     * @return    the index of the first character in the requested field.
     * @stable ICU 2.0
     */
    int32_t getBeginIndex(void) const { return fBeginIndex; }

    /**
     * Retrieve the index of the character following the last character in the
     * requested field.
     * @return    the index of the character following the last character in the
     *            requested field.
     * @stable ICU 2.0
     */
    int32_t getEndIndex(void) const { return fEndIndex; }
 
    /**
     * Set the field.
     * @param f    the new value of the field.
     * @stable ICU 2.0
     */
    void setField(int32_t f) { fField = f; }

    /**
     * Set the begin index.  For use by subclasses of Format.
     * @param bi    the new value of the begin index
     * @stable ICU 2.0
     */
    void setBeginIndex(int32_t bi) { fBeginIndex = bi; }

    /**
     * Set the end index.  For use by subclasses of Format.
     * @param ei    the new value of the end index
     * @stable ICU 2.0
     */
    void setEndIndex(int32_t ei) { fEndIndex = ei; }
    
    /**
     * ICU "poor man's RTTI", returns a UClassID for the actual class.
     *
     * @stable ICU 2.2
     */
    virtual UClassID getDynamicClassID() const;

    /**
     * ICU "poor man's RTTI", returns a UClassID for this class.
     *
     * @stable ICU 2.2
     */
    static UClassID U_EXPORT2 getStaticClassID();

private:
    /**
     * Input: Desired field to determine start and end offsets for.
     * The meaning depends on the subclass of Format.
     */
    int32_t fField;

    /**
     * Output: Start offset of field in text.
     * If the field does not occur in the text, 0 is returned.
     */
    int32_t fBeginIndex;

    /**
     * Output: End offset of field in text.
     * If the field does not occur in the text, 0 is returned.
     */
    int32_t fEndIndex;
};

inline FieldPosition&
FieldPosition::operator=(const FieldPosition& copy)
{
    fField         = copy.fField;
    fEndIndex     = copy.fEndIndex;
    fBeginIndex = copy.fBeginIndex;
    return *this;
}

inline UBool
FieldPosition::operator==(const FieldPosition& copy) const
{
    return (fField == copy.fField &&
        fEndIndex == copy.fEndIndex &&
        fBeginIndex == copy.fBeginIndex);
}

inline UBool
FieldPosition::operator!=(const FieldPosition& copy) const
{
    return !operator==(copy);
}

U_NAMESPACE_END
#endif // U_SHOW_CPLUSPLUS_API

#endif /* #if !UCONFIG_NO_FORMATTING */

#endif // _FIELDPOS
//eof
Commit	Line	Data
f3c0d7a5 A	1	// © 2016 and later: Unicode, Inc. and others.
f3c0d7a5 A	2	// License & terms of use: http://www.unicode.org/copyright.html
b75a7d8f	3	/*
374ca955	4	********************************************************************************
46f4442e	5	* Copyright (C) 1997-2006, International Business Machines
374ca955 A	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
b75a7d8f A	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
73c04bcf A	29	/**
	30	* \file
	31	* \brief C++ API: FieldPosition identifies the fields in a formatted output.
	32	*/
	33
b75a7d8f A	34	#if !UCONFIG_NO_FORMATTING
	35
	36	#include "unicode/uobject.h"
	37
f3c0d7a5	38	#if U_SHOW_CPLUSPLUS_API
b75a7d8f A	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	*
f3c0d7a5	62	* The FieldPosition class is not intended for public subclassing.
374ca955	63	*
b75a7d8f A	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>
374ca955	108	*/
b75a7d8f A	109	class U_I18N_API FieldPosition : public UObject {
	110	public:
	111	/**
	112	* DONT_CARE may be specified as the field to indicate that the
f3c0d7a5 A	113	* caller doesn't need to specify a field.
f3c0d7a5 A	114	* @stable ICU 2.0
b75a7d8f A	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	*/
374ca955	151	virtual ~FieldPosition();
b75a7d8f A	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
374ca955 A	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
73c04bcf	185	* @stable ICU 2.8
374ca955 A	186	*/
	187	FieldPosition *clone() const;
	188
b75a7d8f A	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	*
374ca955	236	* @stable ICU 2.2
b75a7d8f	237	*/
374ca955	238	virtual UClassID getDynamicClassID() const;
b75a7d8f A	239
	240	/**
	241	* ICU "poor man's RTTI", returns a UClassID for this class.
	242	*
374ca955	243	* @stable ICU 2.2
b75a7d8f	244	*/
374ca955	245	static UClassID U_EXPORT2 getStaticClassID();
b75a7d8f A	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;
b75a7d8f A	265	};
b75a7d8f A	266
b75a7d8f A	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	{
46f4442e A	279	return (fField == copy.fField &&
	280	fEndIndex == copy.fEndIndex &&
	281	fBeginIndex == copy.fBeginIndex);
b75a7d8f A	282	}
	283
	284	inline UBool
	285	FieldPosition::operator!=(const FieldPosition& copy) const
	286	{
	287	return !operator==(copy);
	288	}
	289
	290	U_NAMESPACE_END
f3c0d7a5	291	#endif // U_SHOW_CPLUSPLUS_API
b75a7d8f A	292
	293	#endif /* #if !UCONFIG_NO_FORMATTING */
	294
	295	#endif // _FIELDPOS
	296	//eof