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