OLD | NEW |
---|---|
1 // Copyright (c) 2011 The Chromium Authors. All rights reserved. | 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 | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 #ifndef UI_BASE_L10N_TIME_FORMAT_H_ | 5 #ifndef UI_BASE_L10N_TIME_FORMAT_H_ |
6 #define UI_BASE_L10N_TIME_FORMAT_H_ | 6 #define UI_BASE_L10N_TIME_FORMAT_H_ |
7 | 7 |
8 #include "base/basictypes.h" | 8 #include "base/basictypes.h" |
9 #include "base/strings/string16.h" | 9 #include "base/strings/string16.h" |
10 #include "ui/base/ui_base_export.h" | 10 #include "ui/base/ui_base_export.h" |
11 | 11 |
12 namespace base { | 12 namespace base { |
13 class Time; | 13 class Time; |
14 class TimeDelta; | 14 class TimeDelta; |
15 } | 15 } |
16 | 16 |
17 namespace ui { | 17 namespace ui { |
18 | 18 |
19 // Methods to format time values as strings. | 19 // Methods to format time values as strings. |
20 class UI_BASE_EXPORT TimeFormat { | 20 class UI_BASE_EXPORT TimeFormat { |
21 public: | 21 public: |
22 // TimeElapsed, TimeRemaining* and TimeDuration*: | 22 enum Format { |
23 // These functions return a localized string of approximate time duration. | 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 }; | |
24 | 28 |
25 // Returns times in elapsed-format: "3 mins ago", "2 days ago". | 29 enum Length { |
26 static base::string16 TimeElapsed(const base::TimeDelta& delta); | 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 }; | |
27 | 34 |
28 // Returns times in remaining-format: "3 mins left", "2 days left". | 35 // Return a localized string of approximate time duration, formatted as a |
29 static base::string16 TimeRemaining(const base::TimeDelta& delta); | 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); | |
30 | 42 |
31 // Returns times in remaining-long-format: "3 minutes left", "2 days left". | 43 // Return a localized string of more precise time duration, either formatted |
32 static base::string16 TimeRemainingLong(const base::TimeDelta& delta); | 44 // as a single number or as two numbers: for a time delta of e.g. 2h19m either |
33 | 45 // "2 hours" or "2 hours and 19 minutes" could be returned in English. |
34 // Returns times in short-format: "3 mins", "2 days". | 46 // Two-number output can be forced by setting |cutoff| to -1. Single-number |
35 static base::string16 TimeDurationShort(const base::TimeDelta& delta); | 47 // output can be forced by using Simple() or setting |cutoff| to 0. |
36 | 48 // Otherwise, choice of format happens automatically and the value of |cutoff| |
37 // Return times in long-format: "2 hours", "25 minutes". | 49 // determines the largest numeric value that may appear in a single-valued |
38 static base::string16 TimeDurationLong(const base::TimeDelta& delta); | 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 can amount up to | |
56 // 50% in single-valued representation) while at the same time avoiding | |
57 // over-precise time outputs such as e.g. "56 minutes 29 seconds". The | |
58 // relative rounding error is guaranteed to be less than approximately 0.5 / | |
bartfab (slow)
2014/02/20 16:31:23
I like the combination of "guaranteed to" and "app
Thiemo Nagel
2014/02/22 21:44:10
It was tempting to write it that way, but I've cha
| |
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: This is implemented with two translation strings (IDS_TIME_*_1ST and | |
66 // IDS_TIME_*_2ND) per [plurality x pair of units] which are concatenated | |
67 // after having been formatted individually. The separator between first unit | |
68 // and second unit (a blank in English) is included in IDS_TIME_*_1ST. | |
bartfab (slow)
2014/02/20 16:31:23
Nit: The comment is excellent. It may make sense t
Thiemo Nagel
2014/02/22 21:44:10
Done.
| |
69 static base::string16 Detailed(Format format, | |
70 Length length, | |
71 int cutoff, | |
72 const base::TimeDelta& delta); | |
39 | 73 |
40 // For displaying a relative time in the past. This method returns either | 74 // For displaying a relative time in the past. This method returns either |
41 // "Today", "Yesterday", or an empty string if it's older than that. Returns | 75 // "Today", "Yesterday", or an empty string if it's older than that. Returns |
42 // the empty string for days in the future. | 76 // the empty string for days in the future. |
43 // | 77 // |
44 // TODO(brettw): This should be able to handle days in the future like | 78 // TODO(brettw): This should be able to handle days in the future like |
45 // "Tomorrow". | 79 // "Tomorrow". |
46 // TODO(tc): This should be able to do things like "Last week". This | 80 // TODO(tc): This should be able to do things like "Last week". This |
47 // requires handling singluar/plural for all languages. | 81 // requires handling singluar/plural for all languages. |
48 // | 82 // |
49 // The second parameter is optional, it is midnight of "Now" for relative day | 83 // The second parameter is optional, it is midnight of "Now" for relative day |
50 // computations: Time::Now().LocalMidnight() | 84 // computations: Time::Now().LocalMidnight() |
51 // If NULL, the current day's midnight will be retrieved, which can be | 85 // If NULL, the current day's midnight will be retrieved, which can be |
52 // slow. If many items are being processed, it is best to get the current | 86 // slow. If many items are being processed, it is best to get the current |
53 // time once at the beginning and pass it for each computation. | 87 // time once at the beginning and pass it for each computation. |
54 static base::string16 RelativeDate(const base::Time& time, | 88 static base::string16 RelativeDate(const base::Time& time, |
55 const base::Time* optional_midnight_today); | 89 const base::Time* optional_midnight_today); |
56 | 90 |
57 private: | 91 private: |
58 DISALLOW_IMPLICIT_CONSTRUCTORS(TimeFormat); | 92 DISALLOW_IMPLICIT_CONSTRUCTORS(TimeFormat); |
59 }; | 93 }; |
60 | 94 |
61 } // namespace ui | 95 } // namespace ui |
62 | 96 |
63 #endif // UI_BASE_L10N_TIME_FORMAT_H_ | 97 #endif // UI_BASE_L10N_TIME_FORMAT_H_ |
OLD | NEW |