Document HASH changes + add CRYPT_HASH example

src/docs/asciidoc/en/refdocs/fblangref40/_fblangref40-functions-scalar.adoc

@@ -1685,6 +1685,15 @@ The value `'ab'` in a `CHAR(5)` (3 trailing spaces) has a different hash than if
 To avoid this, make sure you always use a variable length data type, or the same fixed length data type, or normalize values before hashing, for example using <<fblangref40-scalarfuncs-trim,`TRIM(TRAILING FROM _value)`>>.
 ====
 
+[[fblangref40-scalarfuncs-crypthash-exmpl]]
+==== Examples of `CRYPT_HASH`
+
+.Hashing `x` with the SHA512 algorithm
+[source]
+----
+select crypt_hash(x using sha512) from y;
+----
+
 .See also
 <<fblangref40-scalarfuncs-hash>>
 
@@ -1695,12 +1704,14 @@ To avoid this, make sure you always use a variable length data type, or the same
 DSQL, PSQL
 
 .Result type
-`BIGINT`
+`INTEGER`,`BIGINT`
 
 .Syntax
 [listing,subs=+quotes]
 ----
-HASH (_string_)
+HASH (_value_ [USING <hash>])
+
+<hash> ::= CRC32
 ----
 
 [[fblangref40-funcs-tbl-hash]]
@@ -1710,13 +1721,54 @@ HASH (_string_)
 ^| Parameter
 ^| Description
 
-|string
-|An expression of a string type
+|value
+|Expression of value of any type;
+non-string or non-binary types are converted to string
+
+|hash
+|Non-cryptographic hash algorithm to apply
 |===
 
-Returns a hash value for the input string.
+`HASH` returns a hash value for the input argument.
+If the input argument is not a string or binary type, it is converted to string before hashing.
+
+The optional `USING` clause specifies the non-cryptographic hash algorithm to apply.
+When the `USING` clause is absent, the legacy PJW algorithm is applied;
+this is identical to its behaviour in previous Firebird versions.
+
 This function fully supports text ``BLOB``s of any length and character set.
 
+.Supported algorithms
+_not specified_::
+When no algorithm is specified, Firebird applies the 64-bit variant of the non-cryptographic https://en.wikipedia.org/wiki/PJW_hash_function[PJW hash function^] (also known as ELF64).
+This is a very fast algorithm for general purposes (hash tables, etc.), but its collision quality is sub-optimal.
+Other hash functions -- specified explicitly in the `USING` clause, or cryptographic hashes through <<fblangref40-scalarfuncs-crypthash>> -- should be used for more reliable hashing.
++
+The `HASH` function returns `BIGINT` for this algorithm
+
+`CRC32`::
+With `CRC32`, Firebird applies the CRC32 algorithm using the polynomial 0x04C11DB7.
++
+The `HASH` function returns `INTEGER` for this algorithm.
+
+[[fblangref40-scalarfuncs-hash-exmpl]]
+==== Examples of `HASH`
+
+. Hashing `x` with the CRC32 algorithm
++
+[source]
+----
+select hash(x using crc32) from y;
+----
+
+. Hashing `x` with the legacy PJW algorithm
++
+[source]
+----
+select hash(x) from y;
+----
+
+
 .See also
 <<fblangref40-scalarfuncs-crypthash>>
 
@@ -2888,7 +2940,6 @@ EXTRACT (<part> FROM <datetime>)
 |===
 
 Extracts and returns an element from a `DATE`, `TIME` or `TIMESTAMP` expression.
-This function was already added in InterBase 6, but not documented in the _Language Reference_ at the time.
 
 [[fblangref40-scalarfuncs-extract-types]]
 ==== Returned Data Types and Ranges