| 1 | /* |
| 2 | ******************************************************************************** |
| 3 | * Copyright (C) 1997-2011, International Business Machines Corporation and others. |
| 4 | * All Rights Reserved. |
| 5 | ******************************************************************************** |
| 6 | * |
| 7 | * File FORMAT.H |
| 8 | * |
| 9 | * Modification History: |
| 10 | * |
| 11 | * Date Name Description |
| 12 | * 02/19/97 aliu Converted from java. |
| 13 | * 03/17/97 clhuang Updated per C++ implementation. |
| 14 | * 03/27/97 helena Updated to pass the simple test after code review. |
| 15 | ******************************************************************************** |
| 16 | */ |
| 17 | // ***************************************************************************** |
| 18 | // This file was generated from the java source file Format.java |
| 19 | // ***************************************************************************** |
| 20 | |
| 21 | #ifndef FORMAT_H |
| 22 | #define FORMAT_H |
| 23 | |
| 24 | |
| 25 | #include "unicode/utypes.h" |
| 26 | |
| 27 | /** |
| 28 | * \file |
| 29 | * \brief C++ API: Base class for all formats. |
| 30 | */ |
| 31 | |
| 32 | #if !UCONFIG_NO_FORMATTING |
| 33 | |
| 34 | #include "unicode/unistr.h" |
| 35 | #include "unicode/fmtable.h" |
| 36 | #include "unicode/fieldpos.h" |
| 37 | #include "unicode/fpositer.h" |
| 38 | #include "unicode/parsepos.h" |
| 39 | #include "unicode/parseerr.h" |
| 40 | #include "unicode/locid.h" |
| 41 | |
| 42 | U_NAMESPACE_BEGIN |
| 43 | |
| 44 | /** |
| 45 | * Base class for all formats. This is an abstract base class which |
| 46 | * specifies the protocol for classes which convert other objects or |
| 47 | * values, such as numeric values and dates, and their string |
| 48 | * representations. In some cases these representations may be |
| 49 | * localized or contain localized characters or strings. For example, |
| 50 | * a numeric formatter such as DecimalFormat may convert a numeric |
| 51 | * value such as 12345 to the string "$12,345". It may also parse |
| 52 | * the string back into a numeric value. A date and time formatter |
| 53 | * like SimpleDateFormat may represent a specific date, encoded |
| 54 | * numerically, as a string such as "Wednesday, February 26, 1997 AD". |
| 55 | * <P> |
| 56 | * Many of the concrete subclasses of Format employ the notion of |
| 57 | * a pattern. A pattern is a string representation of the rules which |
| 58 | * govern the interconversion between values and strings. For example, |
| 59 | * a DecimalFormat object may be associated with the pattern |
| 60 | * "$#,##0.00;($#,##0.00)", which is a common US English format for |
| 61 | * currency values, yielding strings such as "$1,234.45" for 1234.45, |
| 62 | * and "($987.65)" for 987.6543. The specific syntax of a pattern |
| 63 | * is defined by each subclass. |
| 64 | * <P> |
| 65 | * Even though many subclasses use patterns, the notion of a pattern |
| 66 | * is not inherent to Format classes in general, and is not part of |
| 67 | * the explicit base class protocol. |
| 68 | * <P> |
| 69 | * Two complex formatting classes bear mentioning. These are |
| 70 | * MessageFormat and ChoiceFormat. ChoiceFormat is a subclass of |
| 71 | * NumberFormat which allows the user to format different number ranges |
| 72 | * as strings. For instance, 0 may be represented as "no files", 1 as |
| 73 | * "one file", and any number greater than 1 as "many files". |
| 74 | * MessageFormat is a formatter which utilizes other Format objects to |
| 75 | * format a string containing with multiple values. For instance, |
| 76 | * A MessageFormat object might produce the string "There are no files |
| 77 | * on the disk MyDisk on February 27, 1997." given the arguments 0, |
| 78 | * "MyDisk", and the date value of 2/27/97. See the ChoiceFormat |
| 79 | * and MessageFormat headers for further information. |
| 80 | * <P> |
| 81 | * If formatting is unsuccessful, a failing UErrorCode is returned when |
| 82 | * the Format cannot format the type of object, otherwise if there is |
| 83 | * something illformed about the the Unicode replacement character |
| 84 | * 0xFFFD is returned. |
| 85 | * <P> |
| 86 | * If there is no match when parsing, a parse failure UErrorCode is |
| 87 | * retured for methods which take no ParsePosition. For the method |
| 88 | * that takes a ParsePosition, the index parameter is left unchanged. |
| 89 | * <P> |
| 90 | * <em>User subclasses are not supported.</em> While clients may write |
| 91 | * subclasses, such code will not necessarily work and will not be |
| 92 | * guaranteed to work stably from release to release. |
| 93 | */ |
| 94 | class U_I18N_API Format : public UObject { |
| 95 | public: |
| 96 | |
| 97 | /** Destructor |
| 98 | * @stable ICU 2.4 |
| 99 | */ |
| 100 | virtual ~Format(); |
| 101 | |
| 102 | /** |
| 103 | * Return true if the given Format objects are semantically equal. |
| 104 | * Objects of different subclasses are considered unequal. |
| 105 | * @param other the object to be compared with. |
| 106 | * @return Return true if the given Format objects are semantically equal. |
| 107 | * Objects of different subclasses are considered unequal. |
| 108 | * @stable ICU 2.0 |
| 109 | */ |
| 110 | virtual UBool operator==(const Format& other) const = 0; |
| 111 | |
| 112 | /** |
| 113 | * Return true if the given Format objects are not semantically |
| 114 | * equal. |
| 115 | * @param other the object to be compared with. |
| 116 | * @return Return true if the given Format objects are not semantically. |
| 117 | * @stable ICU 2.0 |
| 118 | */ |
| 119 | UBool operator!=(const Format& other) const { return !operator==(other); } |
| 120 | |
| 121 | /** |
| 122 | * Clone this object polymorphically. The caller is responsible |
| 123 | * for deleting the result when done. |
| 124 | * @return A copy of the object |
| 125 | * @stable ICU 2.0 |
| 126 | */ |
| 127 | virtual Format* clone() const = 0; |
| 128 | |
| 129 | /** |
| 130 | * Formats an object to produce a string. |
| 131 | * |
| 132 | * @param obj The object to format. |
| 133 | * @param appendTo Output parameter to receive result. |
| 134 | * Result is appended to existing contents. |
| 135 | * @param status Output parameter filled in with success or failure status. |
| 136 | * @return Reference to 'appendTo' parameter. |
| 137 | * @stable ICU 2.0 |
| 138 | */ |
| 139 | UnicodeString& format(const Formattable& obj, |
| 140 | UnicodeString& appendTo, |
| 141 | UErrorCode& status) const; |
| 142 | |
| 143 | /** |
| 144 | * Format an object to produce a string. This is a pure virtual method which |
| 145 | * subclasses must implement. This method allows polymorphic formatting |
| 146 | * of Formattable objects. If a subclass of Format receives a Formattable |
| 147 | * object type it doesn't handle (e.g., if a numeric Formattable is passed |
| 148 | * to a DateFormat object) then it returns a failing UErrorCode. |
| 149 | * |
| 150 | * @param obj The object to format. |
| 151 | * @param appendTo Output parameter to receive result. |
| 152 | * Result is appended to existing contents. |
| 153 | * @param pos On input: an alignment field, if desired. |
| 154 | * On output: the offsets of the alignment field. |
| 155 | * @param status Output param filled with success/failure status. |
| 156 | * @return Reference to 'appendTo' parameter. |
| 157 | * @stable ICU 2.0 |
| 158 | */ |
| 159 | virtual UnicodeString& format(const Formattable& obj, |
| 160 | UnicodeString& appendTo, |
| 161 | FieldPosition& pos, |
| 162 | UErrorCode& status) const = 0; |
| 163 | /** |
| 164 | * Format an object to produce a string. Subclasses should override this |
| 165 | * method. This method allows polymorphic formatting of Formattable objects. |
| 166 | * If a subclass of Format receives a Formattable object type it doesn't |
| 167 | * handle (e.g., if a numeric Formattable is passed to a DateFormat object) |
| 168 | * then it returns a failing UErrorCode. |
| 169 | * |
| 170 | * @param obj The object to format. |
| 171 | * @param appendTo Output parameter to receive result. |
| 172 | * Result is appended to existing contents. |
| 173 | * @param posIter On return, can be used to iterate over positions |
| 174 | * of fields generated by this format call. |
| 175 | * @param status Output param filled with success/failure status. |
| 176 | * @return Reference to 'appendTo' parameter. |
| 177 | * @stable ICU 4.4 |
| 178 | */ |
| 179 | virtual UnicodeString& format(const Formattable& obj, |
| 180 | UnicodeString& appendTo, |
| 181 | FieldPositionIterator* posIter, |
| 182 | UErrorCode& status) const; |
| 183 | |
| 184 | /** |
| 185 | * Parse a string to produce an object. This is a pure virtual |
| 186 | * method which subclasses must implement. This method allows |
| 187 | * polymorphic parsing of strings into Formattable objects. |
| 188 | * <P> |
| 189 | * Before calling, set parse_pos.index to the offset you want to |
| 190 | * start parsing at in the source. After calling, parse_pos.index |
| 191 | * is the end of the text you parsed. If error occurs, index is |
| 192 | * unchanged. |
| 193 | * <P> |
| 194 | * When parsing, leading whitespace is discarded (with successful |
| 195 | * parse), while trailing whitespace is left as is. |
| 196 | * <P> |
| 197 | * Example: |
| 198 | * <P> |
| 199 | * Parsing "_12_xy" (where _ represents a space) for a number, |
| 200 | * with index == 0 will result in the number 12, with |
| 201 | * parse_pos.index updated to 3 (just before the second space). |
| 202 | * Parsing a second time will result in a failing UErrorCode since |
| 203 | * "xy" is not a number, and leave index at 3. |
| 204 | * <P> |
| 205 | * Subclasses will typically supply specific parse methods that |
| 206 | * return different types of values. Since methods can't overload |
| 207 | * on return types, these will typically be named "parse", while |
| 208 | * this polymorphic method will always be called parseObject. Any |
| 209 | * parse method that does not take a parse_pos should set status |
| 210 | * to an error value when no text in the required format is at the |
| 211 | * start position. |
| 212 | * |
| 213 | * @param source The string to be parsed into an object. |
| 214 | * @param result Formattable to be set to the parse result. |
| 215 | * If parse fails, return contents are undefined. |
| 216 | * @param parse_pos The position to start parsing at. Upon return |
| 217 | * this param is set to the position after the |
| 218 | * last character successfully parsed. If the |
| 219 | * source is not parsed successfully, this param |
| 220 | * will remain unchanged. |
| 221 | * @stable ICU 2.0 |
| 222 | */ |
| 223 | virtual void parseObject(const UnicodeString& source, |
| 224 | Formattable& result, |
| 225 | ParsePosition& parse_pos) const = 0; |
| 226 | |
| 227 | /** |
| 228 | * Parses a string to produce an object. This is a convenience method |
| 229 | * which calls the pure virtual parseObject() method, and returns a |
| 230 | * failure UErrorCode if the ParsePosition indicates failure. |
| 231 | * |
| 232 | * @param source The string to be parsed into an object. |
| 233 | * @param result Formattable to be set to the parse result. |
| 234 | * If parse fails, return contents are undefined. |
| 235 | * @param status Output param to be filled with success/failure |
| 236 | * result code. |
| 237 | * @stable ICU 2.0 |
| 238 | */ |
| 239 | void parseObject(const UnicodeString& source, |
| 240 | Formattable& result, |
| 241 | UErrorCode& status) const; |
| 242 | |
| 243 | /** Get the locale for this format object. You can choose between valid and actual locale. |
| 244 | * @param type type of the locale we're looking for (valid or actual) |
| 245 | * @param status error code for the operation |
| 246 | * @return the locale |
| 247 | * @stable ICU 2.8 |
| 248 | */ |
| 249 | Locale getLocale(ULocDataLocaleType type, UErrorCode& status) const; |
| 250 | |
| 251 | #ifndef U_HIDE_INTERNAL_API |
| 252 | /** Get the locale for this format object. You can choose between valid and actual locale. |
| 253 | * @param type type of the locale we're looking for (valid or actual) |
| 254 | * @param status error code for the operation |
| 255 | * @return the locale |
| 256 | * @internal |
| 257 | */ |
| 258 | const char* getLocaleID(ULocDataLocaleType type, UErrorCode &status) const; |
| 259 | #endif /* U_HIDE_INTERNAL_API */ |
| 260 | |
| 261 | protected: |
| 262 | /** @stable ICU 2.8 */ |
| 263 | void setLocaleIDs(const char* valid, const char* actual); |
| 264 | |
| 265 | protected: |
| 266 | /** |
| 267 | * Default constructor for subclass use only. Does nothing. |
| 268 | * @stable ICU 2.0 |
| 269 | */ |
| 270 | Format(); |
| 271 | |
| 272 | /** |
| 273 | * @stable ICU 2.0 |
| 274 | */ |
| 275 | Format(const Format&); // Does nothing; for subclasses only |
| 276 | |
| 277 | /** |
| 278 | * @stable ICU 2.0 |
| 279 | */ |
| 280 | Format& operator=(const Format&); // Does nothing; for subclasses |
| 281 | |
| 282 | |
| 283 | /** |
| 284 | * Simple function for initializing a UParseError from a UnicodeString. |
| 285 | * |
| 286 | * @param pattern The pattern to copy into the parseError |
| 287 | * @param pos The position in pattern where the error occured |
| 288 | * @param parseError The UParseError object to fill in |
| 289 | * @stable ICU 2.4 |
| 290 | */ |
| 291 | static void syntaxError(const UnicodeString& pattern, |
| 292 | int32_t pos, |
| 293 | UParseError& parseError); |
| 294 | |
| 295 | private: |
| 296 | char actualLocale[ULOC_FULLNAME_CAPACITY]; |
| 297 | char validLocale[ULOC_FULLNAME_CAPACITY]; |
| 298 | }; |
| 299 | |
| 300 | U_NAMESPACE_END |
| 301 | |
| 302 | #endif /* #if !UCONFIG_NO_FORMATTING */ |
| 303 | |
| 304 | #endif // _FORMAT |
| 305 | //eof |