BigInt documentation

Author: d10c

docs/codeql/codeql-language-guides/extensible-predicates.rst

@@ -36,7 +36,7 @@ An extensible predicate is a CodeQL predicate with the following restrictions:
 
 - It uses the ``extensible`` keyword.
 - It has no body.
-- All predicate parameters have primitive types.
+- All predicate parameters have type ``string``, ``int``, ``float``, ``boolean``, or ``date``.
 - It is not in a module.
 
 Columns shared by all extensible predicates

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

@@ -424,3 +424,30 @@ The above query therefore evalutes to:
 +----+----+
 | 4  | 4  |
 +----+----+
+
+.. index:: BigInt
+.. _bigint:
+
+BigInt
+======
+
+The built-in ``QlBuiltins`` module provides an **experimental** type ``BigInt`` of arbitrary-precision integers.
+
+This type is not available in the CodeQL CLI by default, but you can enable it by passing the ``--allow-experimental=bigint``
+option to the CodeQL CLI. Consequently, BigInts are currently disallowed in query results and dbscheme columns.
+
+Unlike ``int`` and ``float``, there is no automatic conversion between ``BigInt`` and other numeric types.
+Instead, big integers can be constructed using the ``.toBigInt()`` methods of ``int`` and ``string``.
+
+The other built-in operations are:
+
+*   comparisons between ``BigInt``\s: ``=``, ``!=``, ``<``, ``<=``, ``>``, ``>=``,
+*   conversions from ``BigInt``\s to strings or integers (if within range): ``.toString()``, ``.toInt()``,
+*   ``BigInt`` arithmetic: binary ``+``, ``-``, ``*``, ``/``, ``%``, unary ``-``,
+*   bitwise operations: ``.bitAnd(BigInt)``, ``.bitOr(BigInt)``,
+    ``.bitXor(BigInt)``, ``.bitShiftLeft(int)``, ``.bitShiftRightSigned(int)``,
+    ``.bitNot()``,
+*   aggregates: ``min``, ``max``, (``strict``)\ ``sum``, (``strict``)\ ``count``, ``avg``,
+    ``rank``, ``unique``, ``any``.
+*   other: ``.pow(int)``, ``.abs()``, ``.gcd(BigInt)``, ``.minimum(BigInt)``,
+    ``.maximum(BigInt)``.

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

@@ -359,7 +359,7 @@ Kinds of types
 
 Types in QL are either *primitive* types, *database* types, *class* types, *character* types, *class domain* types, type *parameters*, or *instantiation-nested* types.
 
-The primitive types are ``boolean``, ``date``, ``float``, ``int``, and ``string``.
+The primitive types are ``boolean``, ``date``, ``float``, ``int``, ``string``, and ``QlBuiltins::BigInt``.
 
 Database types are supplied as part of the database. Each database type has a *name*, which is an identifier starting with an at sign (``@``, U+0040) followed by lower-case letter. Database types have some number of *base types*, which are other database types. In a valid database, the base types relation is non-cyclic.
 
@@ -433,7 +433,7 @@ Values are the fundamental data that QL programs compute over. This section spec
 Kinds of values
 ~~~~~~~~~~~~~~~
 
-There are six kinds of values in QL: one kind for each of the five primitive types, and *entities*. Each value has a type.
+There are seven kinds of values in QL: one kind for each of the six primitive types, and *entities*. Each value has a type.
 
 A boolean value is of type ``boolean``, and may have one of two distinct values: ``true`` or ``false``.
 
@@ -445,6 +445,8 @@ An integer value is of type ``int``. Each value is a 32-bit two's complement int
 
 A string is a finite sequence of 16-bit characters. The characters are interpreted as Unicode code points.
 
+A :ref:`big integer <bigint>` value is of type ``QlBuiltins::BigInt``. Each value is a signed arbitrary-precision integer.
+
 The database includes a number of opaque entity values. Each such value has a type that is one of the database types, and an identifying integer. An entity value is written as the name of its database type followed by its identifying integer in parentheses. For example, ``@tree(12)``, ``@person(16)``, and ``@location(38132)`` are entity values. The identifying integers are left opaque to programmers in this specification, so an implementation of QL is free to use some other set of countable labels to identify its entities.
 
 Ordering
@@ -458,7 +460,7 @@ For dates, the ordering is chronological.
 
 For floats, the ordering is as specified in IEEE 754 when one exists, except that NaN is considered equal to itself and is ordered after all other floats, and negative zero is considered to be strictly less than positive zero.
 
-For integers, the ordering is as for two's complement integers.
+For integers (and :ref:`big integers <bigint>`), the ordering is numerical.
 
 For strings, the ordering is lexicographic.
 

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

@@ -52,6 +52,8 @@ independent of the database that you are querying.
 QL has a range of built-in operations defined on primitive types. These are available by using dispatch on expressions of the appropriate type. For example, ``1.toString()`` is the string representation of the integer constant ``1``. For a full list of built-in operations available in QL, see the
 section on `built-ins <https://codeql.github.com/docs/ql-language-reference/ql-language-specification/#built-ins>`__ in the QL language specification.
 
+Additionally, there is an experimental arbitrary-precision integer primitive type at :ref:`QlBuiltins::BigInt <bigint>`. This type is not available in the CodeQL CLI by default, but you can enable it by passing the ``--allow-experimental=bigint`` option to the CodeQL CLI.
+
 .. index:: class
 .. _classes: