1 // Copyright (c) 2011 The Chromium Authors. All rights reserved. 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. These methods use the current locale 6 // formatting for displaying the time. 7 8 #ifndef BASE_I18N_TIME_FORMATTING_H_ 9 #define BASE_I18N_TIME_FORMATTING_H_ 10 11 #include "base/compiler_specific.h" 12 #include "base/i18n/base_i18n_export.h" 13 #include "base/strings/string16.h" 14 15 namespace base { 16 17 class Time; 18 class TimeDelta; 19 20 // Argument type used to specify the hour clock type. 21 enum HourClockType { 22 k12HourClock, // Uses 1-12. e.g., "3:07 PM" 23 k24HourClock, // Uses 0-23. e.g., "15:07" 24 }; 25 26 // Argument type used to specify whether or not to include AM/PM sign. 27 enum AmPmClockType { 28 kDropAmPm, // Drops AM/PM sign. e.g., "3:07" 29 kKeepAmPm, // Keeps AM/PM sign. e.g., "3:07 PM" 30 }; 31 32 // Should match UMeasureFormatWidth in measfmt.h; replicated here to avoid 33 // requiring third_party/icu dependencies with this file. 34 enum DurationFormatWidth { 35 DURATION_WIDTH_WIDE, // "3 hours, 7 minutes" 36 DURATION_WIDTH_SHORT, // "3 hr, 7 min" 37 DURATION_WIDTH_NARROW, // "3h 7m" 38 DURATION_WIDTH_NUMERIC // "3:07" 39 }; 40 41 // Date formats from third_party/icu/source/i18n/unicode/udat.h. Add more as 42 // necessary. 43 enum DateFormat { 44 // November 2007 45 DATE_FORMAT_YEAR_MONTH, 46 // Tuesday, 7 November 47 DATE_FORMAT_MONTH_WEEKDAY_DAY, 48 }; 49 50 // TODO(derat@chromium.org): Update all of these functions to return boolean 51 // "success" values and use out-params for formatted strings: 52 // http://crbug.com/698802 53 54 // Returns the time of day, e.g., "3:07 PM". 55 BASE_I18N_EXPORT string16 TimeFormatTimeOfDay(const Time& time); 56 57 // Returns the time of day in 24-hour clock format with millisecond accuracy, 58 // e.g., "15:07:30.568" 59 BASE_I18N_EXPORT string16 TimeFormatTimeOfDayWithMilliseconds(const Time& time); 60 61 // Returns the time of day in the specified hour clock type. e.g. 62 // "3:07 PM" (type == k12HourClock, ampm == kKeepAmPm). 63 // "3:07" (type == k12HourClock, ampm == kDropAmPm). 64 // "15:07" (type == k24HourClock). 65 BASE_I18N_EXPORT string16 TimeFormatTimeOfDayWithHourClockType( 66 const Time& time, 67 HourClockType type, 68 AmPmClockType ampm); 69 70 // Returns a shortened date, e.g. "Nov 7, 2007" 71 BASE_I18N_EXPORT string16 TimeFormatShortDate(const Time& time); 72 73 // Returns a numeric date such as 12/13/52. 74 BASE_I18N_EXPORT string16 TimeFormatShortDateNumeric(const Time& time); 75 76 // Returns a numeric date and time such as "12/13/52 2:44:30 PM". 77 BASE_I18N_EXPORT string16 TimeFormatShortDateAndTime(const Time& time); 78 79 // Returns a month and year, e.g. "November 2007" 80 BASE_I18N_EXPORT string16 TimeFormatMonthAndYear(const Time& time); 81 82 // Returns a numeric date and time with time zone such as 83 // "12/13/52 2:44:30 PM PST". 84 BASE_I18N_EXPORT string16 85 TimeFormatShortDateAndTimeWithTimeZone(const Time& time); 86 87 // Formats a time in a friendly sentence format, e.g. 88 // "Monday, March 6, 2008 2:44:30 PM". 89 BASE_I18N_EXPORT string16 TimeFormatFriendlyDateAndTime(const Time& time); 90 91 // Formats a time in a friendly sentence format, e.g. 92 // "Monday, March 6, 2008". 93 BASE_I18N_EXPORT string16 TimeFormatFriendlyDate(const Time& time); 94 95 // Formats a time using a skeleton to produce a format for different locales 96 // when an unusual time format is needed, e.g. "Feb. 2, 18:00". 97 // 98 // See http://userguide.icu-project.org/formatparse/datetime for details. 99 BASE_I18N_EXPORT string16 TimeFormatWithPattern(const Time& time, 100 const char* pattern); 101 102 // Formats a time duration of hours and minutes into various formats, e.g., 103 // "3:07" or "3 hours, 7 minutes", and returns true on success. See 104 // DurationFormatWidth for details. 105 // 106 // Please don't use width = DURATION_WIDTH_NUMERIC when the time duration 107 // can possibly be larger than 24h, as the hour value will be cut below 24 108 // after formatting. 109 // TODO(chengx): fix function output when width = DURATION_WIDTH_NUMERIC 110 // (http://crbug.com/675791) 111 BASE_I18N_EXPORT bool TimeDurationFormat(const TimeDelta time, 112 const DurationFormatWidth width, 113 string16* out) WARN_UNUSED_RESULT; 114 115 // Formats a time duration of hours, minutes and seconds into various formats, 116 // e.g., "3:07:30" or "3 hours, 7 minutes, 30 seconds", and returns true on 117 // success. See DurationFormatWidth for details. 118 // 119 // Please don't use width = DURATION_WIDTH_NUMERIC when the time duration 120 // can possibly be larger than 24h, as the hour value will be cut below 24 121 // after formatting. 122 // TODO(chengx): fix function output when width = DURATION_WIDTH_NUMERIC 123 // (http://crbug.com/675791) 124 BASE_I18N_EXPORT bool TimeDurationFormatWithSeconds( 125 const TimeDelta time, 126 const DurationFormatWidth width, 127 string16* out) WARN_UNUSED_RESULT; 128 129 // Formats a date interval into various formats, e.g. "2 December - 4 December" 130 // or "March 2016 - December 2016". See DateFormat for details. 131 BASE_I18N_EXPORT string16 DateIntervalFormat(const Time& begin_time, 132 const Time& end_time, 133 DateFormat format); 134 135 // Gets the hour clock type of the current locale. e.g. 136 // k12HourClock (en-US). 137 // k24HourClock (en-GB). 138 BASE_I18N_EXPORT HourClockType GetHourClockType(); 139 140 } // namespace base 141 142 #endif // BASE_I18N_TIME_FORMATTING_H_ 143