13.19 <ctime>

The <ctime> header is the C++ version of the C standard <time.h> header, which declares types and functions for working with dates and times.

The time_t type is the fundamental representation of a date and time. The details of this type and how it encodes a date and time are implementation-defined. Unix programmers recognize this type as the number of seconds since January 1, 1970, but that is only one possible implementation.

A date and time have a secondary representation as a tm object, which breaks down a date and time into constituent parts. The parts facilitate formatting dates and times for output, or you can read a date and time, parse the parts, and build a tm object, which you can then convert to a time_t object.

This section describes the types and functions for working with dates and times. The Boost project has additional date and time classes. See Appendix B for information about Boost.

char* asctime(const tm* tmptr)

The asctime function formats the date and time pointed to by tmptr as a character string. It returns a pointer to a static buffer that is overwritten with each call. (The static buffer can be shared with ctime.)

The returned value has the format "Ddd Mmm DD HH:MM:SS YYYY\n" followed by a terminating null character. Thus, the result always has a length of 25. The day of the week (Ddd) and month name (Mmm) are English abbreviations and are not localized—that is, Monday is represented by "Mon" regardless of locale. The day of the month (DD) always takes up the same number of characters, using a leading space if necessary. The hours (HH), minutes (MM), and seconds (SS) use a leading zero if necessary.

See Also

ctime function, gmtime function, localtime function, time_put in <locale>

clock_t clock(  )

The clock function returns the amount of processor time used since an implementation-defined start time. The time is returned in implementation-defined units. There are CLOCKS_PER_SEC units per second.

The value returned by the clock function is not useful by itself but is intended to be used by comparing it with the value returned from an earlier call to clock. For example, the first statement in the main function might be a call to clock; the difference between subsequent calls and the original call tell you how much time has elapsed since the program started.

If the environment cannot provide the processor time, static_cast<clock_t>(-1) is returned.

See Also

clock_t type, CLOCKS_PER_SEC macro, time function

typedef  . . .  clock_t

The clock_t type is an arithmetic type returned by the clock function.

See Also

clock function

int CLOCKS_PER_SEC

The CLOCKS_PER_SEC macro returns the number of clock ticks per second. It is not necessarily a compile-time constant.

See Also

clock function

char* ctime(const time_t* timeptr)

The ctime function converts the date and time pointed to by timeptr to local time and formats the time as a string. It is equivalent to:

std::asctime(std::localtime(timeptr));

The text is written to a static buffer, and a pointer to that buffer is returned. Subsequent calls can overwrite the buffer contents. The static buffer can be shared with asctime.

See Also

asctime function, localtime function

double difftime(time_t t1, time_t t2);

The difftime function computes the difference between two times: t1 - t2. The return value is in seconds.

See Also

time function, time_t type

tm* gmtime(const time_t* timeptr)

The gmtime function expands the calendar time pointed to by timeptr into a static tm object using Coordinated Universal Time (UTC). It returns a pointer to the static object. Subsequent calls to gmtime overwrite the object. The static object can be shared with localtime.

If UTC is not available (for example, the host operating system does not provide the time zone offset), a null pointer is returned.

See Also

localtime function, tm struct

tm* localtime(const time_t* timeptr)

The localtime function expands the calendar time pointed to by timeptr into a static tm object using local time. It returns a pointer to the static object. Subsequent calls to localtime overwrite the object. The static object can be shared with gmtime.

See Also

gmtime function, tm struct

time_t mktime(tm* tmptr)

The mktime function makes a time_t time by assembling the parts in a tm object, interpreted as local time. The tm_wday and tm_yday members are ignored, and other fields are permitted to be outside their normal ranges.

If the conversion is successful, the corresponding time is returned, the tm_wday and tm_yday members are set, and the other fields are changed if necessary to reflect their normal ranges.

If the time cannot be represented as a time_t value, static_cast<time_t>(-1) is returned.

See Also

localtime function, time_t type, tm struct, time_get in <locale>

#define NULL  . . .

The NULL macro expands to a null pointer constant. See <cstddef> for more information.

See Also

NULL in <cstddef>

typedef  . . .  size_t

The size_t type is the type of the result of the sizeof operator. It is an unsigned integral type. The exact type is implementation-defined.

See Also

size_t in <cstddef>

size_t strftime(char* str, size_t n, const char* fmt, const tm* tmptr)

The strftime function formats a tm object as a string. Up to n bytes are stored in str, including a terminating null character. The return value is the number of characters actually stored, not counting the final null character. If the formatted result requires more than n characters, the return value is 0.

Characters from fmt are copied to str, except conversion specifiers, which start with a percent sign (%) and are followed by one of the letters shown in Table 13-6. The LC_TIME category in the current C locale controls the text that is copied to str for each conversion specifier.

Table 13-6. Conversion specifiers for strftime

Specifier	Description
a	Abbreviated weekday name
A	Full weekday name
b	Abbreviated month name
B	Full month name
C	Complete date and time
D	Day of the month (01-31)
H	Hour (00-23); 24-hour clock
I	Hour (01-12); 12-hour clock
j	Day of the year (001-366)
m	Month (01-12)
M	Minutes (00-59)
P	A.M./P.M. designation for use with a 12-hour clock
S	Second (00-61); up to two leap seconds
U	Week number (00-53); week 1 starts with the first Sunday
w	Weekday (0-6); Sunday is day 0
W	Week number (00-53); week 1 starts with first Monday
x	Date
X	Time
y	Year in century (00-99)
Y	Year
Z	Time zone name or abbreviation, or empty string if time zone is unknown
%	Literal %

See Also

asctime function, ctime function, tm struct, time_put in <locale>, <clocale>

time_t time(time_t *timeptr)

The time function returns the current date and time in an implementation-defined format. If the host environment cannot provide the date and time, static_cast<time_t>(-1) is returned.

If timeptr is not null, the return value is also stored in *timeptr.

See Also

clock function, time_t type

typedef  . . .  time_t

The time_t type is an arithmetic type that represents a date and time. The actual type and the encoding of the date and time are implementation-defined.

See Also

clock_t type, time function, tm struct

struct tm {
  int tm_sec;   /* Seconds: 0-61 */
  int tm_min;   /* Minutes: 0-59 */
  int tm_hour;  /* Hours:   0-23 */
  int tm_mday;  /* Day of month: 1-31 */
  int tm_mon;   /* Month: 0-11 */
  int tm_year;  /* Years since 1900 */
  int tm_wday;  /* Days since Sunday: 0-6 */
  int tm_yday;  /* Days since January 1: 0-365 */
  int tm_isdst; /* Daylight Savings Time */
}

The tm structure stores parts of a date and time. The values returned by localtime and gmtime will always be in the ranges shown above. (Note that two extra leap seconds are allowed for tm_sec.)

The tm_isdst member is positive when Daylight Savings Time is in effect, 0 when it is not in effect, or negative if it is unknown.

The order of the members is implementation-defined. An implementation can have additional members.

See Also

gmtime function, localtime function, mktime function, time_t type