Add endianness to int converter functions.

Add `std::Endian` enum with two values `big` and `little`.

Update the bytes <-> int converter functions with a required `Endian`
parameter.

Update the docs to reflect these changes.

docs/stdlib/bytes.rst

@@ -12,6 +12,9 @@ Bytes
     * - :eql:type:`bytes`
       - Byte sequence
 
+    * - :eql:type:`Endian`
+      - An enum for indicating integer value encoding.
+
     * - :eql:op:`bytes[i] <bytesidx>`
       - :eql:op-desc:`bytesidx`
 
@@ -98,6 +101,36 @@ Bytes
         db> select <bytes>to_json("\"SGVsbG8gRWRnZURCIQ==\"");
         {b'Hello EdgeDB!'}
 
+
+----------
+
+
+.. eql:type:: std::Endian
+
+    .. versionadded:: 5.0
+
+    An enum for indicating integer value encoding.
+
+    This enum is used by the :eql:func:`to_int16`, :eql:func:`to_int32`,
+    :eql:func:`to_int64` and the :eql:func:`to_bytes` converters working with
+    :eql:type:`bytes` and integers.
+
+    ``Endian.Big`` stands for big-endian encoding going from most significant
+    byte to least. ``Endian.Little`` stands for little-endian encoding going
+    from least to most significant byte.
+
+    .. code-block:: edgeql-repl
+
+        db> select to_bytes(<int32>16908295, Endian.Big);
+        {b'\x01\x02\x00\x07'}
+        db> select to_int32(b'\x01\x02\x00\x07', Endian.Big);
+        {16908295}
+        db> select to_bytes(<int32>16908295, Endian.Little);
+        {b'\x07\x00\x02\x01'}
+        db> select to_int32(b'\x07\x00\x02\x01', Endian.Little);
+        {16908295}
+
+
 ----------
 
 
@@ -148,10 +181,9 @@ Bytes
 ---------
 
 .. eql:function:: std::to_bytes(s: str) -> bytes
-                  std::to_bytes(val: int16) -> bytes
-                  std::to_bytes(val: int32) -> bytes
-                  std::to_bytes(val: int64) -> bytes
-                  std::to_bytes(val: int64) -> bytes
+                  std::to_bytes(val: int16, endian: Endian) -> bytes
+                  std::to_bytes(val: int32, endian: Endian) -> bytes
+                  std::to_bytes(val: int64, endian: Endian) -> bytes
                   std::to_bytes(val: uuid) -> bytes
 
     :index: encode stringencoder
@@ -167,18 +199,24 @@ Bytes
         db> select to_bytes('テキスト');
         {b'\xe3\x83\x86\xe3\x82\xad\xe3\x82\xb9\xe3\x83\x88'}
 
-    The integer values are encoded as big-endian (most significant bit comes
-    first) byte strings:
+    The integer values can be encoded as big-endian (most significant bit
+    comes first) byte strings:
 
     .. code-block:: edgeql-repl
 
-        db> select to_bytes(<int16>31);
+        db> select to_bytes(<int16>31, Endian.Big);
         {b'\x00\x1f'}
-        db> select to_bytes(<int32>31);
+        db> select to_bytes(<int32>31, Endian.Big);
         {b'\x00\x00\x00\x1f'}
-        db> select to_bytes(123456789123456789);
+        db> select to_bytes(123456789123456789, Endian.Big);
         {b'\x01\xb6\x9bK\xac\xd0_\x15'}
 
+    .. note::
+
+        Due to underlying implementation details using big-endian encoding
+        results in slightly faster performance of ``to_bytes`` when converting
+        integers.
+
     The UUID values are converted to the underlying string of 16 bytes:
 
     .. code-block:: edgeql-repl

docs/stdlib/numbers.rst

@@ -135,7 +135,8 @@ between all numeric types. All numeric types can also be cast to and
 from :eql:type:`str` and :eql:type:`json`.
 
 
-----------
+Definitions
+-----------
 
 
 .. eql:type:: std::int16
@@ -814,7 +815,7 @@ from :eql:type:`str` and :eql:type:`json`.
 
 
 .. eql:function:: std::to_int16(s: str, fmt: optional str={}) -> int16
-                  std::to_int16(val: bytes) -> int16
+                  std::to_int16(val: bytes, endian: Endian) -> int16
 
     :index: parse int16
 
@@ -831,20 +832,27 @@ from :eql:type:`str` and :eql:type:`json`.
         db> select to_int16('23%', '99%');
         {23}
 
-    The bytes conversion function expects exactly 2 bytes using big-endian
-    representation.
+    The bytes conversion function expects exactly 2 bytes with specified
+    endianness.
 
     .. code-block:: edgeql-repl
 
-        db> select to_int16(b'\x00\x07');
+        db> select to_int16(b'\x00\x07', Endian.Big);
+        {7}
+        db> select to_int16(b'\x07\x00', Endian.Little);
         {7}
 
+    .. note::
+
+        Due to underlying implementation details using big-endian encoding
+        results in slightly faster performance of ``to_int16``.
+
 
 ------------
 
 
 .. eql:function:: std::to_int32(s: str, fmt: optional str={}) -> int32
-                  std::to_int32(val: bytes) -> int32
+                  std::to_int32(val: bytes, endian: Endian) -> int32
 
     :index: parse int32
 
@@ -861,20 +869,27 @@ from :eql:type:`str` and :eql:type:`json`.
         db> select to_int32('1000023%', '9999999%');
         {1000023}
 
-    The bytes conversion function expects exactly 4 bytes using big-endian
-    representation.
+    The bytes conversion function expects exactly 4 bytes with specified
+    endianness.
 
     .. code-block:: edgeql-repl
 
-        db> select to_int32(b'\x01\x02\x00\x07');
+        db> select to_int32(b'\x01\x02\x00\x07', Endian.Big);
+        {16908295}
+        db> select to_int32(b'\x07\x00\x02\x01', Endian.Little);
         {16908295}
 
+    .. note::
+
+        Due to underlying implementation details using big-endian encoding
+        results in slightly faster performance of ``to_int32``.
+
 
 ------------
 
 
 .. eql:function:: std::to_int64(s: str, fmt: optional str={}) -> int64
-                  std::to_int64(val: bytes) -> int64
+                  std::to_int64(val: bytes, endian: Endian) -> int64
 
     :index: parse int64
 
@@ -891,14 +906,23 @@ from :eql:type:`str` and :eql:type:`json`.
         db> select to_int64('10000234567%', '99999999999%');
         {10000234567}
 
-    The bytes conversion function expects exactly 8 bytes using big-endian
-    representation.
+    The bytes conversion function expects exactly 8 bytes with specified
+    endianness.
 
     .. code-block:: edgeql-repl
 
-        db> select to_int64(b'\x01\x02\x00\x07\x11\x22\x33\x44');
+        db> select to_int64(b'\x01\x02\x00\x07\x11\x22\x33\x44',
+        ...                 Endian.Big);
+        {72620574343574340}
+        db> select to_int64(b'\x44\x33\x22\x11\x07\x00\x02\x01',
+        ...                 Endian.Little);
         {72620574343574340}
 
+    .. note::
+
+        Due to underlying implementation details using big-endian encoding
+        results in slightly faster performance of ``to_int64``.
+
 
 ------------
 

edb/buildmeta.py

@@ -44,7 +44,7 @@
 
 
 # Increment this whenever the database layout or stdlib changes.
-EDGEDB_CATALOG_VERSION = 2024_02_16_14_00
+EDGEDB_CATALOG_VERSION = 2024_02_20_00_00
 EDGEDB_MAJOR_VERSION = 5