+// © 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
#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"
*/
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;
/**
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;
/**
*/
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
* @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(
* @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(
/**
* 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
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
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
* appended.
* @param status ICU error code returned here.
* @return appendTo
- * @draft ICU 57
+ * @stable ICU 57
*/
UnicodeString& formatNumeric(
double offset,
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",
* 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,
* 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 */
/**
NumberFormat *nfToAdopt,
BreakIterator *brkIter,
UErrorCode &status);
- void adjustForContext(UnicodeString &) const;
+ UnicodeString& adjustForContext(UnicodeString &) const;
+ UBool checkNoAdjustForContext(UErrorCode& status) const;
+
+ template<typename F, typename... Args>
+ UnicodeString& doFormat(
+ F callback,
+ UnicodeString& appendTo,
+ UErrorCode& status,
+ Args... args) const;
+
+#ifndef U_HIDE_DRAFT_API // for FormattedRelativeDateTime
+ template<typename F, typename... Args>
+ 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 */
projects / apple / icu.git / blobdiff