The <ctime>
header is a wrapper for the C standard <time.h>
header, which declares types and functions for working with dates and times.
Convert a time to a string
char* asctime(const tm* tmptr)
The asctime
function formats a time as a character string. It returns a pointer to a static buffer that is overwritten with each call.
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 length 25. The day of the week (Ddd
) and month name (Mmm
) are not localized. 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.
ctime function, gmtime function, localtime function
Get the processor time
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, where 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 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.
clock_t type, CLOCKS_PER_SEC macro, time function
Represent processor time
typedef ... clock_t
The clock_t
type is an arithmetic type returned by the clock
function.
clock function
Processor time resolution
int CLOCKS_PER_SEC
The CLOCKS_PER_SEC
macro returns the number of clock ticks per second.
clock function
Convert a time to a string
char* ctime(const time_t* timeptr)
The ctime
function converts the calendar time pointed to by timeptr
to local time, and formats the time as a string. It is equivalent to
std::asctime(std::localtime(timeptr));
asctime function, localtime function
Compute the difference between two times
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.
time function, time_t type
Extract parts of a UTC time
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.
If UTC is not available (for example, the host operating system does not provide the time zone offset), NULL
is returned.
localtime function, tm struct
Get the parts of a local time
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.
gmtime function, tm struct
Make a time from parts
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, and 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.
localtime function, time_t type, tm struct
NULL pointer
#define NULL 0
The NULL
macro expands to the integer 0, which represents a null pointer.
NULL in <cstddef>
Size type
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.
size_t in <cstddef>
Format a time as a string
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 zero.
Characters from format are copied to str
, except for conversion specifiers, which start with a percent sign (%
), followed by one of the letters shown in Table 13-6. The LC_TIME
category in the current locale dictates the text that is copied to str
for each conversion specifier.
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 |
AM/PM designation for use with a 12-hour clock |
S |
Second (00 -61 ), up to 2 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 % |
asctime function, ctime function, tm struct
Get the current date and time
time_t time(time_t *timeptr)
The time
function returns the current date and time in an unspecified format. If the host environment cannot provide the calendar time, static_cast<time_t>(-1)
is returned.
If timeptr
is not NULL
, the return value is also stored in *timeptr
.
clock function, time_t type
Represent the parts of a date and time
struct tm { int tm_sec; /* seconds: 0-61 */ int tm_min; /* minutes: 0-60 */ int tm_hour; /* hours: 0-24 */ int tm_mday; /* day of month: 1-31 */ int tm_mon; /* month: 1-12 */ 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, zero 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.
gmtime function, localtime function, mktime function