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 #include <string_view> 13 14 #include "base/i18n/base_i18n_export.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 std::string_view 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 std::string_view 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_ 184