base/i18n/time_formatting.h

   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 // Returns the time of day, e.g., "3:07 PM".
  51 BASE_I18N_EXPORT string16 TimeFormatTimeOfDay(const Time& time);
  52
  53 // Returns the time of day in 24-hour clock format with millisecond accuracy,
  54 // e.g., "15:07:30.568"
  55 BASE_I18N_EXPORT string16 TimeFormatTimeOfDayWithMilliseconds(const Time& time);
  56
  57 // Returns the time of day in the specified hour clock type. e.g.
  58 // "3:07 PM" (type == k12HourClock, ampm == kKeepAmPm).
  59 // "3:07"    (type == k12HourClock, ampm == kDropAmPm).
  60 // "15:07"   (type == k24HourClock).
  61 BASE_I18N_EXPORT string16 TimeFormatTimeOfDayWithHourClockType(
  62     const Time& time,
  63     HourClockType type,
  64     AmPmClockType ampm);
  65
  66 // Returns a shortened date, e.g. "Nov 7, 2007"
  67 BASE_I18N_EXPORT string16 TimeFormatShortDate(const Time& time);
  68
  69 // Returns a numeric date such as 12/13/52.
  70 BASE_I18N_EXPORT string16 TimeFormatShortDateNumeric(const Time& time);
  71
  72 // Returns a numeric date and time such as "12/13/52 2:44:30 PM".
  73 BASE_I18N_EXPORT string16 TimeFormatShortDateAndTime(const Time& time);
  74
  75 // Returns a month and year, e.g. "November 2007"
  76 BASE_I18N_EXPORT string16 TimeFormatMonthAndYear(const Time& time);
  77
  78 // Returns a numeric date and time with time zone such as
  79 // "12/13/52 2:44:30 PM PST".
  80 BASE_I18N_EXPORT string16
  81 TimeFormatShortDateAndTimeWithTimeZone(const Time& time);
  82
  83 // Formats a time in a friendly sentence format, e.g.
  84 // "Monday, March 6, 2008 2:44:30 PM".
  85 BASE_I18N_EXPORT string16 TimeFormatFriendlyDateAndTime(const Time& time);
  86
  87 // Formats a time in a friendly sentence format, e.g.
  88 // "Monday, March 6, 2008".
  89 BASE_I18N_EXPORT string16 TimeFormatFriendlyDate(const Time& time);
  90
  91 // Formats a time using a skeleton to produce a format for different locales
  92 // when an unusual time format is needed, e.g. "Feb. 2, 18:00".
  93 //
  94 // See http://userguide.icu-project.org/formatparse/datetime for details.
  95 BASE_I18N_EXPORT string16 TimeFormatWithPattern(const Time& time,
  96                                                 const char* pattern);
  97
  98 // Formats a time duration of hours and minutes into various formats, e.g.,
  99 // "3:07" or "3 hours, 7 minutes", and returns true on success. See
 100 // DurationFormatWidth for details.
 101 //
 102 // Please don't use width = DURATION_WIDTH_NUMERIC when the time duration
 103 // can possibly be larger than 24h, as the hour value will be cut below 24
 104 // after formatting.
 105 // TODO(crbug.com/675791): fix function output when width =
 106 // DURATION_WIDTH_NUMERIC.
 107 BASE_I18N_EXPORT bool TimeDurationFormat(const TimeDelta time,
 108                                          const DurationFormatWidth width,
 109                                          string16* out) WARN_UNUSED_RESULT;
 110
 111 // Formats a time duration of hours, minutes and seconds into various formats,
 112 // e.g., "3:07:30" or "3 hours, 7 minutes, 30 seconds", and returns true on
 113 // success. See DurationFormatWidth for details.
 114 //
 115 // Please don't use width = DURATION_WIDTH_NUMERIC when the time duration
 116 // can possibly be larger than 24h, as the hour value will be cut below 24
 117 // after formatting.
 118 // TODO(crbug.com/675791): fix function output when width =
 119 // DURATION_WIDTH_NUMERIC.
 120 BASE_I18N_EXPORT bool TimeDurationFormatWithSeconds(
 121     const TimeDelta time,
 122     const DurationFormatWidth width,
 123     string16* out) WARN_UNUSED_RESULT;
 124
 125 // Formats a date interval into various formats, e.g. "2 December - 4 December"
 126 // or "March 2016 - December 2016". See DateFormat for details.
 127 BASE_I18N_EXPORT string16 DateIntervalFormat(const Time& begin_time,
 128                                              const Time& end_time,
 129                                              DateFormat format);
 130
 131 // Gets the hour clock type of the current locale. e.g.
 132 // k12HourClock (en-US).
 133 // k24HourClock (en-GB).
 134 BASE_I18N_EXPORT HourClockType GetHourClockType();
 135
 136 }  // namespace base
 137
 138 #endif  // BASE_I18N_TIME_FORMATTING_H_