ui/base/l10n/time_format.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 #ifndef UI_BASE_L10N_TIME_FORMAT_H_
   6 #define UI_BASE_L10N_TIME_FORMAT_H_
   7
   8 #include "base/basictypes.h"
   9 #include "base/strings/string16.h"
  10 #include "ui/base/ui_base_export.h"
  11
  12 namespace base {
  13 class Time;
  14 class TimeDelta;
  15 }
  16
  17 namespace ui {
  18
  19 // Methods to format time values as strings.
  20 class UI_BASE_EXPORT TimeFormat {
  21  public:
  22   enum Format {
  23     FORMAT_DURATION,   // Plain duration, e.g. in English: "2 minutes".
  24     FORMAT_REMAINING,  // Remaining time, e.g. in English: "2 minutes left".
  25     FORMAT_ELAPSED,    // Elapsed time, e.g. in English: "2 minutes ago".
  26     FORMAT_COUNT       // Enum size counter, not a format.  Must be last.
  27   };
  28
  29   enum Length {
  30     LENGTH_SHORT,  // Short format, e.g. in English: sec/min/hour/day.
  31     LENGTH_LONG,   // Long format, e.g. in English: second/minute/hour/day.
  32     LENGTH_COUNT   // Enum size counter, not a length.  Must be last.
  33   };
  34
  35   // Return a localized string of approximate time duration, formatted as a
  36   // single number, e.g. in English "2 hours ago".  Currently, all combinations
  37   // of format and length except (FORMAT_ELAPSED, LENGTH_LONG) are implemented
  38   // but it's easy to add this, if required.
  39   static base::string16 Simple(Format format,
  40                                Length length,
  41                                const base::TimeDelta& delta);
  42
  43   // Return a localized string of more precise time duration, either formatted
  44   // as a single value or as two values: for a time delta of e.g. 2h19m either
  45   // "2 hours" or "2 hours and 19 minutes" could be returned in English.
  46   // Two-value output can be forced by setting |cutoff| to -1.  Single-value
  47   // output can be forced by using Simple() or setting |cutoff| to 0.
  48   // Otherwise, choice of format happens automatically and the value of |cutoff|
  49   // determines the largest numeric value that may appear in a single-value
  50   // format -- for lower numeric values, a second unit is added to increase
  51   // precision.  (Applied to the examples above, a |cutoff| of 2 or smaller
  52   // would yield the first string and a |cutoff| of 3 or larger would return the
  53   // second string.)
  54   //
  55   // The aim of this logic is to reduce rounding errors (that in single-value
  56   // representation can amount up to 33% of the true time duration) while at the
  57   // same time avoiding over-precise time outputs such as e.g. "56 minutes 29
  58   // seconds".  The relative rounding error is guaranteed to be less than 0.5 /
  59   // |cutoff| (e.g. 5% for a |cutoff| of 10) and a second unit is only used when
  60   // necessary to achieve the precision guarantee.
  61   //
  62   // Currently, the only combination of format and length that is implemented is
  63   // (FORMAT_DURATION, LENGTH_LONG), but it's easy to add others if required.
  64   //
  65   // Note: To allow pre-, post- and infixes which can be inflected depending on
  66   // either the first or the second value, two separate translation strings
  67   // (IDS_TIME_*_1ST and IDS_TIME_*_2ND) are used per [plurality] times [pair of
  68   // units] and are concatenated after having been formatted individually.  The
  69   // separator between first unit and second unit (a blank in English) is
  70   // included in IDS_TIME_*_1ST.
  71   static base::string16 Detailed(Format format,
  72                                  Length length,
  73                                  int cutoff,
  74                                  const base::TimeDelta& delta);
  75
  76   // For displaying a relative time in the past.  This method returns either
  77   // "Today", "Yesterday", or an empty string if it's older than that.  Returns
  78   // the empty string for days in the future.
  79   //
  80   // TODO(brettw): This should be able to handle days in the future like
  81   //    "Tomorrow".
  82   // TODO(tc): This should be able to do things like "Last week".  This
  83   //    requires handling singluar/plural for all languages.
  84   //
  85   // The second parameter is optional, it is midnight of "Now" for relative day
  86   // computations: Time::Now().LocalMidnight()
  87   // If NULL, the current day's midnight will be retrieved, which can be
  88   // slow. If many items are being processed, it is best to get the current
  89   // time once at the beginning and pass it for each computation.
  90   static base::string16 RelativeDate(const base::Time& time,
  91                                      const base::Time* optional_midnight_today);
  92
  93  private:
  94   DISALLOW_IMPLICIT_CONSTRUCTORS(TimeFormat);
  95 };
  96
  97 }  // namespace ui
  98
  99 #endif  // UI_BASE_L10N_TIME_FORMAT_H_