Documentation Source Text

Check-in [5178724f27]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Copy the date+time function documentation out of the wiki.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 5178724f27b403fcd088815b272fb4e39410fb9d
User & Date: drh 2008-06-28 13:31:26
Context
2008-07-04
13:40
Fixed typo in PRAGMA documentation. check-in: bd71688bcb user: mihailim tags: trunk
2008-06-28
13:31
Copy the date+time function documentation out of the wiki. check-in: 5178724f27 user: drh tags: trunk
2008-06-27
18:56
Additional work on the R-Tree documentation. check-in: 010e1a52d7 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/lang.in.

1477
1478
1479
1480
1481
1482
1483

1484
1485
1486


































































































































































































































1487
1488
1489
1490
1491
1492
1493
</table>

<tcl>
##############################################################################
Section {Date And Time Functions} datefunc {}
</tcl>


<p>Date and time functions are documented in the 
<a href="http://www.sqlite.org/cvstrac/wiki?p=DateAndTimeFunctions">
SQLite Wiki</a>.</p>



































































































































































































































<tcl>
##############################################################################
Section {Aggregate Functions} aggfunc {}
</tcl>

<p>







>
|
<
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







1477
1478
1479
1480
1481
1482
1483
1484
1485

1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
</table>

<tcl>
##############################################################################
Section {Date And Time Functions} datefunc {}
</tcl>

<p>
SQLite supports five date and time functions as follows:

</p>

<p>
<ol>
<li> <b>date(</b><i>timestring, modifier, modifier, ...</i><b>)</b> </li>
<li> <b>time(</b><i>timestring, modifier, modifier, ...</i><b>)</b> </li>
<li> <b>datetime(</b><i>timestring, modifier, modifier, ...</i><b>)</b> </li>
<li> <b>julianday(</b><i>timestring, modifier, modifier, ...</i><b>)</b> </li>
<li> <b>strftime(</b><i>format, timestring, modifier, modifier, ...</i><b>)</b> </li>
</ol>

<p>
All five functions take a time string as an argument. This time string
may be followed by zero or more modifiers. 
The strftime() function also takes a format string as its first argument.
</p>

<p>
The date() function returns the date in this format: YYYY-MM-DD. 
The time() function returns the time as HH:MM:SS. 
The datetime() function returns "YYYY-MM-DD HH:MM:SS". 
The julianday() function returns the number of days since noon in
Greenwich on November 24, 4714 B.C. (Gregorian Calendar). 
The julian day number is the preferred internal representation of dates.
The strftime() routine returns the date formatted according to 
the format string specified as the first argument.
The format string supports most, but not all, of the more 
common substitutions found in the strftime() function from 
the standard C library plus two new substitutions, %f and %J.
The following is a complete list of valid strftime() substitutions:
</p>

<blockquote>
<table border="0" cellpadding="0" cellspacing="0">
<tr><td><td width="10"><td></tr>

<tr><td> %d <td><td> day of month
<tr><td> %f <td><td> fractional seconds: SS.SSS
<tr><td> %H <td><td> hour 00-24 
<tr><td> %j <td><td> day of year 001-366
<tr><td> %J <td><td> Julian day number
<tr><td> %m <td><td> month 01-12
<tr><td> %M <td><td> minute 00-59
<tr><td> %s <td><td> seconds since 1970-01-01
<tr><td> %S <td><td> seconds 00-59
<tr><td> %w <td><td> day of week 0-6 with sunday==0
<tr><td> %W <td><td> week of year 00-53
<tr><td> %Y <td><td> year 0000-9999
<tr><td> %% <td><td> %
</table>
</blockquote>

<p>
Notice that all other date and time functions can be expressed
in terms of strftime():
</p>

<blockquote>
<table border="0" cellpadding="0" cellspacing="0">
<tr><td><b>Function</b><td width="30"><td><b>Equivalent strftime()</b>
<tr><td>   date(...)      <td><td>  strftime("%Y-%m-%d", ...)
<tr><td>   time(...)      <td><td>  strftime("%H:%M:%S", ...)
<tr><td>   datetime(...)  <td><td>  strftime("%Y-%m-%d %H:%M:%S", ...)
<tr><td>   julianday(...) <td><td>  strftime("%J", ...)
</table>
</blockquote>

<p>
The only reasons for providing functions other than strftime() is
for convenience and for efficiency.
</p>

<h3>Time Strings</h3>

<p>A time string can be in any of the following formats:</p>

<ol>
<li> <i>YYYY-MM-DD</i>
<li> <i>YYYY-MM-DD HH:MM</i>
<li> <i>YYYY-MM-DD HH:MM:SS</i>
<li> <i>YYYY-MM-DD HH:MM:SS.SSS</i>
<li> <i>YYYY-MM-DD</i><b>T</b><i>HH:MM</i>
<li> <i>YYYY-MM-DD</i><b>T</b><i>HH:MM:SS</i>
<li> <i>YYYY-MM-DD</i><b>T</b><i>HH:MM:SS.SSS</i>
<li> <i>HH:MM</i>
<li> <i>HH:MM:SS</i>
<li> <i>HH:MM:SS.SSS</i>
<li> <b>now</b>
<li> <i>DDDDDDDDDD</i>
</ol>

<p>
In formats 5 through 7, the "T" is a literal character separating 
the date and the time, as required by the ISO-8601 standard. 
Formats 8 through 10 that specify only a time assume a date of 
2000-01-01. Format 11, the string 'now', is converted into the 
current date and time. 
Universal Coordinated Time (UTC) is used. 
Format 12 is the julian day number expressed as a floating point value.
</p>

<h3>Modifiers</h3>

<p>The time string can be followed by zero or more modifiers that 
alter the date or alter the interpretation of the date. 
The available modifiers are as follows.</p>

<ol>
<li> NNN days
<li> NNN hours
<li> NNN minutes
<li> NNN.NNNN seconds
<li> NNN months
<li> NNN years
<li> start of month
<li> start of year
<li> start of day
<li> weekday N
<li> unixepoch
<li> localtime
<li> utc 
</ol>

<p>The first six modifiers (1 through 6) 
simply add the specified amount of time to the date 
specified by the preceding timestring.</p>

<p>The "start of" modifiers (7 through 9) shift the date backwards 
to the beginning of the current month, year or day.</p>

<p>The "weekday" modifier advances the date forward to the next date 
where the weekday number is N. Sunday is 0, Monday is 1, and so forth.</p>

<p>The "unixepoch" modifier (11) only works if it immediately follows 
a timestring in the DDDDDDDDDD format. 
This modifier causes the DDDDDDDDDD to be interpreted not 
as a julian day number as it normally would be, but as the 
number of seconds since 1970. 
This modifier allows unix-based times to be converted to 
julian day numbers easily.</p>

<p>The "localtime" modifier (12) adjusts the previous time
string so that it displays the correct local time. "utc" undoes this.</p>

<h3>Examples</h3>

<p>Compute the current date.<p>

<blockquote>SELECT date('now');</blockquote>

<p>Compute the last day of the current month.</p>

<blockquote>SELECT date('now','start of month','+1 month','-1 day');
</blockquote>

<p>Compute the date and time given a unix timestamp 1092941466.</p>

<blockquote>
    SELECT datetime(1092941466, 'unixepoch');
</blockquote>

<p>Compute the date and time given a unix timestamp 1092941466, and 
compensate for your local timezone.</p>

<blockquote>
  SELECT datetime(1092941466, 'unixepoch', 'localtime');
</blockquote>

<p>Compute the current unix timestamp.</p>

<blockquote>
  SELECT strftime('%s','now');
</blockquote>

<p>Compute the number of days since the battle of Hastings.</p>

<blockquote>
  SELECT julianday('now') - julianday('1066-10-14','gregorian');
</blockquote>

<p>Compute the number of seconds since a particular moment in 2004:</p>

<blockquote>
  SELECT strftime('%s','now') - strftime('%s','2004-01-01 02:34:56');
</blockquote>

<p>
Compute the date of the first Tuesday in October
for the current year.
</p>

<blockquote>
  SELECT date('now','start of year','+9 months','weekday 2');
</blockquote>

<p>Compute the time since the unix epoch in seconds 
(like strftime('%s','now') except includes fractional part):</p>

<blockquote>
  SELECT (julianday('now') - 2440587.5)*86400.0;
</blockquote>

<h3>Caveats And Bugs</h3>

<p>The computation of local time depends heavily on the whim 
of local politicians and is thus difficult to get correct for 
all locales. In this implementation, the standard C library 
function localtime_r() is used to assist in the calculation of 
local time.  The 
localtime_r() C function normally only works for years
between 1970 and 2037. For dates outside this range, SQLite 
attempts to map the year into an equivalent year within 
this range, do the calculation, then map the year back.</p>


<p>Date computations do not give correct results for dates 
before Julian day number 0 (-4713-11-24 12:00:00).</p>

<p>Non-Vista Windows platforms only support one set of DST rules. 
Vista only supports two. Therefore, on these platforms, 
historical DST calculations will be incorrect. 
For example, in the US, in 2007 the DST rules changed. 
Non-Vista Windows platforms apply the new 2007 DST rules 
to all previous years as well. Vista does somewhat better
getting results correct back to 1986, when the rules were also changed.</p>

<p>All internal computations assume the Gregorian calendar system.</p>

<tcl>
##############################################################################
Section {Aggregate Functions} aggfunc {}
</tcl>

<p>