X-Git-Url: https://git.saurik.com/apple/icu.git/blobdiff_plain/2ca993e82fb37b597a3c73ecd1586a139a6579c5..340931cb2e044a2141d11567dd0f782524e32994:/icuSources/i18n/unicode/reldatefmt.h diff --git a/icuSources/i18n/unicode/reldatefmt.h b/icuSources/i18n/unicode/reldatefmt.h index 81c71e16..044465b1 100644 --- a/icuSources/i18n/unicode/reldatefmt.h +++ b/icuSources/i18n/unicode/reldatefmt.h @@ -1,3 +1,5 @@ +// © 2016 and later: Unicode, Inc. and others. +// License & terms of use: http://www.unicode.org/copyright.html /* ***************************************************************************** * Copyright (C) 2014-2016, International Business Machines Corporation and @@ -13,17 +15,21 @@ #define __RELDATEFMT_H #include "unicode/utypes.h" + +#if U_SHOW_CPLUSPLUS_API + #include "unicode/uobject.h" #include "unicode/udisplaycontext.h" #include "unicode/ureldatefmt.h" #include "unicode/locid.h" +#include "unicode/formattedvalue.h" /** * \file * \brief C++ API: Formats relative dates such as "1 day ago" or "tomorrow" */ -#if !UCONFIG_NO_FORMATTING && !UCONFIG_NO_BREAK_ITERATION +#if !UCONFIG_NO_FORMATTING /** * Represents the unit for formatting a relative date. e.g "in 5 days" @@ -74,11 +80,13 @@ typedef enum UDateRelativeUnit { */ UDAT_RELATIVE_YEARS, +#ifndef U_HIDE_DEPRECATED_API /** - * Count of items in this enum. - * @stable ICU 53 + * One more than the highest normal UDateRelativeUnit value. + * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. */ UDAT_RELATIVE_UNIT_COUNT +#endif // U_HIDE_DEPRECATED_API } UDateRelativeUnit; /** @@ -162,10 +170,32 @@ typedef enum UDateAbsoluteUnit { UDAT_ABSOLUTE_NOW, /** - * Count of items in this enum. - * @stable ICU 53 + * Quarter + * @stable ICU 63 + */ + UDAT_ABSOLUTE_QUARTER, + +#ifndef U_HIDE_DRAFT_API + /** + * Hour + * @draft ICU 65 + */ + UDAT_ABSOLUTE_HOUR, + + /** + * Minute + * @draft ICU 65 + */ + UDAT_ABSOLUTE_MINUTE, +#endif // U_HIDE_DRAFT_API + +#ifndef U_HIDE_DEPRECATED_API + /** + * One more than the highest normal UDateAbsoluteUnit value. + * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. */ - UDAT_ABSOLUTE_UNIT_COUNT + UDAT_ABSOLUTE_UNIT_COUNT = UDAT_ABSOLUTE_NOW + 4 +#endif // U_HIDE_DEPRECATED_API } UDateAbsoluteUnit; /** @@ -211,22 +241,93 @@ typedef enum UDateDirection { */ UDAT_DIRECTION_PLAIN, +#ifndef U_HIDE_DEPRECATED_API /** - * Count of items in this enum. - * @stable ICU 53 + * One more than the highest normal UDateDirection value. + * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. */ UDAT_DIRECTION_COUNT +#endif // U_HIDE_DEPRECATED_API } UDateDirection; +#if !UCONFIG_NO_BREAK_ITERATION U_NAMESPACE_BEGIN +class BreakIterator; class RelativeDateTimeCacheData; class SharedNumberFormat; class SharedPluralRules; class SharedBreakIterator; class NumberFormat; class UnicodeString; +class FormattedRelativeDateTime; +class FormattedRelativeDateTimeData; + +#ifndef U_HIDE_DRAFT_API +/** + * An immutable class containing the result of a relative datetime formatting operation. + * + * Instances of this class are immutable and thread-safe. + * + * Not intended for public subclassing. + * + * @draft ICU 64 + */ +class U_I18N_API FormattedRelativeDateTime : public UMemory, public FormattedValue { + public: + /** + * Default constructor; makes an empty FormattedRelativeDateTime. + * @draft ICU 64 + */ + FormattedRelativeDateTime() : fData(nullptr), fErrorCode(U_INVALID_STATE_ERROR) {} + + /** + * Move constructor: Leaves the source FormattedRelativeDateTime in an undefined state. + * @draft ICU 64 + */ + FormattedRelativeDateTime(FormattedRelativeDateTime&& src) U_NOEXCEPT; + + /** + * Destruct an instance of FormattedRelativeDateTime. + * @draft ICU 64 + */ + virtual ~FormattedRelativeDateTime() U_OVERRIDE; + + /** Copying not supported; use move constructor instead. */ + FormattedRelativeDateTime(const FormattedRelativeDateTime&) = delete; + + /** Copying not supported; use move assignment instead. */ + FormattedRelativeDateTime& operator=(const FormattedRelativeDateTime&) = delete; + + /** + * Move assignment: Leaves the source FormattedRelativeDateTime in an undefined state. + * @draft ICU 64 + */ + FormattedRelativeDateTime& operator=(FormattedRelativeDateTime&& src) U_NOEXCEPT; + + /** @copydoc FormattedValue::toString() */ + UnicodeString toString(UErrorCode& status) const U_OVERRIDE; + + /** @copydoc FormattedValue::toTempString() */ + UnicodeString toTempString(UErrorCode& status) const U_OVERRIDE; + + /** @copydoc FormattedValue::appendTo() */ + Appendable &appendTo(Appendable& appendable, UErrorCode& status) const U_OVERRIDE; + + /** @copydoc FormattedValue::nextPosition() */ + UBool nextPosition(ConstrainedFieldPosition& cfpos, UErrorCode& status) const U_OVERRIDE; + + private: + FormattedRelativeDateTimeData *fData; + UErrorCode fErrorCode; + explicit FormattedRelativeDateTime(FormattedRelativeDateTimeData *results) + : fData(results), fErrorCode(U_ZERO_ERROR) {} + explicit FormattedRelativeDateTime(UErrorCode errorCode) + : fData(nullptr), fErrorCode(errorCode) {} + friend class RelativeDateTimeFormatter; +}; +#endif /* U_HIDE_DRAFT_API */ /** * Formats simple relative dates. There are two types of relative dates that @@ -318,7 +419,7 @@ public: * @param nfToAdopt Constructed object takes ownership of this pointer. * It is an error for caller to delete this pointer or change its * contents after calling this constructor. - * @status Any error is returned here. + * @param status Any error is returned here. * @stable ICU 53 */ RelativeDateTimeFormatter( @@ -336,7 +437,7 @@ public: * @param style the format style. The UDAT_RELATIVE bit field has no effect. * @param capitalizationContext A value from UDisplayContext that pertains to * capitalization. - * @status Any error is returned here. + * @param status Any error is returned here. * @stable ICU 54 */ RelativeDateTimeFormatter( @@ -368,6 +469,10 @@ public: /** * Formats a relative date with a quantity such as "in 5 days" or * "3 months ago" + * + * This method returns a String. To get more information about the + * formatting result, use formatToValue(). + * * @param quantity The numerical amount e.g 5. This value is formatted * according to this object's NumberFormat object. * @param direction NEXT means a future relative date; LAST means a past @@ -387,8 +492,37 @@ public: UnicodeString& appendTo, UErrorCode& status) const; +#ifndef U_HIDE_DRAFT_API + /** + * Formats a relative date with a quantity such as "in 5 days" or + * "3 months ago" + * + * This method returns a FormattedRelativeDateTime, which exposes more + * information than the String returned by format(). + * + * @param quantity The numerical amount e.g 5. This value is formatted + * according to this object's NumberFormat object. + * @param direction NEXT means a future relative date; LAST means a past + * relative date. If direction is anything else, this method sets + * status to U_ILLEGAL_ARGUMENT_ERROR. + * @param unit the unit e.g day? month? year? + * @param status ICU error code returned here. + * @return The formatted relative datetime + * @draft ICU 64 + */ + FormattedRelativeDateTime formatToValue( + double quantity, + UDateDirection direction, + UDateRelativeUnit unit, + UErrorCode& status) const; +#endif /* U_HIDE_DRAFT_API */ + /** * Formats a relative date without a quantity. + * + * This method returns a String. To get more information about the + * formatting result, use formatToValue(). + * * @param direction NEXT, LAST, THIS, etc. * @param unit e.g SATURDAY, DAY, MONTH * @param appendTo The string to which the formatted result will be @@ -406,10 +540,34 @@ public: UErrorCode& status) const; #ifndef U_HIDE_DRAFT_API + /** + * Formats a relative date without a quantity. + * + * This method returns a FormattedRelativeDateTime, which exposes more + * information than the String returned by format(). + * + * If the string is not available in the requested locale, the return + * value will be empty (calling toString will give an empty string). + * + * @param direction NEXT, LAST, THIS, etc. + * @param unit e.g SATURDAY, DAY, MONTH + * @param status ICU error code returned here. + * @return The formatted relative datetime + * @draft ICU 64 + */ + FormattedRelativeDateTime formatToValue( + UDateDirection direction, + UDateAbsoluteUnit unit, + UErrorCode& status) const; +#endif /* U_HIDE_DRAFT_API */ + /** * Format a combination of URelativeDateTimeUnit and numeric offset * using a numeric style, e.g. "1 week ago", "in 1 week", * "5 weeks ago", "in 5 weeks". + * + * This method returns a String. To get more information about the + * formatting result, use formatNumericToValue(). * * @param offset The signed offset for the specified unit. This * will be formatted according to this object's @@ -421,7 +579,7 @@ public: * appended. * @param status ICU error code returned here. * @return appendTo - * @draft ICU 57 + * @stable ICU 57 */ UnicodeString& formatNumeric( double offset, @@ -429,6 +587,31 @@ public: UnicodeString& appendTo, UErrorCode& status) const; +#ifndef U_HIDE_DRAFT_API + /** + * Format a combination of URelativeDateTimeUnit and numeric offset + * using a numeric style, e.g. "1 week ago", "in 1 week", + * "5 weeks ago", "in 5 weeks". + * + * This method returns a FormattedRelativeDateTime, which exposes more + * information than the String returned by formatNumeric(). + * + * @param offset The signed offset for the specified unit. This + * will be formatted according to this object's + * NumberFormat object. + * @param unit The unit to use when formatting the relative + * date, e.g. UDAT_REL_UNIT_WEEK, + * UDAT_REL_UNIT_FRIDAY. + * @param status ICU error code returned here. + * @return The formatted relative datetime + * @draft ICU 64 + */ + FormattedRelativeDateTime formatNumericToValue( + double offset, + URelativeDateTimeUnit unit, + UErrorCode& status) const; +#endif /* U_HIDE_DRAFT_API */ + /** * Format a combination of URelativeDateTimeUnit and numeric offset * using a text style if possible, e.g. "last week", "this week", @@ -436,6 +619,9 @@ public: * style if no appropriate text term is available for the specified * offset in the object's locale. * + * This method returns a String. To get more information about the + * formatting result, use formatToValue(). + * * @param offset The signed offset for the specified unit. * @param unit The unit to use when formatting the relative * date, e.g. UDAT_REL_UNIT_WEEK, @@ -444,13 +630,37 @@ public: * appended. * @param status ICU error code returned here. * @return appendTo - * @draft ICU 57 + * @stable ICU 57 */ UnicodeString& format( double offset, URelativeDateTimeUnit unit, UnicodeString& appendTo, UErrorCode& status) const; + +#ifndef U_HIDE_DRAFT_API + /** + * Format a combination of URelativeDateTimeUnit and numeric offset + * using a text style if possible, e.g. "last week", "this week", + * "next week", "yesterday", "tomorrow". Falls back to numeric + * style if no appropriate text term is available for the specified + * offset in the object's locale. + * + * This method returns a FormattedRelativeDateTime, which exposes more + * information than the String returned by format(). + * + * @param offset The signed offset for the specified unit. + * @param unit The unit to use when formatting the relative + * date, e.g. UDAT_REL_UNIT_WEEK, + * UDAT_REL_UNIT_FRIDAY. + * @param status ICU error code returned here. + * @return The formatted relative datetime + * @draft ICU 64 + */ + FormattedRelativeDateTime formatToValue( + double offset, + URelativeDateTimeUnit unit, + UErrorCode& status) const; #endif /* U_HIDE_DRAFT_API */ /** @@ -504,10 +714,52 @@ private: NumberFormat *nfToAdopt, BreakIterator *brkIter, UErrorCode &status); - void adjustForContext(UnicodeString &) const; + UnicodeString& adjustForContext(UnicodeString &) const; + UBool checkNoAdjustForContext(UErrorCode& status) const; + + template + UnicodeString& doFormat( + F callback, + UnicodeString& appendTo, + UErrorCode& status, + Args... args) const; + +#ifndef U_HIDE_DRAFT_API // for FormattedRelativeDateTime + template + FormattedRelativeDateTime doFormatToValue( + F callback, + UErrorCode& status, + Args... args) const; +#endif // U_HIDE_DRAFT_API + + void formatImpl( + double quantity, + UDateDirection direction, + UDateRelativeUnit unit, + FormattedRelativeDateTimeData& output, + UErrorCode& status) const; + void formatAbsoluteImpl( + UDateDirection direction, + UDateAbsoluteUnit unit, + FormattedRelativeDateTimeData& output, + UErrorCode& status) const; + void formatNumericImpl( + double offset, + URelativeDateTimeUnit unit, + FormattedRelativeDateTimeData& output, + UErrorCode& status) const; + void formatRelativeImpl( + double offset, + URelativeDateTimeUnit unit, + FormattedRelativeDateTimeData& output, + UErrorCode& status) const; }; U_NAMESPACE_END -#endif /* !UCONFIG_NO_FORMATTING && !UCONFIG_NO_BREAK_ITERATION*/ -#endif +#endif /* !UCONFIG_NO_BREAK_ITERATION */ +#endif /* !UCONFIG_NO_FORMATTING */ + +#endif /* U_SHOW_CPLUSPLUS_API */ + +#endif /* __RELDATEFMT_H */