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 306