时间和日历类的设计
C++通用框架的设计 作者：naven
1 介绍
时间和日历以及时间的格式化处理在软件的设计中起着非常重要的作用，但是目前C++的库却未有一个简单易用的时间类，大部分都需要开发者直接调用操作系统的API来完成，而且很多API都不是线程安全的。某些大型的C++框架虽然提供一些时间类，但是却不通用，也很难直接拿出来使用。下面介绍一下参考Java Framework中的时间相关的类来设计并实现C++版本的时间和日历类。
主要有如下一些类
Time类，对应于Java的java.util.Date类，表示特定的瞬间，精确到毫秒（Linux可精确到微秒，Solaris可精确到十亿分之一秒）。Time只表示某时某地的瞬间，从1970年1月1日 00:00:00 GMT以来的微秒数，无时区。
Calendar 类，对应于Java的java.util.Calendar类，它既表示了Time的精确瞬间，还代表了此时的年、月、日、时区等。它为特定瞬间与一组诸如 YEAR、MONTH、DAY_OF_MONTH、HOUR 等 日历字段之间的转换提供了一些方法，并为操作日历字段（例如获得下星期的日期）提供了一些方法。瞬间可用微秒值来表示，它是距历元（即格林威治标准时间 1970 年 1 月 1 日的 00:00:00.000，GMT）的偏移量。
TimeFormat类，类似Java的java.text.SimpleDateFormat类，它用来将时间和日历格式化成一个本地时间格式的文本形式，或者指定格式的文本形式。如果格式化时间，将缺省使用操作系统设定的本地（locale）时间格式处理。
TimeParser类，类似Java的java.text.SimpleDateFormat类，与TimeFormat相反，它用来将一个时间的文本转化成一个本地时间Time，缺省使用操作系统设定的本地时间格式处理。
2 Hello World!
下面介绍一下它们的使用
void main()
{
// 获取当前时间，精确到微秒
Time t = Time::getCurrentTime();
// 使用CRT的API格式化时间，只能精确到秒
time_t tt = t.sec();
printf("\n%s\n", ctime(&tt));
// 使用系统缺省的locale输出格式化时间文本
TimeFormat tf("%c");
printf("\n%s\n", tf.format(t).c_str());
// 使用系统缺省的locale输出格式化时间文本
TimeFormat tf2("%#c");
printf("\n%s\n", tf2.format(t).c_str());
// 自定义输出格式化时间文本，精确到豪秒
TimeFormat tff("%Y-%m-%d %H:%M:%S.%q");
printf("\n%s\n", tf2.format(t).c_str());
// 自定义输出格式化时间文本，精确到豪秒，输出所有时间信息，包括时区和年代等
TimeFormat tfCN("%G %Y年%B%d日 %A %H时%M分%S秒%q豪秒 时区%z", "zh_CN.gb2312");
printf("\n%s\n", tfCN.format(t).c_str());
// 使用自定义 zh_CN.gb2312 的locale和字符集输出格式化时间文本，不受系统locale影响
TimeFormat tfCN2("%G %Y %b %d %a %H:%M:%S.%q %z", "zh_CN.gb2312");
printf("\n%s\n", tfCN2.format(t).c_str());
// 使用自定义 en_US.iso8859-1 的locale和字符集输出格式化时间文本，不受系统locale影响
TimeFormat tfUS("%G %d %B %Y %A %H:%M:%S.%q TZ:%z", "en_US.iso8859-1");
printf("\n%s\n", tfUS.format(t).c_str());
TimeFormat tfUS2("%G %Y %b %d %a %H:%M:%S.%q %z", "en_US.iso8859-1");
printf("\n%s\n", tfUS2.format(t).c_str());
// 使用 MIME 标准格式输出格式化时间文本
TimeFormat tfMIME("%a, %d %b %Y %H:%M:%S %z");
printf("\n%s\n", tfMIME.format(t).c_str());
// 使用 MimeParse 方法转换时间
Time t2 = tf.mimeParse(tf.mimeFormat(t));
printf("\n%s\n", tfCN.format(t2).c_str());
}
编译程序将输入如下结果
Wed Nov 9 16:09:40 2005
11/09/05 16:09:40
Wednesday, November 09, 2005 16:09:40
Wednesday, November 09, 2005 16:09:40
公元 2005年十一月09日 星期三 16时09分40秒078豪秒 时区+0800
公元 2005 11月 09 周三 16:09:40.078 +0800
AD 09 November 2005 Wednesday 16:09:40.078 TZ:+0800
AD 2005 Nov 09 Wed 16:09:40.078 +0800
Wed, 09 Nov 2005 16:09:40 +0800
公元 2005年十一月09日 星期三 16时09分40秒000豪秒 时区+0800
3 Time类
由于Time要精确到微秒，所以Time类使用timeval结构存储时间，该结构包含两个long整形，一个表示秒数（从1970年1月1日 00:00:00 GMT以来的偏移量），一个表示微秒数。
Time类的定义如下
class Time
{
private:
/**//**
* Store the values as a timeval which fields as.
* struct timeval {
* long tv_sec; // seconds
* long tv_usec; // microseconds
*/
struct timeval _tv;
}
Time类获取当前精确到微秒的实现如下（Win32提供的API只能精确到豪秒）
Time
Time::gettimeofday()
{
#if defined(HAVE_GETTIMEOFDAY)
struct timeval tp;
tp.tv_sec = 0;
tp.tv_usec = 0;
#ifdef IS_SOLARIS_OS
::gettimeofday(&tp, 0); // microseconds = 1/1,000,000 sec
Time nowtime(tp);
#else
struct timezone tz;
tz.tz_dsttime = 0;
tz.tz_minuteswest = 0;
::gettimeofday(&tp, &tz); // microseconds = 1/1,000,000 sec
Time nowtime(tp);
#endif
return nowtime;
#elif defined(HAVE_FTIME)
struct timeb tb;
tb.dstflag = 0;
tb.millitm = 0;
tb.time = 0;
tb.timezone = 0;
ftime(&tb); // milliseconds = 1/1,000 sec
Time nowtime(tb);
return nowtime;
#elif defined(HAVE_CLOCK_GETTIME)
struct timespec ts;
ts.tv_sec = 0;
ts.tv_nsec = 0;
::clock_gettime(CLOCK_REALTIME, &ts); // nanoseconds = 1/1,000,000,000 sec
Time nowtime(ts);
return nowtime;
#else
//#warning "Time::gettimeofday()- low resolution timer: gettimeofday and ftime unavailable"
Time nowtime(::time(0), 0); // seconds
return nowtime;
#endif
}
Time类提供很多方法如果构造方法和操作符等，可以在time_t和其他时间类型之间转换，也可以单独获取和设置时间的秒和微秒。
4 Calendar类
Calendar类是一个表示日历的类，它可以实现日历的向前向后前进等所有功能。例如你可以设置，获取，和操纵一个日期对象的各个部分，比方一个月的一天或者是一个星期的一天。举例如下：
// 定义日历对象并设置为当前时间
Time nowtm = Time::getCurrentTime();
TimeFormat ntf("%Y-%m-%d %H:%M:%S.%q");
printf("\n%s\n", ntf.format(nowtm).c_str());
Calendar cal;
cal.setTime(nowtm);
// 年月日都向前移动一单位
cal.rollUpYear();
cal.rollUpMonth();
cal.rollUpDayOfMonth();
String scal;
ntf.format(cal, scal);
printf("\n%s\n", scal.c_str());
程序输出结果
2005-11-09 16:45:54.589
2006-12-10 16:45:54.589
Calendar类是建立在Time类的基础上的，并加入了时区等信息，它的定义看起来如下所示：
class Calendar
{
protected:
/**//**
* Value of the <code>ERA</code> field indicating
* the period before the common era (before Christ), also known as BCE.
* The sequence of years at the transition from <code>BC</code> to <code>AD</code> is
* , 2 BC, 1 BC, 1 AD, 2 AD,
* @see Calendar#ERA
*/
int _era;
/**//**
* The currently set time for this calendar, expressed in milliseconds after
* January 1, 1970, 0:00:00 GMT.
* @see #isTimeSet
* @serial
*/
Time _time;
/**//**
* The <code>TimeZone</code> used by this calendar. </code>Calendar</code>
* uses the time zone data to translate between locale and GMT time.
* @serial
*/
struct timezone _zone;
/**//**
* The asctime() and mktime() functions both take an argument
* representing broken-down time which is a binary represen-
* tation separated into year, month, day, etc. Broken-down
* time is stored in the structure tm which is defined in
* <time.h> as follows:<P>
* <code>
* struct tm
* {
* int tm_sec; // seconds
* int tm_min; // minutes
* int tm_hour; // hours
* int tm_mday; // day of the month
* int tm_mon; // month
* int tm_year; // year
* int tm_wday; // day of the week
* int tm_yday; // day in the year
* int tm_isdst; // daylight saving time
* };
* </code>
*/
struct tm _tm;
}
Calendar类定义了很多方法和操作符用来在Time类和时区、年月日等之间转换和设置、读取等。Calendar类实现时间的生成、转换等都是自己实现的，并不调用操作系统的API如mktime()等，并不使用CRT（C运行时）的全局变量如timezone等，所以它是线程安全的，每一个Calendar对象都是互相独立的，拥有自己的时区等信息。
5 TimeFormat类
TimeFormat类主要实现了将时间格式化成一个时间文本，可以使用系统缺省的本地格式，也可以指定格式转换。转换的用法如下：
TimeFormat tf("%Y-%m-%d %H:%M:%S.%q"); //定义一个格式
Time t = Time::getCurrentTime();
String s = tf.format(t); // 将时间对象格式化成文本字符串
时间格式化pattern有如下几种
%a The abbreviated weekday name according to the current locale.
%A The full weekday name according to the current locale.
%b The abbreviated month name according to the current locale.
%B The full month name according to the current locale.
%c The preferred date and time representation for the current locale.
%C The century number (year/100) as a 2-digit integer. (SU)
%d The day of the month as a decimal number (range 01 to 31).
%D Equivalent to %m/%d/%y. (Yecch - for Americans only.
Americans should note that in other countries
%d/%m/%y is rather common. This means that in international context
this format is ambiguous and should not be used.) (SU)
%e Like %d, the day of the month as a decimal number, but a leading
zero is replaced by a space. (SU)
%E Modifier: use alternative format, see below. (SU)
%G The ISO 8601 year with century as a decimal number. The 4-digit
year corresponding to the ISO week number (see %V). This has the
same format and value as %y, except that if the ISO week number
belongs to the previous or next year, that year is used instead. (TZ)
%g Like %G, but without century, i.e., with a 2-digit year (00-99). (TZ)
%h Equivalent to %b. (SU)
%H The hour as a decimal number using a 24-hour clock (range 00 to 23).
%I The hour as a decimal number using a 12-hour clock (range 01 to 12).
%j The day of the year as a decimal number (range 001 to 366).
%k The hour (24-hour clock) as a decimal number (range 0 to 23); single
digits are preceded by a blank. (See also %H.) (TZ)
%l The hour (12-hour clock) as a decimal number (range 1 to 12); single
digits are preceded by a blank. (See also %I.) (TZ)
%m The month as a decimal number (range 01 to 12).
%M The minute as a decimal number (range 00 to 59).
%n A newline character. (SU)
%O Modifier: use alternative format, see below. (SU)
%p Either `AM' or `PM' according to the given time value, or the
corresponding strings for the current locale. Noon is treated as `pm'
and midnight as `am'.
%P Like %p but in lowercase: `am' or `pm' or a corresponding string for
the current locale. (GNU)
%r The time in a.m. or p.m. notation. In the POSIX locale this is
equivalent to `%I:%M:%S %p'. (SU)
%R The time in 24-hour notation (%H:%M). (SU) For a version including the
seconds, see %T below.
%s The number of seconds since the Epoch, i.e., since 1970-01-01 00:00:00 UTC.
(TZ)
%S The second as a decimal number (range 00 to 61).
%t A tab character. (SU)
%T The time in 24-hour notation (%H:%M:%S). (SU)
%u The day of the week as a decimal, range 1 to 7, Monday being 1.
See also %w. (SU)
%U The week number of the current year as a decimal number, range 00 to 53,
starting with the first Sun? day as the first day of week 01.
See also %V and %W.
%V The ISO 8601:1988 week number of the current year as a decimal number,
range 01 to 53, where week 1 is the first week that has at least 4 days
in the current year, and with Monday as the first day of the week.
See also %U and %W. (SU)
%w The day of the week as a decimal, range 0 to 6, Sunday being 0. See also %u.
%W The week number of the current year as a decimal number, range 00 to 53,
starting with the first Mon? day as the first day of week 01.
%x The preferred date representation for the current locale without the time.
%X The preferred time representation for the current locale without the date.
%y The year as a decimal number without a century (range 00 to 99).
%Y The year as a decimal number including the century.
%z The time-zone as hour offset from GMT. Required to emit RFC822-conformant
dates (using "%a, %d %b %Y %H:%M:%S %z"). (GNU)
%Z The time zone or name or abbreviation.
%+ The date and time in date(1) format. (TZ)
%% A literal `%' character.
6 TimeParser类
TimeParser类实现与TimeFormat相反的功能，是将一个指定格式的时间文本转换成时间Time对象或Calendar对象，它的设计与TimeFormat类似，目前还未全部完成，只实现了转换Mime时间格式的文本的功能。
示例见上面的 Hello World 程序。
C++通用框架的设计 作者：naven 日期：2005-11-9