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.
5 // Basic time formatting methods. These methods use the current locale
6 // formatting for displaying the time.
8 #ifndef BASE_I18N_TIME_FORMATTING_H_
9 #define BASE_I18N_TIME_FORMATTING_H_
11 #include "base/compiler_specific.h"
12 #include "base/i18n/base_i18n_export.h"
13 #include "base/strings/string16.h"
20 // Argument type used to specify the hour clock type.
22 k12HourClock, // Uses 1-12. e.g., "3:07 PM"
23 k24HourClock, // Uses 0-23. e.g., "15:07"
26 // Argument type used to specify whether or not to include AM/PM sign.
28 kDropAmPm, // Drops AM/PM sign. e.g., "3:07"
29 kKeepAmPm, // Keeps AM/PM sign. e.g., "3:07 PM"
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"
41 // Date formats from third_party/icu/source/i18n/unicode/udat.h. Add more as
45 DATE_FORMAT_YEAR_MONTH,
46 // Tuesday, 7 November
47 DATE_FORMAT_MONTH_WEEKDAY_DAY,
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
54 // Returns the time of day, e.g., "3:07 PM".
55 BASE_I18N_EXPORT string16 TimeFormatTimeOfDay(const Time& time);
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);
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(
70 // Returns a shortened date, e.g. "Nov 7, 2007"
71 BASE_I18N_EXPORT string16 TimeFormatShortDate(const Time& time);
73 // Returns a numeric date such as 12/13/52.
74 BASE_I18N_EXPORT string16 TimeFormatShortDateNumeric(const Time& time);
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);
79 // Returns a month and year, e.g. "November 2007"
80 BASE_I18N_EXPORT string16 TimeFormatMonthAndYear(const Time& time);
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);
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);
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);
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".
98 // See http://userguide.icu-project.org/formatparse/datetime for details.
99 BASE_I18N_EXPORT string16 TimeFormatWithPattern(const Time& time,
100 const char* pattern);
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.
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
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;
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.
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
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;
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,
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();
142 #endif // BASE_I18N_TIME_FORMATTING_H_