1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/i18n/unicode/format.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,305 @@
1.4 +/*
1.5 +********************************************************************************
1.6 +* Copyright (C) 1997-2011, International Business Machines Corporation and others.
1.7 +* All Rights Reserved.
1.8 +********************************************************************************
1.9 +*
1.10 +* File FORMAT.H
1.11 +*
1.12 +* Modification History:
1.13 +*
1.14 +* Date Name Description
1.15 +* 02/19/97 aliu Converted from java.
1.16 +* 03/17/97 clhuang Updated per C++ implementation.
1.17 +* 03/27/97 helena Updated to pass the simple test after code review.
1.18 +********************************************************************************
1.19 +*/
1.20 +// *****************************************************************************
1.21 +// This file was generated from the java source file Format.java
1.22 +// *****************************************************************************
1.23 +
1.24 +#ifndef FORMAT_H
1.25 +#define FORMAT_H
1.26 +
1.27 +
1.28 +#include "unicode/utypes.h"
1.29 +
1.30 +/**
1.31 + * \file
1.32 + * \brief C++ API: Base class for all formats.
1.33 + */
1.34 +
1.35 +#if !UCONFIG_NO_FORMATTING
1.36 +
1.37 +#include "unicode/unistr.h"
1.38 +#include "unicode/fmtable.h"
1.39 +#include "unicode/fieldpos.h"
1.40 +#include "unicode/fpositer.h"
1.41 +#include "unicode/parsepos.h"
1.42 +#include "unicode/parseerr.h"
1.43 +#include "unicode/locid.h"
1.44 +
1.45 +U_NAMESPACE_BEGIN
1.46 +
1.47 +/**
1.48 + * Base class for all formats. This is an abstract base class which
1.49 + * specifies the protocol for classes which convert other objects or
1.50 + * values, such as numeric values and dates, and their string
1.51 + * representations. In some cases these representations may be
1.52 + * localized or contain localized characters or strings. For example,
1.53 + * a numeric formatter such as DecimalFormat may convert a numeric
1.54 + * value such as 12345 to the string "$12,345". It may also parse
1.55 + * the string back into a numeric value. A date and time formatter
1.56 + * like SimpleDateFormat may represent a specific date, encoded
1.57 + * numerically, as a string such as "Wednesday, February 26, 1997 AD".
1.58 + * <P>
1.59 + * Many of the concrete subclasses of Format employ the notion of
1.60 + * a pattern. A pattern is a string representation of the rules which
1.61 + * govern the interconversion between values and strings. For example,
1.62 + * a DecimalFormat object may be associated with the pattern
1.63 + * "$#,##0.00;($#,##0.00)", which is a common US English format for
1.64 + * currency values, yielding strings such as "$1,234.45" for 1234.45,
1.65 + * and "($987.65)" for 987.6543. The specific syntax of a pattern
1.66 + * is defined by each subclass.
1.67 + * <P>
1.68 + * Even though many subclasses use patterns, the notion of a pattern
1.69 + * is not inherent to Format classes in general, and is not part of
1.70 + * the explicit base class protocol.
1.71 + * <P>
1.72 + * Two complex formatting classes bear mentioning. These are
1.73 + * MessageFormat and ChoiceFormat. ChoiceFormat is a subclass of
1.74 + * NumberFormat which allows the user to format different number ranges
1.75 + * as strings. For instance, 0 may be represented as "no files", 1 as
1.76 + * "one file", and any number greater than 1 as "many files".
1.77 + * MessageFormat is a formatter which utilizes other Format objects to
1.78 + * format a string containing with multiple values. For instance,
1.79 + * A MessageFormat object might produce the string "There are no files
1.80 + * on the disk MyDisk on February 27, 1997." given the arguments 0,
1.81 + * "MyDisk", and the date value of 2/27/97. See the ChoiceFormat
1.82 + * and MessageFormat headers for further information.
1.83 + * <P>
1.84 + * If formatting is unsuccessful, a failing UErrorCode is returned when
1.85 + * the Format cannot format the type of object, otherwise if there is
1.86 + * something illformed about the the Unicode replacement character
1.87 + * 0xFFFD is returned.
1.88 + * <P>
1.89 + * If there is no match when parsing, a parse failure UErrorCode is
1.90 + * retured for methods which take no ParsePosition. For the method
1.91 + * that takes a ParsePosition, the index parameter is left unchanged.
1.92 + * <P>
1.93 + * <em>User subclasses are not supported.</em> While clients may write
1.94 + * subclasses, such code will not necessarily work and will not be
1.95 + * guaranteed to work stably from release to release.
1.96 + */
1.97 +class U_I18N_API Format : public UObject {
1.98 +public:
1.99 +
1.100 + /** Destructor
1.101 + * @stable ICU 2.4
1.102 + */
1.103 + virtual ~Format();
1.104 +
1.105 + /**
1.106 + * Return true if the given Format objects are semantically equal.
1.107 + * Objects of different subclasses are considered unequal.
1.108 + * @param other the object to be compared with.
1.109 + * @return Return true if the given Format objects are semantically equal.
1.110 + * Objects of different subclasses are considered unequal.
1.111 + * @stable ICU 2.0
1.112 + */
1.113 + virtual UBool operator==(const Format& other) const = 0;
1.114 +
1.115 + /**
1.116 + * Return true if the given Format objects are not semantically
1.117 + * equal.
1.118 + * @param other the object to be compared with.
1.119 + * @return Return true if the given Format objects are not semantically.
1.120 + * @stable ICU 2.0
1.121 + */
1.122 + UBool operator!=(const Format& other) const { return !operator==(other); }
1.123 +
1.124 + /**
1.125 + * Clone this object polymorphically. The caller is responsible
1.126 + * for deleting the result when done.
1.127 + * @return A copy of the object
1.128 + * @stable ICU 2.0
1.129 + */
1.130 + virtual Format* clone() const = 0;
1.131 +
1.132 + /**
1.133 + * Formats an object to produce a string.
1.134 + *
1.135 + * @param obj The object to format.
1.136 + * @param appendTo Output parameter to receive result.
1.137 + * Result is appended to existing contents.
1.138 + * @param status Output parameter filled in with success or failure status.
1.139 + * @return Reference to 'appendTo' parameter.
1.140 + * @stable ICU 2.0
1.141 + */
1.142 + UnicodeString& format(const Formattable& obj,
1.143 + UnicodeString& appendTo,
1.144 + UErrorCode& status) const;
1.145 +
1.146 + /**
1.147 + * Format an object to produce a string. This is a pure virtual method which
1.148 + * subclasses must implement. This method allows polymorphic formatting
1.149 + * of Formattable objects. If a subclass of Format receives a Formattable
1.150 + * object type it doesn't handle (e.g., if a numeric Formattable is passed
1.151 + * to a DateFormat object) then it returns a failing UErrorCode.
1.152 + *
1.153 + * @param obj The object to format.
1.154 + * @param appendTo Output parameter to receive result.
1.155 + * Result is appended to existing contents.
1.156 + * @param pos On input: an alignment field, if desired.
1.157 + * On output: the offsets of the alignment field.
1.158 + * @param status Output param filled with success/failure status.
1.159 + * @return Reference to 'appendTo' parameter.
1.160 + * @stable ICU 2.0
1.161 + */
1.162 + virtual UnicodeString& format(const Formattable& obj,
1.163 + UnicodeString& appendTo,
1.164 + FieldPosition& pos,
1.165 + UErrorCode& status) const = 0;
1.166 + /**
1.167 + * Format an object to produce a string. Subclasses should override this
1.168 + * method. This method allows polymorphic formatting of Formattable objects.
1.169 + * If a subclass of Format receives a Formattable object type it doesn't
1.170 + * handle (e.g., if a numeric Formattable is passed to a DateFormat object)
1.171 + * then it returns a failing UErrorCode.
1.172 + *
1.173 + * @param obj The object to format.
1.174 + * @param appendTo Output parameter to receive result.
1.175 + * Result is appended to existing contents.
1.176 + * @param posIter On return, can be used to iterate over positions
1.177 + * of fields generated by this format call.
1.178 + * @param status Output param filled with success/failure status.
1.179 + * @return Reference to 'appendTo' parameter.
1.180 + * @stable ICU 4.4
1.181 + */
1.182 + virtual UnicodeString& format(const Formattable& obj,
1.183 + UnicodeString& appendTo,
1.184 + FieldPositionIterator* posIter,
1.185 + UErrorCode& status) const;
1.186 +
1.187 + /**
1.188 + * Parse a string to produce an object. This is a pure virtual
1.189 + * method which subclasses must implement. This method allows
1.190 + * polymorphic parsing of strings into Formattable objects.
1.191 + * <P>
1.192 + * Before calling, set parse_pos.index to the offset you want to
1.193 + * start parsing at in the source. After calling, parse_pos.index
1.194 + * is the end of the text you parsed. If error occurs, index is
1.195 + * unchanged.
1.196 + * <P>
1.197 + * When parsing, leading whitespace is discarded (with successful
1.198 + * parse), while trailing whitespace is left as is.
1.199 + * <P>
1.200 + * Example:
1.201 + * <P>
1.202 + * Parsing "_12_xy" (where _ represents a space) for a number,
1.203 + * with index == 0 will result in the number 12, with
1.204 + * parse_pos.index updated to 3 (just before the second space).
1.205 + * Parsing a second time will result in a failing UErrorCode since
1.206 + * "xy" is not a number, and leave index at 3.
1.207 + * <P>
1.208 + * Subclasses will typically supply specific parse methods that
1.209 + * return different types of values. Since methods can't overload
1.210 + * on return types, these will typically be named "parse", while
1.211 + * this polymorphic method will always be called parseObject. Any
1.212 + * parse method that does not take a parse_pos should set status
1.213 + * to an error value when no text in the required format is at the
1.214 + * start position.
1.215 + *
1.216 + * @param source The string to be parsed into an object.
1.217 + * @param result Formattable to be set to the parse result.
1.218 + * If parse fails, return contents are undefined.
1.219 + * @param parse_pos The position to start parsing at. Upon return
1.220 + * this param is set to the position after the
1.221 + * last character successfully parsed. If the
1.222 + * source is not parsed successfully, this param
1.223 + * will remain unchanged.
1.224 + * @stable ICU 2.0
1.225 + */
1.226 + virtual void parseObject(const UnicodeString& source,
1.227 + Formattable& result,
1.228 + ParsePosition& parse_pos) const = 0;
1.229 +
1.230 + /**
1.231 + * Parses a string to produce an object. This is a convenience method
1.232 + * which calls the pure virtual parseObject() method, and returns a
1.233 + * failure UErrorCode if the ParsePosition indicates failure.
1.234 + *
1.235 + * @param source The string to be parsed into an object.
1.236 + * @param result Formattable to be set to the parse result.
1.237 + * If parse fails, return contents are undefined.
1.238 + * @param status Output param to be filled with success/failure
1.239 + * result code.
1.240 + * @stable ICU 2.0
1.241 + */
1.242 + void parseObject(const UnicodeString& source,
1.243 + Formattable& result,
1.244 + UErrorCode& status) const;
1.245 +
1.246 + /** Get the locale for this format object. You can choose between valid and actual locale.
1.247 + * @param type type of the locale we're looking for (valid or actual)
1.248 + * @param status error code for the operation
1.249 + * @return the locale
1.250 + * @stable ICU 2.8
1.251 + */
1.252 + Locale getLocale(ULocDataLocaleType type, UErrorCode& status) const;
1.253 +
1.254 +#ifndef U_HIDE_INTERNAL_API
1.255 + /** Get the locale for this format object. You can choose between valid and actual locale.
1.256 + * @param type type of the locale we're looking for (valid or actual)
1.257 + * @param status error code for the operation
1.258 + * @return the locale
1.259 + * @internal
1.260 + */
1.261 + const char* getLocaleID(ULocDataLocaleType type, UErrorCode &status) const;
1.262 +#endif /* U_HIDE_INTERNAL_API */
1.263 +
1.264 + protected:
1.265 + /** @stable ICU 2.8 */
1.266 + void setLocaleIDs(const char* valid, const char* actual);
1.267 +
1.268 +protected:
1.269 + /**
1.270 + * Default constructor for subclass use only. Does nothing.
1.271 + * @stable ICU 2.0
1.272 + */
1.273 + Format();
1.274 +
1.275 + /**
1.276 + * @stable ICU 2.0
1.277 + */
1.278 + Format(const Format&); // Does nothing; for subclasses only
1.279 +
1.280 + /**
1.281 + * @stable ICU 2.0
1.282 + */
1.283 + Format& operator=(const Format&); // Does nothing; for subclasses
1.284 +
1.285 +
1.286 + /**
1.287 + * Simple function for initializing a UParseError from a UnicodeString.
1.288 + *
1.289 + * @param pattern The pattern to copy into the parseError
1.290 + * @param pos The position in pattern where the error occured
1.291 + * @param parseError The UParseError object to fill in
1.292 + * @stable ICU 2.4
1.293 + */
1.294 + static void syntaxError(const UnicodeString& pattern,
1.295 + int32_t pos,
1.296 + UParseError& parseError);
1.297 +
1.298 + private:
1.299 + char actualLocale[ULOC_FULLNAME_CAPACITY];
1.300 + char validLocale[ULOC_FULLNAME_CAPACITY];
1.301 +};
1.302 +
1.303 +U_NAMESPACE_END
1.304 +
1.305 +#endif /* #if !UCONFIG_NO_FORMATTING */
1.306 +
1.307 +#endif // _FORMAT
1.308 +//eof
