The strftime() function returns a formatted string
by taking a
(with modifiers) and formating it according to
timestring
, a format
printf() style
format specification. If any of the parameters are in an
incorrect or illegal format, a NULL is returned.
The
string can contain any of the following
markers:format
The
value can be in any of these formats:timestring
All hour values use a 24-hour clock.
Any value that is not given will be implied. Any implied hour,
minute, second, or subsecond is zero. Any implied month or day
of month is 1. Any implied year is 2000. The full date and time
formats allow either a space or a literal uppercase T between the date and time. The
last two values (a single, large integer or floating-point
number) provide the date (or date and time) as expressed in
Julian Days.
Before formatting, the
value is processed by one or more modifiers. The
modifiers are processed one at a time in the order they are
given. The date is normalized after each modifier is
applied.timestring
Modifiers can be in the following formats:
The first set of modifiers adds or
subtracts a given unit of time from the original
value. For example, the call timestring
date( '2001-01-01', '+2 days' ) will return
'2001-01-03'.
Manipulations are done at a very literal level, and the dates
are normalized to legal values after each modifier is applied.
For example, date( '2001-01-01', '-2
days' ) returns '2000-12-30'.
The normalization process can cause
some unexpected results. For example, consider date( '2001-01-31', '+1 month'
). This initially calculates the date '2001-02-31', or February 31st.
Since February never has 31 days, this date is normalized into
the month of March. In the case of 2001 (a nonleap year) the
final result is '2001-03-03'.
It is also significant that normalization is done after each modifier is applied. For
example, the call date(
'2001-01-31', '+1 month', '-1 month' ) will
result in '2001-02-03'.
The start
of... modifiers set all time units that are
smaller than the named unit to their minimum value. For example,
datetime( '2001-02-28 12:30:59',
'start of month' ) will result in '2001-02-01 00:00:00' by setting
everything smaller than a month (day, hour, minute, second) to
its minimum value.
The weekday modifier shifts the current date
forward in time anywhere from zero to six days, so that the day
will fall on the
th day of the week (Sunday = 0).N
The unixepoch modifier only works as an initial
modifier, and only when the date is given as a single numeric
value. This modifier forces the date to be interpreted as a Unix
epoch counter, rather than the traditional Julian Day.
The SQLite date/time functions do not
keep track of time zone data. Unless otherwise specified, all
dates are assumed to be in UTC. For example, the 'now'
will produce date and time values in UTC. To convert
a UTC timestamp to the local time, the modifier timestring
localtime can be applied.
Conversely, if the
is known to be in reference to the local time zone,
the timestring
utc modifier can be used
to convert the timestamp to UTC.
All date and time functions are
designed to operate on dates between 0000-01-01 00:00:00 and 9999-12-31 23:59:59 (Julian Day
numbers 1721059.5 to 5373484.5). Any use of values outside of
this range may result in undefined behavior. Unix epoch values
are only valid through the date/time 5352-11-01
10:52:47.