Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/reldatefmt.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) 2014-2016, International Business Machines Corporation and
jpayne@69 6 * others.
jpayne@69 7 * All Rights Reserved.
jpayne@69 8 *****************************************************************************
jpayne@69 9 *
jpayne@69 10 * File RELDATEFMT.H
jpayne@69 11 *****************************************************************************
jpayne@69 12 */
jpayne@69 13
jpayne@69 14 #ifndef __RELDATEFMT_H
jpayne@69 15 #define __RELDATEFMT_H
jpayne@69 16
jpayne@69 17 #include "unicode/utypes.h"
jpayne@69 18
jpayne@69 19 #if U_SHOW_CPLUSPLUS_API
jpayne@69 20
jpayne@69 21 #include "unicode/uobject.h"
jpayne@69 22 #include "unicode/udisplaycontext.h"
jpayne@69 23 #include "unicode/ureldatefmt.h"
jpayne@69 24 #include "unicode/locid.h"
jpayne@69 25 #include "unicode/formattedvalue.h"
jpayne@69 26
jpayne@69 27 /**
jpayne@69 28 * \file
jpayne@69 29 * \brief C++ API: Formats relative dates such as "1 day ago" or "tomorrow"
jpayne@69 30 */
jpayne@69 31
jpayne@69 32 #if !UCONFIG_NO_FORMATTING
jpayne@69 33
jpayne@69 34 /**
jpayne@69 35 * Represents the unit for formatting a relative date. e.g "in 5 days"
jpayne@69 36 * or "in 3 months"
jpayne@69 37 * @stable ICU 53
jpayne@69 38 */
jpayne@69 39 typedef enum UDateRelativeUnit {
jpayne@69 40
jpayne@69 41 /**
jpayne@69 42 * Seconds
jpayne@69 43 * @stable ICU 53
jpayne@69 44 */
jpayne@69 45 UDAT_RELATIVE_SECONDS,
jpayne@69 46
jpayne@69 47 /**
jpayne@69 48 * Minutes
jpayne@69 49 * @stable ICU 53
jpayne@69 50 */
jpayne@69 51 UDAT_RELATIVE_MINUTES,
jpayne@69 52
jpayne@69 53 /**
jpayne@69 54 * Hours
jpayne@69 55 * @stable ICU 53
jpayne@69 56 */
jpayne@69 57 UDAT_RELATIVE_HOURS,
jpayne@69 58
jpayne@69 59 /**
jpayne@69 60 * Days
jpayne@69 61 * @stable ICU 53
jpayne@69 62 */
jpayne@69 63 UDAT_RELATIVE_DAYS,
jpayne@69 64
jpayne@69 65 /**
jpayne@69 66 * Weeks
jpayne@69 67 * @stable ICU 53
jpayne@69 68 */
jpayne@69 69 UDAT_RELATIVE_WEEKS,
jpayne@69 70
jpayne@69 71 /**
jpayne@69 72 * Months
jpayne@69 73 * @stable ICU 53
jpayne@69 74 */
jpayne@69 75 UDAT_RELATIVE_MONTHS,
jpayne@69 76
jpayne@69 77 /**
jpayne@69 78 * Years
jpayne@69 79 * @stable ICU 53
jpayne@69 80 */
jpayne@69 81 UDAT_RELATIVE_YEARS,
jpayne@69 82
jpayne@69 83 #ifndef U_HIDE_DEPRECATED_API
jpayne@69 84 /**
jpayne@69 85 * One more than the highest normal UDateRelativeUnit value.
jpayne@69 86 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
jpayne@69 87 */
jpayne@69 88 UDAT_RELATIVE_UNIT_COUNT
jpayne@69 89 #endif // U_HIDE_DEPRECATED_API
jpayne@69 90 } UDateRelativeUnit;
jpayne@69 91
jpayne@69 92 /**
jpayne@69 93 * Represents an absolute unit.
jpayne@69 94 * @stable ICU 53
jpayne@69 95 */
jpayne@69 96 typedef enum UDateAbsoluteUnit {
jpayne@69 97
jpayne@69 98 // Days of week have to remain together and in order from Sunday to
jpayne@69 99 // Saturday.
jpayne@69 100 /**
jpayne@69 101 * Sunday
jpayne@69 102 * @stable ICU 53
jpayne@69 103 */
jpayne@69 104 UDAT_ABSOLUTE_SUNDAY,
jpayne@69 105
jpayne@69 106 /**
jpayne@69 107 * Monday
jpayne@69 108 * @stable ICU 53
jpayne@69 109 */
jpayne@69 110 UDAT_ABSOLUTE_MONDAY,
jpayne@69 111
jpayne@69 112 /**
jpayne@69 113 * Tuesday
jpayne@69 114 * @stable ICU 53
jpayne@69 115 */
jpayne@69 116 UDAT_ABSOLUTE_TUESDAY,
jpayne@69 117
jpayne@69 118 /**
jpayne@69 119 * Wednesday
jpayne@69 120 * @stable ICU 53
jpayne@69 121 */
jpayne@69 122 UDAT_ABSOLUTE_WEDNESDAY,
jpayne@69 123
jpayne@69 124 /**
jpayne@69 125 * Thursday
jpayne@69 126 * @stable ICU 53
jpayne@69 127 */
jpayne@69 128 UDAT_ABSOLUTE_THURSDAY,
jpayne@69 129
jpayne@69 130 /**
jpayne@69 131 * Friday
jpayne@69 132 * @stable ICU 53
jpayne@69 133 */
jpayne@69 134 UDAT_ABSOLUTE_FRIDAY,
jpayne@69 135
jpayne@69 136 /**
jpayne@69 137 * Saturday
jpayne@69 138 * @stable ICU 53
jpayne@69 139 */
jpayne@69 140 UDAT_ABSOLUTE_SATURDAY,
jpayne@69 141
jpayne@69 142 /**
jpayne@69 143 * Day
jpayne@69 144 * @stable ICU 53
jpayne@69 145 */
jpayne@69 146 UDAT_ABSOLUTE_DAY,
jpayne@69 147
jpayne@69 148 /**
jpayne@69 149 * Week
jpayne@69 150 * @stable ICU 53
jpayne@69 151 */
jpayne@69 152 UDAT_ABSOLUTE_WEEK,
jpayne@69 153
jpayne@69 154 /**
jpayne@69 155 * Month
jpayne@69 156 * @stable ICU 53
jpayne@69 157 */
jpayne@69 158 UDAT_ABSOLUTE_MONTH,
jpayne@69 159
jpayne@69 160 /**
jpayne@69 161 * Year
jpayne@69 162 * @stable ICU 53
jpayne@69 163 */
jpayne@69 164 UDAT_ABSOLUTE_YEAR,
jpayne@69 165
jpayne@69 166 /**
jpayne@69 167 * Now
jpayne@69 168 * @stable ICU 53
jpayne@69 169 */
jpayne@69 170 UDAT_ABSOLUTE_NOW,
jpayne@69 171
jpayne@69 172 /**
jpayne@69 173 * Quarter
jpayne@69 174 * @stable ICU 63
jpayne@69 175 */
jpayne@69 176 UDAT_ABSOLUTE_QUARTER,
jpayne@69 177
jpayne@69 178 #ifndef U_HIDE_DRAFT_API
jpayne@69 179 /**
jpayne@69 180 * Hour
jpayne@69 181 * @draft ICU 65
jpayne@69 182 */
jpayne@69 183 UDAT_ABSOLUTE_HOUR,
jpayne@69 184
jpayne@69 185 /**
jpayne@69 186 * Minute
jpayne@69 187 * @draft ICU 65
jpayne@69 188 */
jpayne@69 189 UDAT_ABSOLUTE_MINUTE,
jpayne@69 190 #endif // U_HIDE_DRAFT_API
jpayne@69 191
jpayne@69 192 #ifndef U_HIDE_DEPRECATED_API
jpayne@69 193 /**
jpayne@69 194 * One more than the highest normal UDateAbsoluteUnit value.
jpayne@69 195 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
jpayne@69 196 */
jpayne@69 197 UDAT_ABSOLUTE_UNIT_COUNT = UDAT_ABSOLUTE_NOW + 4
jpayne@69 198 #endif // U_HIDE_DEPRECATED_API
jpayne@69 199 } UDateAbsoluteUnit;
jpayne@69 200
jpayne@69 201 /**
jpayne@69 202 * Represents a direction for an absolute unit e.g "Next Tuesday"
jpayne@69 203 * or "Last Tuesday"
jpayne@69 204 * @stable ICU 53
jpayne@69 205 */
jpayne@69 206 typedef enum UDateDirection {
jpayne@69 207
jpayne@69 208 /**
jpayne@69 209 * Two before. Not fully supported in every locale.
jpayne@69 210 * @stable ICU 53
jpayne@69 211 */
jpayne@69 212 UDAT_DIRECTION_LAST_2,
jpayne@69 213
jpayne@69 214 /**
jpayne@69 215 * Last
jpayne@69 216 * @stable ICU 53
jpayne@69 217 */
jpayne@69 218 UDAT_DIRECTION_LAST,
jpayne@69 219
jpayne@69 220 /**
jpayne@69 221 * This
jpayne@69 222 * @stable ICU 53
jpayne@69 223 */
jpayne@69 224 UDAT_DIRECTION_THIS,
jpayne@69 225
jpayne@69 226 /**
jpayne@69 227 * Next
jpayne@69 228 * @stable ICU 53
jpayne@69 229 */
jpayne@69 230 UDAT_DIRECTION_NEXT,
jpayne@69 231
jpayne@69 232 /**
jpayne@69 233 * Two after. Not fully supported in every locale.
jpayne@69 234 * @stable ICU 53
jpayne@69 235 */
jpayne@69 236 UDAT_DIRECTION_NEXT_2,
jpayne@69 237
jpayne@69 238 /**
jpayne@69 239 * Plain, which means the absence of a qualifier.
jpayne@69 240 * @stable ICU 53
jpayne@69 241 */
jpayne@69 242 UDAT_DIRECTION_PLAIN,
jpayne@69 243
jpayne@69 244 #ifndef U_HIDE_DEPRECATED_API
jpayne@69 245 /**
jpayne@69 246 * One more than the highest normal UDateDirection value.
jpayne@69 247 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
jpayne@69 248 */
jpayne@69 249 UDAT_DIRECTION_COUNT
jpayne@69 250 #endif // U_HIDE_DEPRECATED_API
jpayne@69 251 } UDateDirection;
jpayne@69 252
jpayne@69 253 #if !UCONFIG_NO_BREAK_ITERATION
jpayne@69 254
jpayne@69 255 U_NAMESPACE_BEGIN
jpayne@69 256
jpayne@69 257 class BreakIterator;
jpayne@69 258 class RelativeDateTimeCacheData;
jpayne@69 259 class SharedNumberFormat;
jpayne@69 260 class SharedPluralRules;
jpayne@69 261 class SharedBreakIterator;
jpayne@69 262 class NumberFormat;
jpayne@69 263 class UnicodeString;
jpayne@69 264 class FormattedRelativeDateTime;
jpayne@69 265 class FormattedRelativeDateTimeData;
jpayne@69 266
jpayne@69 267 /**
jpayne@69 268 * An immutable class containing the result of a relative datetime formatting operation.
jpayne@69 269 *
jpayne@69 270 * Instances of this class are immutable and thread-safe.
jpayne@69 271 *
jpayne@69 272 * Not intended for public subclassing.
jpayne@69 273 *
jpayne@69 274 * @stable ICU 64
jpayne@69 275 */
jpayne@69 276 class U_I18N_API FormattedRelativeDateTime : public UMemory, public FormattedValue {
jpayne@69 277 public:
jpayne@69 278 /**
jpayne@69 279 * Default constructor; makes an empty FormattedRelativeDateTime.
jpayne@69 280 * @stable ICU 64
jpayne@69 281 */
jpayne@69 282 FormattedRelativeDateTime() : fData(nullptr), fErrorCode(U_INVALID_STATE_ERROR) {}
jpayne@69 283
jpayne@69 284 /**
jpayne@69 285 * Move constructor: Leaves the source FormattedRelativeDateTime in an undefined state.
jpayne@69 286 * @stable ICU 64
jpayne@69 287 */
jpayne@69 288 FormattedRelativeDateTime(FormattedRelativeDateTime&& src) U_NOEXCEPT;
jpayne@69 289
jpayne@69 290 /**
jpayne@69 291 * Destruct an instance of FormattedRelativeDateTime.
jpayne@69 292 * @stable ICU 64
jpayne@69 293 */
jpayne@69 294 virtual ~FormattedRelativeDateTime() U_OVERRIDE;
jpayne@69 295
jpayne@69 296 /** Copying not supported; use move constructor instead. */
jpayne@69 297 FormattedRelativeDateTime(const FormattedRelativeDateTime&) = delete;
jpayne@69 298
jpayne@69 299 /** Copying not supported; use move assignment instead. */
jpayne@69 300 FormattedRelativeDateTime& operator=(const FormattedRelativeDateTime&) = delete;
jpayne@69 301
jpayne@69 302 /**
jpayne@69 303 * Move assignment: Leaves the source FormattedRelativeDateTime in an undefined state.
jpayne@69 304 * @stable ICU 64
jpayne@69 305 */
jpayne@69 306 FormattedRelativeDateTime& operator=(FormattedRelativeDateTime&& src) U_NOEXCEPT;
jpayne@69 307
jpayne@69 308 /** @copydoc FormattedValue::toString() */
jpayne@69 309 UnicodeString toString(UErrorCode& status) const U_OVERRIDE;
jpayne@69 310
jpayne@69 311 /** @copydoc FormattedValue::toTempString() */
jpayne@69 312 UnicodeString toTempString(UErrorCode& status) const U_OVERRIDE;
jpayne@69 313
jpayne@69 314 /** @copydoc FormattedValue::appendTo() */
jpayne@69 315 Appendable &appendTo(Appendable& appendable, UErrorCode& status) const U_OVERRIDE;
jpayne@69 316
jpayne@69 317 /** @copydoc FormattedValue::nextPosition() */
jpayne@69 318 UBool nextPosition(ConstrainedFieldPosition& cfpos, UErrorCode& status) const U_OVERRIDE;
jpayne@69 319
jpayne@69 320 private:
jpayne@69 321 FormattedRelativeDateTimeData *fData;
jpayne@69 322 UErrorCode fErrorCode;
jpayne@69 323 explicit FormattedRelativeDateTime(FormattedRelativeDateTimeData *results)
jpayne@69 324 : fData(results), fErrorCode(U_ZERO_ERROR) {}
jpayne@69 325 explicit FormattedRelativeDateTime(UErrorCode errorCode)
jpayne@69 326 : fData(nullptr), fErrorCode(errorCode) {}
jpayne@69 327 friend class RelativeDateTimeFormatter;
jpayne@69 328 };
jpayne@69 329
jpayne@69 330 /**
jpayne@69 331 * Formats simple relative dates. There are two types of relative dates that
jpayne@69 332 * it handles:
jpayne@69 333 * <ul>
jpayne@69 334 * <li>relative dates with a quantity e.g "in 5 days"</li>
jpayne@69 335 * <li>relative dates without a quantity e.g "next Tuesday"</li>
jpayne@69 336 * </ul>
jpayne@69 337 * <p>
jpayne@69 338 * This API is very basic and is intended to be a building block for more
jpayne@69 339 * fancy APIs. The caller tells it exactly what to display in a locale
jpayne@69 340 * independent way. While this class automatically provides the correct plural
jpayne@69 341 * forms, the grammatical form is otherwise as neutral as possible. It is the
jpayne@69 342 * caller's responsibility to handle cut-off logic such as deciding between
jpayne@69 343 * displaying "in 7 days" or "in 1 week." This API supports relative dates
jpayne@69 344 * involving one single unit. This API does not support relative dates
jpayne@69 345 * involving compound units,
jpayne@69 346 * e.g "in 5 days and 4 hours" nor does it support parsing.
jpayne@69 347 * <p>
jpayne@69 348 * This class is mostly thread safe and immutable with the following caveats:
jpayne@69 349 * 1. The assignment operator violates Immutability. It must not be used
jpayne@69 350 * concurrently with other operations.
jpayne@69 351 * 2. Caller must not hold onto adopted pointers.
jpayne@69 352 * <p>
jpayne@69 353 * This class is not intended for public subclassing.
jpayne@69 354 * <p>
jpayne@69 355 * Here are some examples of use:
jpayne@69 356 * <blockquote>
jpayne@69 357 * <pre>
jpayne@69 358 * UErrorCode status = U_ZERO_ERROR;
jpayne@69 359 * UnicodeString appendTo;
jpayne@69 360 * RelativeDateTimeFormatter fmt(status);
jpayne@69 361 * // Appends "in 1 day"
jpayne@69 362 * fmt.format(
jpayne@69 363 * 1, UDAT_DIRECTION_NEXT, UDAT_RELATIVE_DAYS, appendTo, status);
jpayne@69 364 * // Appends "in 3 days"
jpayne@69 365 * fmt.format(
jpayne@69 366 * 3, UDAT_DIRECTION_NEXT, UDAT_RELATIVE_DAYS, appendTo, status);
jpayne@69 367 * // Appends "3.2 years ago"
jpayne@69 368 * fmt.format(
jpayne@69 369 * 3.2, UDAT_DIRECTION_LAST, UDAT_RELATIVE_YEARS, appendTo, status);
jpayne@69 370 * // Appends "last Sunday"
jpayne@69 371 * fmt.format(UDAT_DIRECTION_LAST, UDAT_ABSOLUTE_SUNDAY, appendTo, status);
jpayne@69 372 * // Appends "this Sunday"
jpayne@69 373 * fmt.format(UDAT_DIRECTION_THIS, UDAT_ABSOLUTE_SUNDAY, appendTo, status);
jpayne@69 374 * // Appends "next Sunday"
jpayne@69 375 * fmt.format(UDAT_DIRECTION_NEXT, UDAT_ABSOLUTE_SUNDAY, appendTo, status);
jpayne@69 376 * // Appends "Sunday"
jpayne@69 377 * fmt.format(UDAT_DIRECTION_PLAIN, UDAT_ABSOLUTE_SUNDAY, appendTo, status);
jpayne@69 378 *
jpayne@69 379 * // Appends "yesterday"
jpayne@69 380 * fmt.format(UDAT_DIRECTION_LAST, UDAT_ABSOLUTE_DAY, appendTo, status);
jpayne@69 381 * // Appends "today"
jpayne@69 382 * fmt.format(UDAT_DIRECTION_THIS, UDAT_ABSOLUTE_DAY, appendTo, status);
jpayne@69 383 * // Appends "tomorrow"
jpayne@69 384 * fmt.format(UDAT_DIRECTION_NEXT, UDAT_ABSOLUTE_DAY, appendTo, status);
jpayne@69 385 * // Appends "now"
jpayne@69 386 * fmt.format(UDAT_DIRECTION_PLAIN, UDAT_ABSOLUTE_NOW, appendTo, status);
jpayne@69 387 *
jpayne@69 388 * </pre>
jpayne@69 389 * </blockquote>
jpayne@69 390 * <p>
jpayne@69 391 * In the future, we may add more forms, such as abbreviated/short forms
jpayne@69 392 * (3 secs ago), and relative day periods ("yesterday afternoon"), etc.
jpayne@69 393 *
jpayne@69 394 * The RelativeDateTimeFormatter class is not intended for public subclassing.
jpayne@69 395 *
jpayne@69 396 * @stable ICU 53
jpayne@69 397 */
jpayne@69 398 class U_I18N_API RelativeDateTimeFormatter : public UObject {
jpayne@69 399 public:
jpayne@69 400
jpayne@69 401 /**
jpayne@69 402 * Create RelativeDateTimeFormatter with default locale.
jpayne@69 403 * @stable ICU 53
jpayne@69 404 */
jpayne@69 405 RelativeDateTimeFormatter(UErrorCode& status);
jpayne@69 406
jpayne@69 407 /**
jpayne@69 408 * Create RelativeDateTimeFormatter with given locale.
jpayne@69 409 * @stable ICU 53
jpayne@69 410 */
jpayne@69 411 RelativeDateTimeFormatter(const Locale& locale, UErrorCode& status);
jpayne@69 412
jpayne@69 413 /**
jpayne@69 414 * Create RelativeDateTimeFormatter with given locale and NumberFormat.
jpayne@69 415 *
jpayne@69 416 * @param locale the locale
jpayne@69 417 * @param nfToAdopt Constructed object takes ownership of this pointer.
jpayne@69 418 * It is an error for caller to delete this pointer or change its
jpayne@69 419 * contents after calling this constructor.
jpayne@69 420 * @param status Any error is returned here.
jpayne@69 421 * @stable ICU 53
jpayne@69 422 */
jpayne@69 423 RelativeDateTimeFormatter(
jpayne@69 424 const Locale& locale, NumberFormat *nfToAdopt, UErrorCode& status);
jpayne@69 425
jpayne@69 426 /**
jpayne@69 427 * Create RelativeDateTimeFormatter with given locale, NumberFormat,
jpayne@69 428 * and capitalization context.
jpayne@69 429 *
jpayne@69 430 * @param locale the locale
jpayne@69 431 * @param nfToAdopt Constructed object takes ownership of this pointer.
jpayne@69 432 * It is an error for caller to delete this pointer or change its
jpayne@69 433 * contents after calling this constructor. Caller may pass NULL for
jpayne@69 434 * this argument if they want default number format behavior.
jpayne@69 435 * @param style the format style. The UDAT_RELATIVE bit field has no effect.
jpayne@69 436 * @param capitalizationContext A value from UDisplayContext that pertains to
jpayne@69 437 * capitalization.
jpayne@69 438 * @param status Any error is returned here.
jpayne@69 439 * @stable ICU 54
jpayne@69 440 */
jpayne@69 441 RelativeDateTimeFormatter(
jpayne@69 442 const Locale& locale,
jpayne@69 443 NumberFormat *nfToAdopt,
jpayne@69 444 UDateRelativeDateTimeFormatterStyle style,
jpayne@69 445 UDisplayContext capitalizationContext,
jpayne@69 446 UErrorCode& status);
jpayne@69 447
jpayne@69 448 /**
jpayne@69 449 * Copy constructor.
jpayne@69 450 * @stable ICU 53
jpayne@69 451 */
jpayne@69 452 RelativeDateTimeFormatter(const RelativeDateTimeFormatter& other);
jpayne@69 453
jpayne@69 454 /**
jpayne@69 455 * Assignment operator.
jpayne@69 456 * @stable ICU 53
jpayne@69 457 */
jpayne@69 458 RelativeDateTimeFormatter& operator=(
jpayne@69 459 const RelativeDateTimeFormatter& other);
jpayne@69 460
jpayne@69 461 /**
jpayne@69 462 * Destructor.
jpayne@69 463 * @stable ICU 53
jpayne@69 464 */
jpayne@69 465 virtual ~RelativeDateTimeFormatter();
jpayne@69 466
jpayne@69 467 /**
jpayne@69 468 * Formats a relative date with a quantity such as "in 5 days" or
jpayne@69 469 * "3 months ago"
jpayne@69 470 *
jpayne@69 471 * This method returns a String. To get more information about the
jpayne@69 472 * formatting result, use formatToValue().
jpayne@69 473 *
jpayne@69 474 * @param quantity The numerical amount e.g 5. This value is formatted
jpayne@69 475 * according to this object's NumberFormat object.
jpayne@69 476 * @param direction NEXT means a future relative date; LAST means a past
jpayne@69 477 * relative date. If direction is anything else, this method sets
jpayne@69 478 * status to U_ILLEGAL_ARGUMENT_ERROR.
jpayne@69 479 * @param unit the unit e.g day? month? year?
jpayne@69 480 * @param appendTo The string to which the formatted result will be
jpayne@69 481 * appended
jpayne@69 482 * @param status ICU error code returned here.
jpayne@69 483 * @return appendTo
jpayne@69 484 * @stable ICU 53
jpayne@69 485 */
jpayne@69 486 UnicodeString& format(
jpayne@69 487 double quantity,
jpayne@69 488 UDateDirection direction,
jpayne@69 489 UDateRelativeUnit unit,
jpayne@69 490 UnicodeString& appendTo,
jpayne@69 491 UErrorCode& status) const;
jpayne@69 492
jpayne@69 493 /**
jpayne@69 494 * Formats a relative date with a quantity such as "in 5 days" or
jpayne@69 495 * "3 months ago"
jpayne@69 496 *
jpayne@69 497 * This method returns a FormattedRelativeDateTime, which exposes more
jpayne@69 498 * information than the String returned by format().
jpayne@69 499 *
jpayne@69 500 * @param quantity The numerical amount e.g 5. This value is formatted
jpayne@69 501 * according to this object's NumberFormat object.
jpayne@69 502 * @param direction NEXT means a future relative date; LAST means a past
jpayne@69 503 * relative date. If direction is anything else, this method sets
jpayne@69 504 * status to U_ILLEGAL_ARGUMENT_ERROR.
jpayne@69 505 * @param unit the unit e.g day? month? year?
jpayne@69 506 * @param status ICU error code returned here.
jpayne@69 507 * @return The formatted relative datetime
jpayne@69 508 * @stable ICU 64
jpayne@69 509 */
jpayne@69 510 FormattedRelativeDateTime formatToValue(
jpayne@69 511 double quantity,
jpayne@69 512 UDateDirection direction,
jpayne@69 513 UDateRelativeUnit unit,
jpayne@69 514 UErrorCode& status) const;
jpayne@69 515
jpayne@69 516 /**
jpayne@69 517 * Formats a relative date without a quantity.
jpayne@69 518 *
jpayne@69 519 * This method returns a String. To get more information about the
jpayne@69 520 * formatting result, use formatToValue().
jpayne@69 521 *
jpayne@69 522 * @param direction NEXT, LAST, THIS, etc.
jpayne@69 523 * @param unit e.g SATURDAY, DAY, MONTH
jpayne@69 524 * @param appendTo The string to which the formatted result will be
jpayne@69 525 * appended. If the value of direction is documented as not being fully
jpayne@69 526 * supported in all locales then this method leaves appendTo unchanged if
jpayne@69 527 * no format string is available.
jpayne@69 528 * @param status ICU error code returned here.
jpayne@69 529 * @return appendTo
jpayne@69 530 * @stable ICU 53
jpayne@69 531 */
jpayne@69 532 UnicodeString& format(
jpayne@69 533 UDateDirection direction,
jpayne@69 534 UDateAbsoluteUnit unit,
jpayne@69 535 UnicodeString& appendTo,
jpayne@69 536 UErrorCode& status) const;
jpayne@69 537
jpayne@69 538 /**
jpayne@69 539 * Formats a relative date without a quantity.
jpayne@69 540 *
jpayne@69 541 * This method returns a FormattedRelativeDateTime, which exposes more
jpayne@69 542 * information than the String returned by format().
jpayne@69 543 *
jpayne@69 544 * If the string is not available in the requested locale, the return
jpayne@69 545 * value will be empty (calling toString will give an empty string).
jpayne@69 546 *
jpayne@69 547 * @param direction NEXT, LAST, THIS, etc.
jpayne@69 548 * @param unit e.g SATURDAY, DAY, MONTH
jpayne@69 549 * @param status ICU error code returned here.
jpayne@69 550 * @return The formatted relative datetime
jpayne@69 551 * @stable ICU 64
jpayne@69 552 */
jpayne@69 553 FormattedRelativeDateTime formatToValue(
jpayne@69 554 UDateDirection direction,
jpayne@69 555 UDateAbsoluteUnit unit,
jpayne@69 556 UErrorCode& status) const;
jpayne@69 557
jpayne@69 558 /**
jpayne@69 559 * Format a combination of URelativeDateTimeUnit and numeric offset
jpayne@69 560 * using a numeric style, e.g. "1 week ago", "in 1 week",
jpayne@69 561 * "5 weeks ago", "in 5 weeks".
jpayne@69 562 *
jpayne@69 563 * This method returns a String. To get more information about the
jpayne@69 564 * formatting result, use formatNumericToValue().
jpayne@69 565 *
jpayne@69 566 * @param offset The signed offset for the specified unit. This
jpayne@69 567 * will be formatted according to this object's
jpayne@69 568 * NumberFormat object.
jpayne@69 569 * @param unit The unit to use when formatting the relative
jpayne@69 570 * date, e.g. UDAT_REL_UNIT_WEEK,
jpayne@69 571 * UDAT_REL_UNIT_FRIDAY.
jpayne@69 572 * @param appendTo The string to which the formatted result will be
jpayne@69 573 * appended.
jpayne@69 574 * @param status ICU error code returned here.
jpayne@69 575 * @return appendTo
jpayne@69 576 * @stable ICU 57
jpayne@69 577 */
jpayne@69 578 UnicodeString& formatNumeric(
jpayne@69 579 double offset,
jpayne@69 580 URelativeDateTimeUnit unit,
jpayne@69 581 UnicodeString& appendTo,
jpayne@69 582 UErrorCode& status) const;
jpayne@69 583
jpayne@69 584 /**
jpayne@69 585 * Format a combination of URelativeDateTimeUnit and numeric offset
jpayne@69 586 * using a numeric style, e.g. "1 week ago", "in 1 week",
jpayne@69 587 * "5 weeks ago", "in 5 weeks".
jpayne@69 588 *
jpayne@69 589 * This method returns a FormattedRelativeDateTime, which exposes more
jpayne@69 590 * information than the String returned by formatNumeric().
jpayne@69 591 *
jpayne@69 592 * @param offset The signed offset for the specified unit. This
jpayne@69 593 * will be formatted according to this object's
jpayne@69 594 * NumberFormat object.
jpayne@69 595 * @param unit The unit to use when formatting the relative
jpayne@69 596 * date, e.g. UDAT_REL_UNIT_WEEK,
jpayne@69 597 * UDAT_REL_UNIT_FRIDAY.
jpayne@69 598 * @param status ICU error code returned here.
jpayne@69 599 * @return The formatted relative datetime
jpayne@69 600 * @stable ICU 64
jpayne@69 601 */
jpayne@69 602 FormattedRelativeDateTime formatNumericToValue(
jpayne@69 603 double offset,
jpayne@69 604 URelativeDateTimeUnit unit,
jpayne@69 605 UErrorCode& status) const;
jpayne@69 606
jpayne@69 607 /**
jpayne@69 608 * Format a combination of URelativeDateTimeUnit and numeric offset
jpayne@69 609 * using a text style if possible, e.g. "last week", "this week",
jpayne@69 610 * "next week", "yesterday", "tomorrow". Falls back to numeric
jpayne@69 611 * style if no appropriate text term is available for the specified
jpayne@69 612 * offset in the object's locale.
jpayne@69 613 *
jpayne@69 614 * This method returns a String. To get more information about the
jpayne@69 615 * formatting result, use formatToValue().
jpayne@69 616 *
jpayne@69 617 * @param offset The signed offset for the specified unit.
jpayne@69 618 * @param unit The unit to use when formatting the relative
jpayne@69 619 * date, e.g. UDAT_REL_UNIT_WEEK,
jpayne@69 620 * UDAT_REL_UNIT_FRIDAY.
jpayne@69 621 * @param appendTo The string to which the formatted result will be
jpayne@69 622 * appended.
jpayne@69 623 * @param status ICU error code returned here.
jpayne@69 624 * @return appendTo
jpayne@69 625 * @stable ICU 57
jpayne@69 626 */
jpayne@69 627 UnicodeString& format(
jpayne@69 628 double offset,
jpayne@69 629 URelativeDateTimeUnit unit,
jpayne@69 630 UnicodeString& appendTo,
jpayne@69 631 UErrorCode& status) const;
jpayne@69 632
jpayne@69 633 /**
jpayne@69 634 * Format a combination of URelativeDateTimeUnit and numeric offset
jpayne@69 635 * using a text style if possible, e.g. "last week", "this week",
jpayne@69 636 * "next week", "yesterday", "tomorrow". Falls back to numeric
jpayne@69 637 * style if no appropriate text term is available for the specified
jpayne@69 638 * offset in the object's locale.
jpayne@69 639 *
jpayne@69 640 * This method returns a FormattedRelativeDateTime, which exposes more
jpayne@69 641 * information than the String returned by format().
jpayne@69 642 *
jpayne@69 643 * @param offset The signed offset for the specified unit.
jpayne@69 644 * @param unit The unit to use when formatting the relative
jpayne@69 645 * date, e.g. UDAT_REL_UNIT_WEEK,
jpayne@69 646 * UDAT_REL_UNIT_FRIDAY.
jpayne@69 647 * @param status ICU error code returned here.
jpayne@69 648 * @return The formatted relative datetime
jpayne@69 649 * @stable ICU 64
jpayne@69 650 */
jpayne@69 651 FormattedRelativeDateTime formatToValue(
jpayne@69 652 double offset,
jpayne@69 653 URelativeDateTimeUnit unit,
jpayne@69 654 UErrorCode& status) const;
jpayne@69 655
jpayne@69 656 /**
jpayne@69 657 * Combines a relative date string and a time string in this object's
jpayne@69 658 * locale. This is done with the same date-time separator used for the
jpayne@69 659 * default calendar in this locale.
jpayne@69 660 *
jpayne@69 661 * @param relativeDateString the relative date, e.g 'yesterday'
jpayne@69 662 * @param timeString the time e.g '3:45'
jpayne@69 663 * @param appendTo concatenated date and time appended here
jpayne@69 664 * @param status ICU error code returned here.
jpayne@69 665 * @return appendTo
jpayne@69 666 * @stable ICU 53
jpayne@69 667 */
jpayne@69 668 UnicodeString& combineDateAndTime(
jpayne@69 669 const UnicodeString& relativeDateString,
jpayne@69 670 const UnicodeString& timeString,
jpayne@69 671 UnicodeString& appendTo,
jpayne@69 672 UErrorCode& status) const;
jpayne@69 673
jpayne@69 674 /**
jpayne@69 675 * Returns the NumberFormat this object is using.
jpayne@69 676 *
jpayne@69 677 * @stable ICU 53
jpayne@69 678 */
jpayne@69 679 const NumberFormat& getNumberFormat() const;
jpayne@69 680
jpayne@69 681 /**
jpayne@69 682 * Returns the capitalization context.
jpayne@69 683 *
jpayne@69 684 * @stable ICU 54
jpayne@69 685 */
jpayne@69 686 UDisplayContext getCapitalizationContext() const;
jpayne@69 687
jpayne@69 688 /**
jpayne@69 689 * Returns the format style.
jpayne@69 690 *
jpayne@69 691 * @stable ICU 54
jpayne@69 692 */
jpayne@69 693 UDateRelativeDateTimeFormatterStyle getFormatStyle() const;
jpayne@69 694
jpayne@69 695 private:
jpayne@69 696 const RelativeDateTimeCacheData* fCache;
jpayne@69 697 const SharedNumberFormat *fNumberFormat;
jpayne@69 698 const SharedPluralRules *fPluralRules;
jpayne@69 699 UDateRelativeDateTimeFormatterStyle fStyle;
jpayne@69 700 UDisplayContext fContext;
jpayne@69 701 const SharedBreakIterator *fOptBreakIterator;
jpayne@69 702 Locale fLocale;
jpayne@69 703 void init(
jpayne@69 704 NumberFormat *nfToAdopt,
jpayne@69 705 BreakIterator *brkIter,
jpayne@69 706 UErrorCode &status);
jpayne@69 707 UnicodeString& adjustForContext(UnicodeString &) const;
jpayne@69 708 UBool checkNoAdjustForContext(UErrorCode& status) const;
jpayne@69 709
jpayne@69 710 template<typename F, typename... Args>
jpayne@69 711 UnicodeString& doFormat(
jpayne@69 712 F callback,
jpayne@69 713 UnicodeString& appendTo,
jpayne@69 714 UErrorCode& status,
jpayne@69 715 Args... args) const;
jpayne@69 716
jpayne@69 717 template<typename F, typename... Args>
jpayne@69 718 FormattedRelativeDateTime doFormatToValue(
jpayne@69 719 F callback,
jpayne@69 720 UErrorCode& status,
jpayne@69 721 Args... args) const;
jpayne@69 722
jpayne@69 723 void formatImpl(
jpayne@69 724 double quantity,
jpayne@69 725 UDateDirection direction,
jpayne@69 726 UDateRelativeUnit unit,
jpayne@69 727 FormattedRelativeDateTimeData& output,
jpayne@69 728 UErrorCode& status) const;
jpayne@69 729 void formatAbsoluteImpl(
jpayne@69 730 UDateDirection direction,
jpayne@69 731 UDateAbsoluteUnit unit,
jpayne@69 732 FormattedRelativeDateTimeData& output,
jpayne@69 733 UErrorCode& status) const;
jpayne@69 734 void formatNumericImpl(
jpayne@69 735 double offset,
jpayne@69 736 URelativeDateTimeUnit unit,
jpayne@69 737 FormattedRelativeDateTimeData& output,
jpayne@69 738 UErrorCode& status) const;
jpayne@69 739 void formatRelativeImpl(
jpayne@69 740 double offset,
jpayne@69 741 URelativeDateTimeUnit unit,
jpayne@69 742 FormattedRelativeDateTimeData& output,
jpayne@69 743 UErrorCode& status) const;
jpayne@69 744 };
jpayne@69 745
jpayne@69 746 U_NAMESPACE_END
jpayne@69 747
jpayne@69 748 #endif /* !UCONFIG_NO_BREAK_ITERATION */
jpayne@69 749 #endif /* !UCONFIG_NO_FORMATTING */
jpayne@69 750
jpayne@69 751 #endif /* U_SHOW_CPLUSPLUS_API */
jpayne@69 752
jpayne@69 753 #endif /* __RELDATEFMT_H */