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