Merge pull request github#18610 from jbj/bigint-language-reference

QL reference: more BigInt updates

Author: jbj

docs/codeql/ql-language-reference/expressions.rst

@@ -194,7 +194,7 @@ the **aggregation variables**.
 
 Ordered aggregates (namely ``min``, ``max``, ``rank``, ``concat``, and ``strictconcat``) are
 ordered by their ``<expression>`` values by default. The ordering is either numeric (for 
-integers and floating point numbers) or lexicographic (for strings). Lexicographic ordering is
+numeric types) or lexicographic (for strings). Lexicographic ordering is
 based on the `Unicode value <https://en.wikipedia.org/wiki/List_of_Unicode_characters#Basic_Latin>`_
 of each character.
 
@@ -684,7 +684,7 @@ Unary operations
 ****************
 
 A unary operation is a minus sign (``-``) or a plus sign (``+``) followed by an expression of type
-``int`` or ``float``. For example:
+``int``, ``float`` or ``QlBuiltins::BigInt``. For example:
 
 .. code-block:: ql
 
@@ -731,10 +731,11 @@ You can use the following binary operators in QL:
 +------------------------+--------+
 
 If both expressions are numbers, these operators act as standard arithmetic operators. For 
-example, ``10.6 - 3.2`` has value ``7.4``, ``123.456 * 0`` has value ``0``, and ``9 % 4`` has 
+example, ``10.6 - 3.2`` has value ``7.4``, ``123.456 * 0`` has value ``0.0``, and ``9 % 4`` has 
 value ``1`` (the remainder after dividing ``9`` by ``4``).
-If both operands are integers, then the result is an integer. Otherwise the result is a 
-floating-point number.
+If both operands are subtypes of ``int`` or ``QlBuiltins::BigInt``, then the result type is
+``int`` or ``QlBuiltins::BigInt``, respectively. Otherwise, if both operands are subtypes of
+``float``, then the result type is ``float``.
 
 You can also use ``+`` as a string concatenation operator. In this case, at least one of the 
 expressions must be a string—the other expression is implicitly converted to a string using the

docs/codeql/ql-language-reference/name-resolution.rst

@@ -305,6 +305,7 @@ were defined in the :ref:`QL tutorials <ql-tutorials>`:
 The module namespace of ``Villagers`` has entries for: 
     - The module ``S``.
     - Any modules exported by ``tutorial``.
+    - The built-in top-level module ``QlBuiltins``.
 
 The module namespace of ``S`` also has entries for the module ``S`` itself, and for any 
 modules exported by ``tutorial``.
@@ -314,7 +315,7 @@ modules exported by ``tutorial``.
 The type namespace of ``Villagers`` has entries for:
     - The class ``Child``.
     - The types exported by the module ``tutorial``.
-    - The built-in types, namely ``int``, ``float``, ``string``, ``date``, and ``boolean``.
+    - The built-in top-level types, namely ``int``, ``float``, ``string``, ``date``, and ``boolean``.
 
 The type namespace of ``S`` has entries for:
     - All the above types.

docs/codeql/ql-language-reference/ql-language-specification.rst

@@ -718,7 +718,7 @@ An integer literal is a possibly negated sequence of decimal digits (``0`` throu
 Float literals (float)
 ~~~~~~~~~~~~~~~~~~~~~~
 
-A floating-point literals is a possibly negated two non-negative integers literals separated by a dot (``.``, U+002E). Here are some examples of float literals:
+A floating-point literal is a possibly negated pair of non-negative integer literals separated by a dot (``.``, U+002E). Here are some examples of float literals:
 
 ::
 
@@ -1243,7 +1243,7 @@ A unary operation is the application of ``+`` or ``-`` to another expression:
 
 The ``+`` or ``-`` in the operation is called the *operator*, and the expression is called the *operand*. The typing environment of the operand is the same as for the unary operation.
 
-For a valid unary operation, the operand must be of type ``int`` or ``float``. The operation has the same type as its operand.
+For a valid unary operation, the operand must be of type ``int``, ``float`` or ``QlBuiltins::BigInt``. The operation has the same type as its operand.
 
 If the operator is ``+``, then the values of the expression are the same as the values of the operand. If the operator is ``-``, then the values of the expression are the arithmetic negations of the values of the operand.
 
@@ -1260,9 +1260,9 @@ A binary operation is written as a *left operand* followed by a *binary operator
          |   expr "/" expr
          |   expr "%" expr
 
-The typing environment for the two environments is the same as for the operation. If the operator is ``+``, then either both operands must be subtypes of ``int`` or ``float``, or at least one operand must be a subtype of ``string``. If the operator is anything else, then each operand must be a subtype of ``int`` or ``float``.
+The typing environment for the two environments is the same as for the operation. If the operator is ``+``, then either both operands must be subtypes of one of ``int``, ``float`` or ``QlBuiltins::BigInt``, or at least one operand must be a subtype of ``string``. If the operator is anything else, then both operands must be subtypes of one of ``int``, ``float`` or ``QlBuiltins::BigInt``.
 
-The type of the operation is ``string`` if either operand is a subtype of ``string``. Otherwise, the type of the operation is ``int`` if both operands are subtypes of ``int``. Otherwise, the type of the operation is ``float``.
+The type of the operation is ``string`` if either operand is a subtype of ``string``. Otherwise, the type of the operation is ``int`` or ``QlBuiltins::BigInt`` if both operands are subtypes of ``int`` or ``QlBuiltins::BigInt``, respectively. Otherwise, the type of the operation is ``float``.
 
 If the result is of type ``string``, then the *left values* of the operation are the values of a "call with results" expression with the left operand as the receiver, ``toString`` as the predicate name, and no arguments (see "`Calls with results <#calls-with-results>`__"). Otherwise the left values are the values of the left operand. Likewise, the *right values* are either the values from calling ``toString`` on the right operand, or the values of the right operand as it is.
 
@@ -1272,6 +1272,8 @@ The binary operation has one value for each combination of a left value and a ri
 
 -  Otherwise, if both operand types are subtypes of ``int``, then the value of the operation is the result of applying the two's-complement 32-bit integer operation corresponding to the QL binary operator.
 
+-  Otherwise, if both operand types are subtypes of ``QlBuiltins::BigInt``, then the value of the operation is the result of applying the arbitrary-range integer operation corresponding to the QL binary operator.
+
 -  Otherwise, both operand types must be subtypes of ``float``. If either operand is of type ``int`` then they are converted to a float. The value of the operation is then the result of applying the IEEE 754 floating-point operator that corresponds to the QL binary operator: addition for ``+``, subtraction for ``-``, multiplication for ``*``, division for ``/``, or remainder for ``%``.
 
 Variables
@@ -1443,10 +1445,10 @@ The number and types of the aggregation expressions are restricted as follows:
 -  A ``max``, ``min``, ``rank`` or ``unique`` aggregation must have a single expression.
 -  The type of the expression in a ``max``, ``min`` or ``rank`` aggregation without an ordering directive expression must be an orderable type.
 -  A ``count`` or ``strictcount`` aggregation must not have an expression.
--  A ``sum``, ``strictsum`` or ``avg`` aggregation must have a single aggregation expression, which must have a type which is a subtype of ``float``.
+-  A ``sum``, ``strictsum`` or ``avg`` aggregation must have a single aggregation expression, which must have a type which is a subtype of ``float`` or ``QlBuiltins::BigInt``.
 -  A ``concat`` or ``strictconcat`` aggregation must have two expressions. Both expressions must have types which are subtypes of ``string``.
 
-The type of a ``count``, ``strictcount`` aggregation is ``int``. The type of an ``avg`` aggregation is ``float``. The type of a ``concat`` or ``strictconcat`` aggregation is ``string``. The type of a ``sum`` or ``strictsum`` aggregation is ``int`` if the aggregation expression is a subtype of ``int``, otherwise it is ``float``. The type of a ``rank``, ``min`` or ``max`` aggregation is the type of the single expression.
+The type of a ``count``, ``strictcount`` aggregation is ``int``. The type of an ``avg`` aggregation is ``float``. The type of a ``concat`` or ``strictconcat`` aggregation is ``string``. The type of a ``sum`` or ``strictsum`` aggregation is ``int`` if the aggregation expression is a subtype of ``int``; otherwise it is ``QlBuiltins::BigInt`` if the aggregation expression is a subtype of ``QlBuiltins::BigInt``; otherwise it is ``float``. The type of a ``rank``, ``min`` or ``max`` aggregation is the type of the single expression.
 
 An ordering directive may only be specified for a ``max``, ``min``, ``rank``, ``concat`` or ``strictconcat`` aggregation. The type of the expression in an ordering directive must be an orderable type.
 
@@ -1462,7 +1464,7 @@ If the aggregation id is ``max``, ``min`` or ``rank`` and there was no ordering
 
 The values of the aggregation expression are given by applying the aggregation function to each set of tuples obtained by picking exactly one aggregation tuple for each range tuple.
 
--  If the aggregation id is ``avg``, and the set is non-empty, then the resulting value is the average of the value for the aggregation variable in each tuple in the set, weighted by the number of tuples in the set, after converting the value to a floating-point number.
+-  If the aggregation id is ``avg``, and the set is non-empty, then the resulting value is the average of the value for the aggregation variable in each tuple in the set, weighted by the number of tuples in the set, after converting the value to its appropriate base type of ``float`` or ``QlBuiltins::BigInt``, then converting the final result to ``float``.
 
 -  If the aggregation id is ``count``, then the resulting value is the number of tuples in the set. If there are no tuples in the set, then the value is the integer ``0``.