Merge pull request #1488 from katzyn/docs

Improve documentation of window and some other functions

h2/src/docsrc/help/help.csv

@@ -2564,6 +2564,18 @@ W1
 [windowFrame])
 ","
 A window specification for a window, window function or aggregate.
+
+If name of an existing window is specified its clauses are used by default.
+
+Optional window partition clause separates rows into independent partitions.
+Each partition is processed separately.
+If this clause is not present there is one implicit partition with all rows.
+
+Optional window order clause specifies order of rows in the partition.
+If some rows have the same order position they are considered as a group of rows in optional window frame clause.
+
+Optional window frame clause specifies which rows are processed by a window function,
+see its documentation for a more details.
 ","
 ()
 (W1 ORDER BY ID)
@@ -2579,8 +2591,33 @@ ROWS|RANGE|GROUP
 ","
 A window frame clause.
 May be specified only for aggregates and FIRST_VALUE(), LAST_VALUE(), and NTH_VALUE() window functions.
+
+If this clause is not specified for an aggregate or window function that supports this clause
+the default window frame depends on window order clause.
+If window order clause is also not specified
+the default window frame contains all the rows in the partition.
+If window order clause is specified
+the default window frame contains all preceding rows and all rows from the current group.
+
+Window frame unit determines how rows or groups of rows are selected and counted.
+If ROWS is specified rows are not grouped in any way and relative numbers of rows are used in bounds.
+If RANGE is specified rows are grouped according window order clause,
+preceding and following values mean the difference between value in the current row and in the target rows,
+and CURRENT ROW in bound specification means current group of rows.
+If GROUPS is specified rows are grouped according window order clause,
+preceding and following values means relative number of groups of rows,
+and CURRENT ROW in bound specification means current group of rows.
+
+If only window frame preceding clause is specified it is treated as
+BETWEEN windowFramePreceding AND CURRENT ROW
+
+Optional window frame exclusion clause specifies rows that should be excluded from the frame.
+EXCLUDE CURRENT ROW excludes only the current row regardless the window frame unit.
+EXCLUDE GROUP excludes the whole current group of rows, including the current row.
+EXCLUDE TIES excludes the current group of rows, but not the current row.
+EXCLUDE NO OTHERS is default and it does not exclude anything.
 ","
-RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW EXCLUDE GROUP
+ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW EXCLUDE TIES
 "
 
 "Other Grammar","Window frame preceding","
@@ -3567,11 +3604,17 @@ ENVELOPE(X)
 "
 
 "Functions (Numeric)","ABS","
-ABS ( { numeric } )
+ABS (numeric|interval)
 ","
-See also Java ""Math.abs"".
-Please note that ""Math.abs(Integer.MIN_VALUE) == Integer.MIN_VALUE"" and ""Math.abs(Long.MIN_VALUE) == Long.MIN_VALUE"".
+Returns the absolute value of a specified value.
 The returned value is of the same data type as the parameter.
+
+Note that TINYINT, SMALLINT, INT, and BIGINT data types cannot represent absolute values
+of their minimum negative values, because they have more negative values than positive.
+For example, for INT data type allowed values are from -2147483648 to 2147483647.
+ABS(-2147483648) should be 2147483648, but this value is not allowed for this data type.
+It leads to an exception.
+To avoid it cast argument of this function to a higher data type.
 ","
 ABS(ID)
 "
@@ -3773,21 +3816,21 @@ This method returns a double.
 FLOOR(A)
 "
 
-"Functions (Numeric)","LOG","
-{ LOG | LN } (numeric)
+"Functions (Numeric)","LN","
+{LN|LOG}(numeric)
 ","
-See also Java ""Math.log"".
+Calculates the natural (base e) logarithm as a double value.
 In the PostgreSQL mode, LOG(x) is base 10.
-This method returns a double.
+See also Java ""Math.log"".
 ","
-LOG(A)
+LN(A)
 "
 
 "Functions (Numeric)","LOG10","
 LOG10(numeric)
 ","
+Calculates the base 10 logarithm as a double value.
 See also Java ""Math.log10"".
-This method returns a double.
 ","
 LOG10(A)
 "
@@ -4051,7 +4094,11 @@ CONCAT_WS(',', NAME, '!')
 DIFFERENCE(string, string)
 ","
 Returns the difference between the sounds of two strings.
-This method returns an int.
+The difference is calculated as a number of matched characters
+in the same positions in SOUNDEX representations of arguments.
+This method returns an int between 0 and 4 inclusive, or null if any of its parameters is null.
+Note that value of 0 means that strings are not similar to each other.
+Value of 4 means that strings are fully similar to each other (have the same SOUNDEX representation).
 ","
 DIFFERENCE(T1.NAME, T2.NAME)
 "
@@ -4263,8 +4310,8 @@ REPLACE(NAME, ' ')
 SOUNDEX(string)
 ","
 Returns a four character code representing the sound of a string.
-See also http://www.archives.gov/genealogy/census/soundex.html .
-This method returns a string.
+This method returns a string, or null if parameter is null.
+See https://en.wikipedia.org/wiki/Soundex for more information.
 ","
 SOUNDEX(NAME)
 "
@@ -4476,7 +4523,7 @@ The datetimeField indicates the unit.
 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)
+DATEDIFF(YEAR, T1.CREATED, T2.CREATED)
 "
 
 "Functions (Time and Date)","DAYNAME","
@@ -5131,6 +5178,7 @@ H2VERSION()
 ROW_NUMBER() OVER windowNameOrSpecification
 ","
 Returns the number of the current row starting with 1.
+Window frame clause is not allowed for this function.
 
 Window functions are currently experimental in H2 and should be used with caution.
 They also may require a lot of memory for large queries.
@@ -5147,6 +5195,8 @@ Returns the rank of the current row.
 The rank of a row is the number of rows that precede this row plus 1.
 If two or more rows have the same values in ORDER BY columns, these rows get the same rank from the first row with the same values.
 It means that gaps in ranks are possible.
+This function requires window order clause.
+Window frame clause is not allowed for this function.
 
 Window functions are currently experimental in H2 and should be used with caution.
 They also may require a lot of memory for large queries.
@@ -5162,6 +5212,8 @@ Returns the dense rank of the current row.
 The rank of a row is the number of groups of rows with the same values in ORDER BY columns that precede group with this row plus 1.
 If two or more rows have the same values in ORDER BY columns, these rows get the same rank.
 Gaps in ranks are not possible.
+This function requires window order clause.
+Window frame clause is not allowed for this function.
 
 Window functions are currently experimental in H2 and should be used with caution.
 They also may require a lot of memory for large queries.
@@ -5176,6 +5228,7 @@ PERCENT_RANK() OVER windowNameOrSpecification
 Returns the relative rank of the current row.
 The relative rank is calculated as (RANK - 1) / (NR - 1),
 where RANK is a rank of the row and NR is a number of rows in window partition with this row.
+Window frame clause is not allowed for this function.
 
 Window functions are currently experimental in H2 and should be used with caution.
 They also may require a lot of memory for large queries.
@@ -5191,6 +5244,7 @@ Returns the relative rank of the current row.
 The relative rank is calculated as NP / NR
 where NP is a number of rows that precede the current row or have the same values in ORDER BY columns
 and NR is a number of rows in window partition with this row.
+Window frame clause is not allowed for this function.
 
 Window functions are currently experimental in H2 and should be used with caution.
 They also may require a lot of memory for large queries.
@@ -5207,6 +5261,8 @@ Number of groups should be a positive integer value.
 NTILE returns the 1-based number of the group to which the current row belongs.
 First groups will have more rows if number of rows is not divisible by number of groups.
 For example, if 5 rows are distributed into 2 groups this function returns 1 for the first 3 row and 2 for the last 2 rows.
+This function requires window order clause.
+Window frame clause is not allowed for this function.
 
 Window functions are currently experimental in H2 and should be used with caution.
 They also may require a lot of memory for large queries.
@@ -5225,6 +5281,8 @@ If IGNORE NULLS is specified rows with null values in selected expression are sk
 If number of considered rows is less than specified relative number this function returns NULL
 or the specified default value, if any.
 If offset is 0 the value from the current row is returned unconditionally.
+This function requires window order clause.
+Window frame clause is not allowed for this function.
 
 Window functions are currently experimental in H2 and should be used with caution.
 They also may require a lot of memory for large queries.
@@ -5245,6 +5303,8 @@ If IGNORE NULLS is specified rows with null values in selected expression are sk
 If number of considered rows is less than specified relative number this function returns NULL
 or the specified default value, if any.
 If offset is 0 the value from the current row is returned unconditionally.
+This function requires window order clause.
+Window frame clause is not allowed for this function.
 
 Window functions are currently experimental in H2 and should be used with caution.
 They also may require a lot of memory for large queries.
@@ -5276,7 +5336,8 @@ OVER windowNameOrSpecification
 Returns the last value in a window.
 If IGNORE NULLS is specified null values are skipped and the function returns last non-null value before them, if any;
 if there is no non-null value it returns NULL.
-Note that the last value is actually a value in the current row if window frame is not specified.
+Note that the last value is actually a value in the current group of rows
+if window order clause is specified and window frame clause is not specified.
 
 Window functions are currently experimental in H2 and should be used with caution.
 They also may require a lot of memory for large queries.
@@ -5297,7 +5358,8 @@ Relative row number must be positive.
 If FROM LAST is specified rows a counted backwards from the last row.
 If IGNORE NULLS is specified rows with null values in selected expression are skipped.
 If number of considered rows is less than specified relative number this function returns NULL.
-Note that the last row is actually a current row if window frame is not specified.
+Note that the last row is actually a last row in the current group of rows
+if window order clause is specified and window frame clause is not specified.
 
 Window functions are currently experimental in H2 and should be used with caution.
 They also may require a lot of memory for large queries.

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

@@ -230,12 +230,7 @@ public class ValueTime extends Value {
 
     @Override
     public int getSignum() {
-        return Long.signum(nanos);
-    }
-
-    @Override
-    public Value negate() {
-        return ValueTime.fromNanos(-nanos);
+        return (int) (-nanos >>> 63);
     }
 
 }

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

@@ -178,6 +178,7 @@ public class GenerateDoc {
                     text = StringUtils.replaceAll(text,
                             "<br />", " ");
                     text = addCode(text);
+                    text = addLinks(text);
                     map.put("text", text);
                 }
 
@@ -254,4 +255,42 @@ public class GenerateDoc {
         s = StringUtils.replaceAll(s, "<code>GB</code>", "GB");
         return s;
     }
+
+    private static String addLinks(String text) {
+        int start = nextLink(text, 0);
+        if (start < 0) {
+            return text;
+        }
+        StringBuilder buff = new StringBuilder(text.length());
+        int len = text.length();
+        int offset = 0;
+        do {
+            int end = start + 7;
+            for (; end < len && !Character.isWhitespace(text.charAt(end)); end++) {
+                // Nothing to do
+            }
+            buff.append(text, offset, start) //
+                    .append("<a href=\"").append(text, start, end).append("\">") //
+                    .append(text, start, end) //
+                    .append("</a>");
+            offset = end;
+        } while ((start = nextLink(text, offset)) >= 0);
+        return buff.append(text, offset, len).toString();
+    }
+
+    private static int nextLink(String text, int i) {
+        int found = -1;
+        found = findLink(text, i, "http://", found);
+        found = findLink(text, i, "https://", found);
+        return found;
+    }
+
+    private static int findLink(String text, int offset, String prefix, int found) {
+        int idx = text.indexOf(prefix, offset);
+        if (idx >= 0 && (found < 0 || idx < found)) {
+            found = idx;
+        }
+        return found;
+    }
+
 }

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

@@ -797,6 +797,6 @@ xym normalizes coord setz xyzm geometrycollection multipolygon mixup rings polyg
 pointzm pointz pointm dimensionality redefine forum measures
 mpg casted pzm mls constrained subtypes complains
 ranks rno dro rko precede cume reopens preceding unbounded rightly itr lag maximal tiles tile ntile signify
-partitioned tri
+partitioned tri partitions
 
-discard enhancements nolock
+discard enhancements nolock surefire logarithm