Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/format.h @ 69:33d812a61356

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