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