1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/i18n/unicode/dtptngen.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,498 @@
1.4 +/*
1.5 +*******************************************************************************
1.6 +* Copyright (C) 2007-2013, International Business Machines Corporation and
1.7 +* others. All Rights Reserved.
1.8 +*******************************************************************************
1.9 +*
1.10 +* File DTPTNGEN.H
1.11 +*
1.12 +*******************************************************************************
1.13 +*/
1.14 +
1.15 +#ifndef __DTPTNGEN_H__
1.16 +#define __DTPTNGEN_H__
1.17 +
1.18 +#include "unicode/datefmt.h"
1.19 +#include "unicode/locid.h"
1.20 +#include "unicode/udat.h"
1.21 +#include "unicode/udatpg.h"
1.22 +
1.23 +U_NAMESPACE_BEGIN
1.24 +
1.25 +/**
1.26 + * \file
1.27 + * \brief C++ API: Date/Time Pattern Generator
1.28 + */
1.29 +
1.30 +
1.31 +class Hashtable;
1.32 +class FormatParser;
1.33 +class DateTimeMatcher;
1.34 +class DistanceInfo;
1.35 +class PatternMap;
1.36 +class PtnSkeleton;
1.37 +
1.38 +/**
1.39 + * This class provides flexible generation of date format patterns, like "yy-MM-dd".
1.40 + * The user can build up the generator by adding successive patterns. Once that
1.41 + * is done, a query can be made using a "skeleton", which is a pattern which just
1.42 + * includes the desired fields and lengths. The generator will return the "best fit"
1.43 + * pattern corresponding to that skeleton.
1.44 + * <p>The main method people will use is getBestPattern(String skeleton),
1.45 + * since normally this class is pre-built with data from a particular locale.
1.46 + * However, generators can be built directly from other data as well.
1.47 + * <p><i>Issue: may be useful to also have a function that returns the list of
1.48 + * fields in a pattern, in order, since we have that internally.
1.49 + * That would be useful for getting the UI order of field elements.</i>
1.50 + * @stable ICU 3.8
1.51 +**/
1.52 +class U_I18N_API DateTimePatternGenerator : public UObject {
1.53 +public:
1.54 + /**
1.55 + * Construct a flexible generator according to default locale.
1.56 + * @param status Output param set to success/failure code on exit,
1.57 + * which must not indicate a failure before the function call.
1.58 + * @stable ICU 3.8
1.59 + */
1.60 + static DateTimePatternGenerator* U_EXPORT2 createInstance(UErrorCode& status);
1.61 +
1.62 + /**
1.63 + * Construct a flexible generator according to data for a given locale.
1.64 + * @param uLocale
1.65 + * @param status Output param set to success/failure code on exit,
1.66 + * which must not indicate a failure before the function call.
1.67 + * @stable ICU 3.8
1.68 + */
1.69 + static DateTimePatternGenerator* U_EXPORT2 createInstance(const Locale& uLocale, UErrorCode& status);
1.70 +
1.71 + /**
1.72 + * Create an empty generator, to be constructed with addPattern(...) etc.
1.73 + * @param status Output param set to success/failure code on exit,
1.74 + * which must not indicate a failure before the function call.
1.75 + * @stable ICU 3.8
1.76 + */
1.77 + static DateTimePatternGenerator* U_EXPORT2 createEmptyInstance(UErrorCode& status);
1.78 +
1.79 + /**
1.80 + * Destructor.
1.81 + * @stable ICU 3.8
1.82 + */
1.83 + virtual ~DateTimePatternGenerator();
1.84 +
1.85 + /**
1.86 + * Clone DateTimePatternGenerator object. Clients are responsible for
1.87 + * deleting the DateTimePatternGenerator object cloned.
1.88 + * @stable ICU 3.8
1.89 + */
1.90 + DateTimePatternGenerator* clone() const;
1.91 +
1.92 + /**
1.93 + * Return true if another object is semantically equal to this one.
1.94 + *
1.95 + * @param other the DateTimePatternGenerator object to be compared with.
1.96 + * @return true if other is semantically equal to this.
1.97 + * @stable ICU 3.8
1.98 + */
1.99 + UBool operator==(const DateTimePatternGenerator& other) const;
1.100 +
1.101 + /**
1.102 + * Return true if another object is semantically unequal to this one.
1.103 + *
1.104 + * @param other the DateTimePatternGenerator object to be compared with.
1.105 + * @return true if other is semantically unequal to this.
1.106 + * @stable ICU 3.8
1.107 + */
1.108 + UBool operator!=(const DateTimePatternGenerator& other) const;
1.109 +
1.110 + /**
1.111 + * Utility to return a unique skeleton from a given pattern. For example,
1.112 + * both "MMM-dd" and "dd/MMM" produce the skeleton "MMMdd".
1.113 + *
1.114 + * @param pattern Input pattern, such as "dd/MMM"
1.115 + * @param status Output param set to success/failure code on exit,
1.116 + * which must not indicate a failure before the function call.
1.117 + * @return skeleton such as "MMMdd"
1.118 + * @stable ICU 3.8
1.119 + */
1.120 + UnicodeString getSkeleton(const UnicodeString& pattern, UErrorCode& status);
1.121 +
1.122 + /**
1.123 + * Utility to return a unique base skeleton from a given pattern. This is
1.124 + * the same as the skeleton, except that differences in length are minimized
1.125 + * so as to only preserve the difference between string and numeric form. So
1.126 + * for example, both "MMM-dd" and "d/MMM" produce the skeleton "MMMd"
1.127 + * (notice the single d).
1.128 + *
1.129 + * @param pattern Input pattern, such as "dd/MMM"
1.130 + * @param status Output param set to success/failure code on exit,
1.131 + * which must not indicate a failure before the function call.
1.132 + * @return base skeleton, such as "Md"
1.133 + * @stable ICU 3.8
1.134 + */
1.135 + UnicodeString getBaseSkeleton(const UnicodeString& pattern, UErrorCode& status);
1.136 +
1.137 + /**
1.138 + * Adds a pattern to the generator. If the pattern has the same skeleton as
1.139 + * an existing pattern, and the override parameter is set, then the previous
1.140 + * value is overriden. Otherwise, the previous value is retained. In either
1.141 + * case, the conflicting status is set and previous vale is stored in
1.142 + * conflicting pattern.
1.143 + * <p>
1.144 + * Note that single-field patterns (like "MMM") are automatically added, and
1.145 + * don't need to be added explicitly!
1.146 + *
1.147 + * @param pattern Input pattern, such as "dd/MMM"
1.148 + * @param override When existing values are to be overridden use true,
1.149 + * otherwise use false.
1.150 + * @param conflictingPattern Previous pattern with the same skeleton.
1.151 + * @param status Output param set to success/failure code on exit,
1.152 + * which must not indicate a failure before the function call.
1.153 + * @return conflicting status. The value could be UDATPG_NO_CONFLICT,
1.154 + * UDATPG_BASE_CONFLICT or UDATPG_CONFLICT.
1.155 + * @stable ICU 3.8
1.156 + * <p>
1.157 + * <h4>Sample code</h4>
1.158 + * \snippet samples/dtptngsample/dtptngsample.cpp getBestPatternExample1
1.159 + * \snippet samples/dtptngsample/dtptngsample.cpp addPatternExample
1.160 + * <p>
1.161 + */
1.162 + UDateTimePatternConflict addPattern(const UnicodeString& pattern,
1.163 + UBool override,
1.164 + UnicodeString& conflictingPattern,
1.165 + UErrorCode& status);
1.166 +
1.167 + /**
1.168 + * An AppendItem format is a pattern used to append a field if there is no
1.169 + * good match. For example, suppose that the input skeleton is "GyyyyMMMd",
1.170 + * and there is no matching pattern internally, but there is a pattern
1.171 + * matching "yyyyMMMd", say "d-MM-yyyy". Then that pattern is used, plus the
1.172 + * G. The way these two are conjoined is by using the AppendItemFormat for G
1.173 + * (era). So if that value is, say "{0}, {1}" then the final resulting
1.174 + * pattern is "d-MM-yyyy, G".
1.175 + * <p>
1.176 + * There are actually three available variables: {0} is the pattern so far,
1.177 + * {1} is the element we are adding, and {2} is the name of the element.
1.178 + * <p>
1.179 + * This reflects the way that the CLDR data is organized.
1.180 + *
1.181 + * @param field such as UDATPG_ERA_FIELD.
1.182 + * @param value pattern, such as "{0}, {1}"
1.183 + * @stable ICU 3.8
1.184 + */
1.185 + void setAppendItemFormat(UDateTimePatternField field, const UnicodeString& value);
1.186 +
1.187 + /**
1.188 + * Getter corresponding to setAppendItemFormat. Values below 0 or at or
1.189 + * above UDATPG_FIELD_COUNT are illegal arguments.
1.190 + *
1.191 + * @param field such as UDATPG_ERA_FIELD.
1.192 + * @return append pattern for field
1.193 + * @stable ICU 3.8
1.194 + */
1.195 + const UnicodeString& getAppendItemFormat(UDateTimePatternField field) const;
1.196 +
1.197 + /**
1.198 + * Sets the names of field, eg "era" in English for ERA. These are only
1.199 + * used if the corresponding AppendItemFormat is used, and if it contains a
1.200 + * {2} variable.
1.201 + * <p>
1.202 + * This reflects the way that the CLDR data is organized.
1.203 + *
1.204 + * @param field such as UDATPG_ERA_FIELD.
1.205 + * @param value name of the field
1.206 + * @stable ICU 3.8
1.207 + */
1.208 + void setAppendItemName(UDateTimePatternField field, const UnicodeString& value);
1.209 +
1.210 + /**
1.211 + * Getter corresponding to setAppendItemNames. Values below 0 or at or above
1.212 + * UDATPG_FIELD_COUNT are illegal arguments.
1.213 + *
1.214 + * @param field such as UDATPG_ERA_FIELD.
1.215 + * @return name for field
1.216 + * @stable ICU 3.8
1.217 + */
1.218 + const UnicodeString& getAppendItemName(UDateTimePatternField field) const;
1.219 +
1.220 + /**
1.221 + * The date time format is a message format pattern used to compose date and
1.222 + * time patterns. The default value is "{0} {1}", where {0} will be replaced
1.223 + * by the date pattern and {1} will be replaced by the time pattern.
1.224 + * <p>
1.225 + * This is used when the input skeleton contains both date and time fields,
1.226 + * but there is not a close match among the added patterns. For example,
1.227 + * suppose that this object was created by adding "dd-MMM" and "hh:mm", and
1.228 + * its datetimeFormat is the default "{0} {1}". Then if the input skeleton
1.229 + * is "MMMdhmm", there is not an exact match, so the input skeleton is
1.230 + * broken up into two components "MMMd" and "hmm". There are close matches
1.231 + * for those two skeletons, so the result is put together with this pattern,
1.232 + * resulting in "d-MMM h:mm".
1.233 + *
1.234 + * @param dateTimeFormat
1.235 + * message format pattern, here {0} will be replaced by the date
1.236 + * pattern and {1} will be replaced by the time pattern.
1.237 + * @stable ICU 3.8
1.238 + */
1.239 + void setDateTimeFormat(const UnicodeString& dateTimeFormat);
1.240 +
1.241 + /**
1.242 + * Getter corresponding to setDateTimeFormat.
1.243 + * @return DateTimeFormat.
1.244 + * @stable ICU 3.8
1.245 + */
1.246 + const UnicodeString& getDateTimeFormat() const;
1.247 +
1.248 + /**
1.249 + * Return the best pattern matching the input skeleton. It is guaranteed to
1.250 + * have all of the fields in the skeleton.
1.251 + *
1.252 + * @param skeleton
1.253 + * The skeleton is a pattern containing only the variable fields.
1.254 + * For example, "MMMdd" and "mmhh" are skeletons.
1.255 + * @param status Output param set to success/failure code on exit,
1.256 + * which must not indicate a failure before the function call.
1.257 + * @return bestPattern
1.258 + * The best pattern found from the given skeleton.
1.259 + * @stable ICU 3.8
1.260 + * <p>
1.261 + * <h4>Sample code</h4>
1.262 + * \snippet samples/dtptngsample/dtptngsample.cpp getBestPatternExample1
1.263 + * \snippet samples/dtptngsample/dtptngsample.cpp getBestPatternExample
1.264 + * <p>
1.265 + */
1.266 + UnicodeString getBestPattern(const UnicodeString& skeleton, UErrorCode& status);
1.267 +
1.268 +
1.269 + /**
1.270 + * Return the best pattern matching the input skeleton. It is guaranteed to
1.271 + * have all of the fields in the skeleton.
1.272 + *
1.273 + * @param skeleton
1.274 + * The skeleton is a pattern containing only the variable fields.
1.275 + * For example, "MMMdd" and "mmhh" are skeletons.
1.276 + * @param options
1.277 + * Options for forcing the length of specified fields in the
1.278 + * returned pattern to match those in the skeleton (when this
1.279 + * would not happen otherwise). For default behavior, use
1.280 + * UDATPG_MATCH_NO_OPTIONS.
1.281 + * @param status
1.282 + * Output param set to success/failure code on exit,
1.283 + * which must not indicate a failure before the function call.
1.284 + * @return bestPattern
1.285 + * The best pattern found from the given skeleton.
1.286 + * @stable ICU 4.4
1.287 + */
1.288 + UnicodeString getBestPattern(const UnicodeString& skeleton,
1.289 + UDateTimePatternMatchOptions options,
1.290 + UErrorCode& status);
1.291 +
1.292 +
1.293 + /**
1.294 + * Adjusts the field types (width and subtype) of a pattern to match what is
1.295 + * in a skeleton. That is, if you supply a pattern like "d-M H:m", and a
1.296 + * skeleton of "MMMMddhhmm", then the input pattern is adjusted to be
1.297 + * "dd-MMMM hh:mm". This is used internally to get the best match for the
1.298 + * input skeleton, but can also be used externally.
1.299 + *
1.300 + * @param pattern Input pattern
1.301 + * @param skeleton
1.302 + * The skeleton is a pattern containing only the variable fields.
1.303 + * For example, "MMMdd" and "mmhh" are skeletons.
1.304 + * @param status Output param set to success/failure code on exit,
1.305 + * which must not indicate a failure before the function call.
1.306 + * @return pattern adjusted to match the skeleton fields widths and subtypes.
1.307 + * @stable ICU 3.8
1.308 + * <p>
1.309 + * <h4>Sample code</h4>
1.310 + * \snippet samples/dtptngsample/dtptngsample.cpp getBestPatternExample1
1.311 + * \snippet samples/dtptngsample/dtptngsample.cpp replaceFieldTypesExample
1.312 + * <p>
1.313 + */
1.314 + UnicodeString replaceFieldTypes(const UnicodeString& pattern,
1.315 + const UnicodeString& skeleton,
1.316 + UErrorCode& status);
1.317 +
1.318 + /**
1.319 + * Adjusts the field types (width and subtype) of a pattern to match what is
1.320 + * in a skeleton. That is, if you supply a pattern like "d-M H:m", and a
1.321 + * skeleton of "MMMMddhhmm", then the input pattern is adjusted to be
1.322 + * "dd-MMMM hh:mm". This is used internally to get the best match for the
1.323 + * input skeleton, but can also be used externally.
1.324 + *
1.325 + * @param pattern Input pattern
1.326 + * @param skeleton
1.327 + * The skeleton is a pattern containing only the variable fields.
1.328 + * For example, "MMMdd" and "mmhh" are skeletons.
1.329 + * @param options
1.330 + * Options controlling whether the length of specified fields in the
1.331 + * pattern are adjusted to match those in the skeleton (when this
1.332 + * would not happen otherwise). For default behavior, use
1.333 + * UDATPG_MATCH_NO_OPTIONS.
1.334 + * @param status
1.335 + * Output param set to success/failure code on exit,
1.336 + * which must not indicate a failure before the function call.
1.337 + * @return pattern adjusted to match the skeleton fields widths and subtypes.
1.338 + * @stable ICU 4.4
1.339 + */
1.340 + UnicodeString replaceFieldTypes(const UnicodeString& pattern,
1.341 + const UnicodeString& skeleton,
1.342 + UDateTimePatternMatchOptions options,
1.343 + UErrorCode& status);
1.344 +
1.345 + /**
1.346 + * Return a list of all the skeletons (in canonical form) from this class.
1.347 + *
1.348 + * Call getPatternForSkeleton() to get the corresponding pattern.
1.349 + *
1.350 + * @param status Output param set to success/failure code on exit,
1.351 + * which must not indicate a failure before the function call.
1.352 + * @return StringEnumeration with the skeletons.
1.353 + * The caller must delete the object.
1.354 + * @stable ICU 3.8
1.355 + */
1.356 + StringEnumeration* getSkeletons(UErrorCode& status) const;
1.357 +
1.358 + /**
1.359 + * Get the pattern corresponding to a given skeleton.
1.360 + * @param skeleton
1.361 + * @return pattern corresponding to a given skeleton.
1.362 + * @stable ICU 3.8
1.363 + */
1.364 + const UnicodeString& getPatternForSkeleton(const UnicodeString& skeleton) const;
1.365 +
1.366 + /**
1.367 + * Return a list of all the base skeletons (in canonical form) from this class.
1.368 + *
1.369 + * @param status Output param set to success/failure code on exit,
1.370 + * which must not indicate a failure before the function call.
1.371 + * @return a StringEnumeration with the base skeletons.
1.372 + * The caller must delete the object.
1.373 + * @stable ICU 3.8
1.374 + */
1.375 + StringEnumeration* getBaseSkeletons(UErrorCode& status) const;
1.376 +
1.377 +#ifndef U_HIDE_INTERNAL_API
1.378 + /**
1.379 + * Return a list of redundant patterns are those which if removed, make no
1.380 + * difference in the resulting getBestPattern values. This method returns a
1.381 + * list of them, to help check the consistency of the patterns used to build
1.382 + * this generator.
1.383 + *
1.384 + * @param status Output param set to success/failure code on exit,
1.385 + * which must not indicate a failure before the function call.
1.386 + * @return a StringEnumeration with the redundant pattern.
1.387 + * The caller must delete the object.
1.388 + * @internal ICU 3.8
1.389 + */
1.390 + StringEnumeration* getRedundants(UErrorCode& status);
1.391 +#endif /* U_HIDE_INTERNAL_API */
1.392 +
1.393 + /**
1.394 + * The decimal value is used in formatting fractions of seconds. If the
1.395 + * skeleton contains fractional seconds, then this is used with the
1.396 + * fractional seconds. For example, suppose that the input pattern is
1.397 + * "hhmmssSSSS", and the best matching pattern internally is "H:mm:ss", and
1.398 + * the decimal string is ",". Then the resulting pattern is modified to be
1.399 + * "H:mm:ss,SSSS"
1.400 + *
1.401 + * @param decimal
1.402 + * @stable ICU 3.8
1.403 + */
1.404 + void setDecimal(const UnicodeString& decimal);
1.405 +
1.406 + /**
1.407 + * Getter corresponding to setDecimal.
1.408 + * @return UnicodeString corresponding to the decimal point
1.409 + * @stable ICU 3.8
1.410 + */
1.411 + const UnicodeString& getDecimal() const;
1.412 +
1.413 + /**
1.414 + * ICU "poor man's RTTI", returns a UClassID for the actual class.
1.415 + *
1.416 + * @stable ICU 3.8
1.417 + */
1.418 + virtual UClassID getDynamicClassID() const;
1.419 +
1.420 + /**
1.421 + * ICU "poor man's RTTI", returns a UClassID for this class.
1.422 + *
1.423 + * @stable ICU 3.8
1.424 + */
1.425 + static UClassID U_EXPORT2 getStaticClassID(void);
1.426 +
1.427 +private:
1.428 + /**
1.429 + * Constructor.
1.430 + * @stable ICU 3.8
1.431 + */
1.432 + DateTimePatternGenerator(UErrorCode & status);
1.433 +
1.434 + /**
1.435 + * Constructor.
1.436 + * @stable ICU 3.8
1.437 + */
1.438 + DateTimePatternGenerator(const Locale& locale, UErrorCode & status);
1.439 +
1.440 + /**
1.441 + * Copy constructor.
1.442 + * @param other DateTimePatternGenerator to copy
1.443 + * @stable ICU 3.8
1.444 + */
1.445 + DateTimePatternGenerator(const DateTimePatternGenerator& other);
1.446 +
1.447 + /**
1.448 + * Default assignment operator.
1.449 + * @param other DateTimePatternGenerator to copy
1.450 + * @stable ICU 3.8
1.451 + */
1.452 + DateTimePatternGenerator& operator=(const DateTimePatternGenerator& other);
1.453 +
1.454 + Locale pLocale; // pattern locale
1.455 + FormatParser *fp;
1.456 + DateTimeMatcher* dtMatcher;
1.457 + DistanceInfo *distanceInfo;
1.458 + PatternMap *patternMap;
1.459 + UnicodeString appendItemFormats[UDATPG_FIELD_COUNT];
1.460 + UnicodeString appendItemNames[UDATPG_FIELD_COUNT];
1.461 + UnicodeString dateTimeFormat;
1.462 + UnicodeString decimal;
1.463 + DateTimeMatcher *skipMatcher;
1.464 + Hashtable *fAvailableFormatKeyHash;
1.465 + UnicodeString hackPattern;
1.466 + UnicodeString emptyString;
1.467 + UChar fDefaultHourFormatChar;
1.468 +
1.469 + /* internal flags masks for adjustFieldTypes etc. */
1.470 + enum {
1.471 + kDTPGNoFlags = 0,
1.472 + kDTPGFixFractionalSeconds = 1,
1.473 + kDTPGSkeletonUsesCapJ = 2
1.474 + };
1.475 +
1.476 + void initData(const Locale &locale, UErrorCode &status);
1.477 + void addCanonicalItems();
1.478 + void addICUPatterns(const Locale& locale, UErrorCode& status);
1.479 + void hackTimes(const UnicodeString& hackPattern, UErrorCode& status);
1.480 + void addCLDRData(const Locale& locale, UErrorCode& status);
1.481 + UDateTimePatternConflict addPatternWithSkeleton(const UnicodeString& pattern, const UnicodeString * skeletonToUse, UBool override, UnicodeString& conflictingPattern, UErrorCode& status);
1.482 + void initHashtable(UErrorCode& status);
1.483 + void setDateTimeFromCalendar(const Locale& locale, UErrorCode& status);
1.484 + void setDecimalSymbols(const Locale& locale, UErrorCode& status);
1.485 + UDateTimePatternField getAppendFormatNumber(const char* field) const;
1.486 + UDateTimePatternField getAppendNameNumber(const char* field) const;
1.487 + void getAppendName(UDateTimePatternField field, UnicodeString& value);
1.488 + int32_t getCanonicalIndex(const UnicodeString& field);
1.489 + const UnicodeString* getBestRaw(DateTimeMatcher& source, int32_t includeMask, DistanceInfo* missingFields, const PtnSkeleton** specifiedSkeletonPtr = 0);
1.490 + UnicodeString adjustFieldTypes(const UnicodeString& pattern, const PtnSkeleton* specifiedSkeleton, int32_t flags, UDateTimePatternMatchOptions options = UDATPG_MATCH_NO_OPTIONS);
1.491 + UnicodeString getBestAppending(int32_t missingFields, int32_t flags, UDateTimePatternMatchOptions options = UDATPG_MATCH_NO_OPTIONS);
1.492 + int32_t getTopBitNumber(int32_t foundMask);
1.493 + void setAvailableFormat(const UnicodeString &key, UErrorCode& status);
1.494 + UBool isAvailableFormatSet(const UnicodeString &key) const;
1.495 + void copyHashtable(Hashtable *other, UErrorCode &status);
1.496 + UBool isCanonicalItem(const UnicodeString& item) const;
1.497 +} ;// end class DateTimePatternGenerator
1.498 +
1.499 +U_NAMESPACE_END
1.500 +
1.501 +#endif
