Merge pull request #926 from katzyn/datetime

Describe datetime fields in documentation

h2/src/docsrc/help/help.csv

@@ -1794,6 +1794,171 @@ Admin rights are required to execute this command.
 SHUTDOWN COMPACT
 "
 
+"Datetime fields","Datetime field","
+yearField | monthField | dayOfMonthField
+    | hourField | minuteField | secondField
+    | millisecondField | microsecondField | nanosecondField
+    | timezoneHourField | timezoneMinuteField
+    | dayOfWeekField | isoDayOfWeekField
+    | weekOfYearField | isoWeekOfYearField
+    | quarterField | dayOfYearField | epochField
+","
+Fields for EXTRACT, DATEADD, and DATEDIFF functions.
+","
+YEAR
+"
+
+"Datetime fields","Year field","
+YEAR | YYYY | YY | SQL_TSI_YEAR
+","
+Year.
+","
+YEAR
+"
+
+"Datetime fields","Month field","
+MONTH | MM | M | SQL_TSI_MONTH
+","
+Month (1-12).
+","
+MONTH
+"
+
+"Datetime fields","Day of month field","
+DAY | DD | D | SQL_TSI_DAY
+","
+Day of month (1-31).
+","
+DAY
+"
+
+"Datetime fields","Hour field","
+HOUR | HH | SQL_TSI_HOUR
+","
+Hour (0-23).
+","
+HOUR
+"
+
+"Datetime fields","Minute field","
+MINUTE | MI | N | SQL_TSI_MINUTE
+","
+Minute (0-59).
+","
+MINUTE
+"
+
+"Datetime fields","Second field","
+SECOND | SS | S | SQL_TSI_SECOND
+","
+Second (0-59).
+","
+SECOND
+"
+
+"Datetime fields","Millisecond field","
+MILLISECOND | MS
+","
+Millisecond (0-999).
+","
+MILLISECOND
+"
+
+"Datetime fields","Microsecond field","
+MICROSECOND | MCS
+","
+Microsecond (0-999999).
+","
+MICROSECOND
+"
+
+"Datetime fields","Nanosecond field","
+NANOSECOND | NS
+","
+Nanosecond (0-999999999).
+","
+NANOSECOND
+"
+
+"Datetime fields","Timezone hour field","
+TIMEZONE_HOUR
+","
+Timezone hour (from -18 to +18).
+","
+TIMEZONE_HOUR
+"
+
+"Datetime fields","Timezone minute field","
+TIMEZONE_MINUTE
+","
+Timezone minute (from -59 to +59).
+","
+TIMEZONE_MINUTE
+"
+
+"Datetime fields","Day of week field","
+DAY_OF_WEEK | DAYOFWEEK | DOW
+","
+Day of week (1-7). Sunday is 1.
+","
+DAY_OF_WEEK
+"
+
+"Datetime fields","ISO day of week field","
+ISO_DAY_OF_WEEK
+","
+ISO day of week (1-7). Monday is 1.
+","
+ISO_DAY_OF_WEEK
+"
+
+"Datetime fields","Week of year field","
+WEEK | WW | W | SQL_TSI_WEEK
+","
+Week of year (1-53).
+EXTRACT function uses local rules to get number of week in year.
+DATEDIFF function uses Sunday as a first day of week.
+","
+WEEK
+"
+
+"Datetime fields","ISO week of year field","
+ISO_WEEK
+","
+ISO week of year (1-53).
+ISO definition is used when first week of year should have at least four days
+and week is started with Monday.
+","
+ISO_WEEK
+"
+
+"Datetime fields","Quarter field","
+QUARTER
+","
+Quarter (1-4).
+","
+QUARTER
+"
+
+"Datetime fields","Day of year field","
+DAYOFYEAR | DAY_OF_YEAR | DOY | DY
+","
+Day of year (1-366).
+","
+DAYOFYEAR
+"
+
+"Datetime fields","Epoch field","
+EPOCH
+","
+For TIMESTAMP values number of seconds since 1970-01-01 00:00:00 in local time zone.
+For TIMESTAMP WITH TIME ZONE values number of seconds since 1970-01-01 00:00:00 in UTC time zone.
+For DATE values number of seconds since 1970-01-01.
+For TIME values number of seconds since midnight.
+","
+EPOCH
+"
+
 "Other Grammar","Alias","
 name
 ","
@@ -3704,30 +3869,28 @@ CURRENT_TIMESTAMP()
 "
 
 "Functions (Time and Date)","DATEADD","
-{ DATEADD| TIMESTAMPADD } (unitString, addIntLong, dateAndTime)
+{ DATEADD| TIMESTAMPADD } (datetimeField, addIntLong, dateAndTime)
 ","
 Adds units to a date-time value. The string indicates the unit.
 Use negative values to subtract units.
 addIntLong may be a long value when manipulating milliseconds,
 microseconds, or nanoseconds otherwise its range is restricted to int.
-The same units as in the EXTRACT function are supported.
 This method returns a value with the same type as specified value if unit is compatible with this value.
-If specified unit is a HOUR, MINUTE, SECOND, MILLISECOND, etc and value is a DATE value DATEADD returns combined TIMESTAMP.
-Units DAY, MONTH, YEAR, WEEK, etc are not allowed for TIME values.
-Units TIMEZONE_HOUR and TIMEZONE_MINUTE are only allowed for TIMESTAMP WITH TIME ZONE values.
+If specified field is a HOUR, MINUTE, SECOND, MILLISECOND, etc and value is a DATE value DATEADD returns combined TIMESTAMP.
+Fields DAY, MONTH, YEAR, WEEK, etc are not allowed for TIME values.
+Fields TIMEZONE_HOUR and TIMEZONE_MINUTE are only allowed for TIMESTAMP WITH TIME ZONE values.
 ","
 DATEADD('MONTH', 1, DATE '2001-01-31')
 "
 
 "Functions (Time and Date)","DATEDIFF","
-{ DATEDIFF | TIMESTAMPDIFF } (unitString, aDateAndTime, bDateAndTime)
+{ DATEDIFF | TIMESTAMPDIFF } (datetimeField, aDateAndTime, bDateAndTime)
 ","
 Returns the the number of crossed unit boundaries between two date/time values.
 This method returns a long.
 The string indicates the unit.
-The same units as in the EXTRACT function are supported.
-Only TIMEZONE_HOUR and TIMEZONE_MINUTE units use the time zone offset component.
-With all other units if date/time values have time zone offset component it is ignored.
+Only TIMEZONE_HOUR and TIMEZONE_MINUTE fields use the time zone offset component.
+With all other fields if date/time values have time zone offset component it is ignored.
 ","
 DATEDIFF('YEAR', T1.CREATED, T2.CREATED)
 "
@@ -3756,6 +3919,14 @@ Returns the day of the week (1 means Sunday).
 DAY_OF_WEEK(CREATED)
 "
 
+"Functions (Time and Date)","ISO_DAY_OF_WEEK","
+ISO_DAY_OF_WEEK(dateAndTime)
+","
+Returns the ISO day of the week (1 means Monday).
+","
+ISO_DAY_OF_WEEK(CREATED)
+"
+
 "Functions (Time and Date)","DAY_OF_YEAR","
 DAY_OF_YEAR(dateAndTime)
 ","
@@ -3765,16 +3936,11 @@ DAY_OF_YEAR(CREATED)
 "
 
 "Functions (Time and Date)","EXTRACT","
-EXTRACT ( { YEAR | YY | MONTH | MM | QUARTER | WEEK | ISO_WEEK
-    | DAY | DD | DAY_OF_YEAR | DOY
-    | HOUR | HH | MINUTE | MI | SECOND | SS | EPOCH
-    | MILLISECOND | MS | MICROSECOND | MCS | NANOSECOND | NS
-    | TIMEZONE_HOUR | TIMEZONE_MINUTE }
-    FROM dateAndTime )
+EXTRACT ( datetimeField FROM dateAndTime )
 ","
 Returns a value of the specific time unit from a date/time value.
-This method returns a numeric value with EPOCH unit and
-an int for all other time units.
+This method returns a numeric value with EPOCH field and
+an int for all other fields.
 ","
 EXTRACT(SECOND FROM CURRENT_TIMESTAMP)
 "
@@ -3869,7 +4035,7 @@ WEEK(CREATED)
 ISO_WEEK(dateAndTime)
 ","
 Returns the ISO week (1-53) from a date/time value.
-This method uses the ISO definition when
+This function uses the ISO definition when
 first week of year should have at least four days
 and week is started with Monday.
 ","

h2/src/docsrc/html/grammar.html

@@ -103,6 +103,34 @@ syntax-end -->
 </table>
 <!-- railroad-end -->
 
+<h3>Datetime fields</h3>
+<!-- syntax-start
+<p class="notranslate">
+<c:forEach var="item" items="datetimeFields">
+    <a href="#${item.link}">${item.topic}</a><br />
+</c:forEach>
+</p>
+syntax-end -->
+<!-- railroad-start -->
+<table class="notranslate index">
+    <tr>
+        <td class="index">
+            <c:forEach var="item" items="datetimeFields-0">
+                <a href="#${item.link}" >${item.topic}</a><br />
+            </c:forEach>
+        </td><td class="index">
+            <c:forEach var="item" items="datetimeFields-1">
+                <a href="#${item.link}" >${item.topic}</a><br />
+            </c:forEach>
+        </td><td class="index">
+            <c:forEach var="item" items="datetimeFields-2">
+                <a href="#${item.link}" >${item.topic}</a><br />
+            </c:forEach>
+        </td>
+    </tr>
+</table>
+<!-- railroad-end -->
+
 <h3>Other Grammar</h3>
 <!-- syntax-start
 <p class="notranslate">
@@ -163,6 +191,27 @@ syntax-end -->
 ${item.example}</p>
 </c:forEach>
 
+<c:forEach var="item" items="datetimeFields">
+<h3 id="${item.link}" class="notranslate" onclick="switchBnf(this)">${item.topic}</h3>
+<!-- railroad-start -->
+<pre name="bnf" style="display: none">
+${item.syntax}
+</pre>
+<div name="railroad">
+${item.railroad}
+</div>
+<!-- railroad-end -->
+<!-- syntax-start
+<pre>
+${item.syntax}
+</pre>
+syntax-end -->
+<p>${item.text}</p>
+<p>Example:</p>
+<p class="notranslate">
+${item.example}</p>
+</c:forEach>
+
 <c:forEach var="item" items="otherGrammar">
 <h3 id="${item.link}" class="notranslate" onclick="switchBnf(this)">${item.topic}</h3>
 <!-- railroad-start -->

h2/src/main/org/h2/expression/Function.java

@@ -188,6 +188,10 @@ public class Function extends Expression implements FunctionCall {
         DATE_PART.put("DD", DAY_OF_MONTH);
         DATE_PART.put("D", DAY_OF_MONTH);
         DATE_PART.put("SQL_TSI_DAY", DAY_OF_MONTH);
+        DATE_PART.put("DAY_OF_WEEK", DAY_OF_WEEK);
+        DATE_PART.put("DAYOFWEEK", DAY_OF_WEEK);
+        DATE_PART.put("DOW", DAY_OF_WEEK);
+        DATE_PART.put("ISO_DAY_OF_WEEK", ISO_DAY_OF_WEEK);
         DATE_PART.put("DAYOFYEAR", DAY_OF_YEAR);
         DATE_PART.put("DAY_OF_YEAR", DAY_OF_YEAR);
         DATE_PART.put("DY", DAY_OF_YEAR);
@@ -1898,6 +1902,7 @@ public class Function extends Expression implements FunctionCall {
             count *= 7;
             //$FALL-THROUGH$
         case DAY_OF_WEEK:
+        case ISO_DAY_OF_WEEK:
         case DAY_OF_MONTH:
         case DAY_OF_YEAR:
             if (!withDate) {
@@ -2012,6 +2017,8 @@ public class Function extends Expression implements FunctionCall {
             //$FALL-THROUGH$
         case DAY_OF_MONTH:
         case DAY_OF_YEAR:
+        case DAY_OF_WEEK:
+        case ISO_DAY_OF_WEEK:
             return absolute2 - absolute1;
         case WEEK:
             return weekdiff(absolute1, absolute2, 0);

h2/src/main/org/h2/util/IOUtils.java

@@ -38,7 +38,7 @@ public class IOUtils {
     /**
      * Close a Closeable without throwing an exception.
      *
-     * @param out the Closeablem or null
+     * @param out the Closeable or null
      */
     public static void closeSilently(Closeable out) {
         if (out != null) {

h2/src/main/org/h2/value/DataType.java

@@ -464,8 +464,8 @@ public class DataType {
         return dataType;
     }
 
-    private static DataType createDate(int maxPrecision, int precision, String prefix, boolean supportsScale, int scale,
-            int maxScale) {
+    private static DataType createDate(int maxPrecision, int precision, String prefix,
+            boolean supportsScale, int scale, int maxScale) {
         DataType dataType = new DataType();
         dataType.prefix = prefix + " '";
         dataType.suffix = "'";

h2/src/test/org/h2/test/scripts/information_schema.sql

@@ -66,7 +66,7 @@ SELECT * FROM INFORMATION_SCHEMA.REFERENTIAL_CONSTRAINTS LIMIT 0;
 > ------------------ ----------------- --------------- ------------------------- ------------------------ ---------------------- ------------ ----------- -----------
 > rows: 0
 
--- H2 may return name of the index istead of name of the referenced constraint as UNIQUE_CONSTRAINT_NAME
+-- H2 may return name of the index instead of name of the referenced constraint as UNIQUE_CONSTRAINT_NAME
 SELECT CONSTRAINT_NAME, SUBSTRING(UNIQUE_CONSTRAINT_NAME, 0, 11) AS UCN_PART, MATCH_OPTION, UPDATE_RULE, DELETE_RULE FROM INFORMATION_SCHEMA.REFERENTIAL_CONSTRAINTS
     WHERE CONSTRAINT_CATALOG = DATABASE() AND CONSTRAINT_SCHEMA = SCHEMA() AND UNIQUE_CONSTRAINT_CATALOG = DATABASE() AND UNIQUE_CONSTRAINT_SCHEMA = SCHEMA()
     ORDER BY CONSTRAINT_NAME, UNIQUE_CONSTRAINT_NAME;

h2/src/tools/org/h2/build/doc/GenerateDoc.java

@@ -78,6 +78,8 @@ public class GenerateDoc {
                 help + "= 'Commands (DDL)' ORDER BY ID", false);
         map("commandsOther",
                 help + "= 'Commands (Other)' ORDER BY ID", false);
+        map("datetimeFields",
+                help + "= 'Datetime fields' ORDER BY ID", true);
         map("otherGrammar",
                 help + "= 'Other Grammar' ORDER BY ID", true);
         map("functionsAggregate",

h2/src/tools/org/h2/build/doc/dictionary.txt

@@ -734,7 +734,7 @@ toto anatolii callables spurious disregard uniqueidentifier promoted oom doesnt
 optimisations roughly contractid succeeding tran fixme iters ovain orgid chosen
 arbonaut exposing obscure determined turkey buildings indexhints acct
 choosing optimise arte preparator katzyn bla jenkins tot artes pgserver npe
-suffers closeablem mni significance vise identiy vitalus aka ilike uppercasing reentrant
+suffers mni significance vise identiy vitalus aka ilike uppercasing reentrant
 aff ignite warm upstream producing sfu jit smtm affinity stashed tbl
 stumc numbered
 
@@ -765,4 +765,4 @@ jacoco xdata invokes sourcefiles classfiles duplication crypto stacktraces prt d
 interpolated thead
 
 die weekdiff osx subprocess dow proleptic microsecond microseconds divisible cmp denormalized suppressed saturated mcs
-london dfs weekdays intermittent looked msec tstz africa monrovia asia tokyo weekday joi callers
+london dfs weekdays intermittent looked msec tstz africa monrovia asia tokyo weekday joi callers multipliers ucn