base/i18n/time_formatting.h

   1 // Copyright 2011 The Chromium Authors
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // Basic time formatting methods.  Most methods format based on the current
   6 // locale. *TimeFormatWithPattern() are special; see comments there.
   7
   8 #ifndef BASE_I18N_TIME_FORMATTING_H_
   9 #define BASE_I18N_TIME_FORMATTING_H_
  10
  11 #include <string>
  12
  13 #include "base/i18n/base_i18n_export.h"
  14 #include "base/strings/string_piece.h"
  15 #include "build/build_config.h"
  16 #include "build/chromeos_buildflags.h"
  17 #include "third_party/icu/source/common/unicode/uversion.h"
  18
  19 U_NAMESPACE_BEGIN
  20 class TimeZone;
  21 U_NAMESPACE_END
  22
  23 namespace base {
  24
  25 class Time;
  26 class TimeDelta;
  27
  28 // Argument type used to specify the hour clock type.
  29 enum HourClockType {
  30   k12HourClock,  // Uses 1-12. e.g., "3:07 PM"
  31   k24HourClock,  // Uses 0-23. e.g., "15:07"
  32 };
  33
  34 // Argument type used to specify whether or not to include AM/PM sign.
  35 enum AmPmClockType {
  36   kDropAmPm,  // Drops AM/PM sign. e.g., "3:07"
  37   kKeepAmPm,  // Keeps AM/PM sign. e.g., "3:07 PM"
  38 };
  39
  40 // Should match UMeasureFormatWidth in measfmt.h; replicated here to avoid
  41 // requiring third_party/icu dependencies with this file.
  42 enum DurationFormatWidth {
  43   DURATION_WIDTH_WIDE,    // "3 hours, 7 minutes"
  44   DURATION_WIDTH_SHORT,   // "3 hr, 7 min"
  45   DURATION_WIDTH_NARROW,  // "3h 7m"
  46   DURATION_WIDTH_NUMERIC  // "3:07"
  47 };
  48
  49 // Date formats from third_party/icu/source/i18n/unicode/udat.h. Add more as
  50 // necessary.
  51 enum DateFormat {
  52   // November 2007
  53   DATE_FORMAT_YEAR_MONTH,
  54   // Tuesday, 7 November
  55   DATE_FORMAT_MONTH_WEEKDAY_DAY,
  56 };
  57
  58 // Returns the time of day, e.g., "3:07 PM".
  59 BASE_I18N_EXPORT std::u16string TimeFormatTimeOfDay(const Time& time);
  60
  61 // Returns the time of day in 24-hour clock format with millisecond accuracy,
  62 // e.g., "15:07:30.568"
  63 BASE_I18N_EXPORT std::u16string TimeFormatTimeOfDayWithMilliseconds(
  64     const Time& time);
  65
  66 // Returns the time of day in the specified hour clock type. e.g.
  67 // "3:07 PM" (type == k12HourClock, ampm == kKeepAmPm).
  68 // "3:07"    (type == k12HourClock, ampm == kDropAmPm).
  69 // "15:07"   (type == k24HourClock).
  70 BASE_I18N_EXPORT std::u16string TimeFormatTimeOfDayWithHourClockType(
  71     const Time& time,
  72     HourClockType type,
  73     AmPmClockType ampm);
  74
  75 // Returns a shortened date, e.g. "Nov 7, 2007"
  76 BASE_I18N_EXPORT std::u16string TimeFormatShortDate(const Time& time);
  77
  78 // Returns a numeric date such as 12/13/52.
  79 BASE_I18N_EXPORT std::u16string TimeFormatShortDateNumeric(const Time& time);
  80
  81 // Returns a numeric date and time such as "12/13/52 2:44:30 PM".
  82 BASE_I18N_EXPORT std::u16string TimeFormatShortDateAndTime(const Time& time);
  83
  84 #if BUILDFLAG(IS_CHROMEOS_ASH)
  85 // Returns a month and year, e.g. "November 2007" for the specified time zone.
  86 BASE_I18N_EXPORT std::u16string TimeFormatMonthAndYearForTimeZone(
  87     const Time& time,
  88     const icu::TimeZone* time_zone);
  89 #endif  // BUILDFLAG(IS_CHROMEOS_ASH)
  90
  91 // Returns a month and year, e.g. "November 2007"
  92 BASE_I18N_EXPORT std::u16string TimeFormatMonthAndYear(const Time& time);
  93
  94 // Returns a numeric date and time with time zone such as
  95 // "12/13/52 2:44:30 PM PST".
  96 BASE_I18N_EXPORT std::u16string TimeFormatShortDateAndTimeWithTimeZone(
  97     const Time& time);
  98
  99 // Formats a time in a friendly sentence format, e.g.
 100 // "Monday, March 6, 2008 2:44:30 PM".
 101 BASE_I18N_EXPORT std::u16string TimeFormatFriendlyDateAndTime(const Time& time);
 102
 103 // Formats a time in a friendly sentence format, e.g.
 104 // "Monday, March 6, 2008".
 105 BASE_I18N_EXPORT std::u16string TimeFormatFriendlyDate(const Time& time);
 106
 107 // Formats a time using a pattern to produce output for different locales when
 108 // an unusual time format is needed, e.g. "Feb. 2, 18:00". See
 109 // https://unicode-org.github.io/icu/userguide/format_parse/datetime/#datetime-format-syntax
 110 // for pattern details.
 111 //
 112 // Use this version when you want to display the resulting string to the user.
 113 //
 114 // This localizes more than you might expect: it does not simply translate days
 115 // of the week, etc., and then feed them into the provided pattern. The pattern
 116 // will also be run through a pattern localizer that will add spacing,
 117 // delimiters, etc. appropriate for the current locale. If you don't want this,
 118 // look at `UnlocalizedTimeFormatWithPattern()` below. If you want translation
 119 // but don't want to adjust the pattern as well, talk to base/ OWNERS about your
 120 // use case.
 121 BASE_I18N_EXPORT std::u16string LocalizedTimeFormatWithPattern(
 122     const Time& time,
 123     StringPiece pattern);
 124
 125 // Formats a time using a pattern to produce en-US-like output, e.g. "Feb. 2,
 126 // 18:00". See
 127 // https://unicode-org.github.io/icu/userguide/format_parse/datetime/#datetime-format-syntax
 128 // for pattern details. NOTE: While ICU only supports millisecond precision
 129 // (fractional second patterns "SSS..." will be filled with zeroes after the
 130 // third 'S'), this supports microsecond precision (up to six 'S's may become
 131 // non-zero values), since some callers need that.
 132 //
 133 // `time_zone` can be set to a desired time zone (e.g.
 134 // icu::TimeZone::getGMT()); if left as null, the local time zone will be used.
 135 //
 136 // Use this version when you want to control the output format precisely, e.g.
 137 // for logging or to format a string for consumption by some server.
 138 //
 139 // This always outputs in US English and does not change the provided pattern at
 140 // all before formatting. It returns a `std::string` instead of a
 141 // `std::u16string` under the assumption that it will not be used in UI.
 142 BASE_I18N_EXPORT std::string UnlocalizedTimeFormatWithPattern(
 143     const Time& time,
 144     StringPiece pattern,
 145     const icu::TimeZone* time_zone = nullptr);
 146
 147 // Formats a time compliant to ISO 8601 in UTC, e.g. "2020-12-31T23:59:59.999Z".
 148 BASE_I18N_EXPORT std::string TimeFormatAsIso8601(const Time& time);
 149
 150 // Formats a time in the IMF-fixdate format defined by RFC 7231 (satisfying its
 151 // HTTP-date format), e.g. "Sun, 06 Nov 1994 08:49:37 GMT".
 152 BASE_I18N_EXPORT std::string TimeFormatHTTP(const Time& time);
 153
 154 // Formats a time duration of hours and minutes into various formats, e.g.,
 155 // "3:07" or "3 hours, 7 minutes", and returns true on success. See
 156 // DurationFormatWidth for details.
 157 [[nodiscard]] BASE_I18N_EXPORT bool TimeDurationFormat(
 158     TimeDelta time,
 159     DurationFormatWidth width,
 160     std::u16string* out);
 161
 162 // Formats a time duration of hours, minutes and seconds into various formats,
 163 // e.g., "3:07:30" or "3 hours, 7 minutes, 30 seconds", and returns true on
 164 // success. See DurationFormatWidth for details.
 165 [[nodiscard]] BASE_I18N_EXPORT bool TimeDurationFormatWithSeconds(
 166     TimeDelta time,
 167     DurationFormatWidth width,
 168     std::u16string* out);
 169
 170 // Formats a date interval into various formats, e.g. "2 December - 4 December"
 171 // or "March 2016 - December 2016". See DateFormat for details.
 172 BASE_I18N_EXPORT std::u16string DateIntervalFormat(const Time& begin_time,
 173                                                    const Time& end_time,
 174                                                    DateFormat format);
 175
 176 // Gets the hour clock type of the current locale. e.g.
 177 // k12HourClock (en-US).
 178 // k24HourClock (en-GB).
 179 BASE_I18N_EXPORT HourClockType GetHourClockType();
 180
 181 }  // namespace base
 182
 183 #endif  // BASE_I18N_TIME_FORMATTING_H_