Skip to content

Commit 52ccc2f

Browse files
pgulutzanpgulutzan
committed
Fixes gh-870 Document decimal field type.
1 parent 90186ad commit 52ccc2f

File tree

5 files changed

+94
-31
lines changed

5 files changed

+94
-31
lines changed

‎doc/2.2/book/box/box_schema.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -610,6 +610,10 @@ Below is a list of all ``box.schema`` functions.
610610

611611
:return: nil
612612

613+
These functions can be called with :samp:`{function-object}:call({arguments})`; however,
614+
unlike the case with ordinary functions, array arguments will not be correctly recognized
615+
unless they are enclosed in braces.
616+
613617
**Example:**
614618

615619
.. code-block:: lua

‎doc/2.2/book/box/box_space.rst

Lines changed: 68 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -309,6 +309,7 @@ Below is a list of all ``box.space`` functions and members.
309309
| parts | field-numbers + types | {field_no, ``'unsigned'`` or | ``{1, 'unsigned'}`` |
310310
| | | ``'string'`` or ``'integer'`` or | |
311311
| | | ``'number'`` or ``'boolean'`` or | |
312+
| | | ``'decimal'`` or | |
312313
| | | ``'varbinary'`` or | |
313314
| | | ``'array'`` or ``'scalar'``, | |
314315
| | | and optional collation or | |
@@ -375,8 +376,8 @@ Below is a list of all ``box.space`` functions and members.
375376

376377
**Details about index field types:**
377378

378-
The eight index field types (unsigned | string | integer | number |
379-
boolean | varbinary | array | scalar) differ depending on what values are allowed, and
379+
The nine index field types (unsigned | string | integer | number |
380+
boolean | decimal | varbinary | array | scalar) differ depending on what values are allowed, and
380381
what index types are allowed.
381382

382383
* **unsigned**: unsigned integers between 0 and 18446744073709551615,
@@ -392,10 +393,13 @@ Below is a list of all ``box.space`` functions and members.
392393
vinyl TREE indexes.
393394
* **number**: integers between -9223372036854775808 and 18446744073709551615,
394395
single-precision floating point numbers, or double-precision floating
395-
point numbers. Legal in memtx TREE or HASH indexes, and in vinyl TREE
396+
point numbers, or exact numbers. Legal in memtx TREE or HASH indexes, and in vinyl TREE
396397
indexes.
397398
* **boolean**: true or false. Legal in memtx TREE or HASH indexes, and in
398399
vinyl TREE indexes.
400+
* **decimal**: exact number returned from a function in the
401+
:ref:`decimal <decimal>` module. Legal in memtx TREE or HASH indexes,
402+
and in vinyl TREE indexes.
399403
* **varbinary**: any set of octets, up to the :ref:`maximum length
400404
<limitations_bytes_in_index_key>`. Legal in
401405
memtx TREE or HASH indexes, and in vinyl TREE indexes.
@@ -406,8 +410,9 @@ Below is a list of all ``box.space`` functions and members.
406410
booleans (true or false), or integers between
407411
-9223372036854775808 and 18446744073709551615, or single-precision
408412
floating point numbers, or double-precison floating-point numbers, or
409-
strings. When there is a mix of types, the key order is: null, then
410-
booleans, then numbers, then strings. Legal in memtx TREE or
413+
exact numbers, or strings, or (varbinary) byte arrays.
414+
When there is a mix of types, the key order is: null, then
415+
booleans, then numbers, then strings, then byte arrays. Legal in memtx TREE or
411416
HASH indexes, and in vinyl TREE indexes.
412417

413418
Additionally, `nil` is allowed with any index field type if
@@ -450,11 +455,17 @@ Below is a list of all ``box.space`` functions and members.
450455
| | single-precision | | |
451456
| | floating point numbers, | | |
452457
| | double-precision | | |
453-
| | floating point numbers | | |
458+
| | floating point numbers, | | |
459+
| | exact (decimal) numbers | | |
454460
+------------------+---------------------------+---------------------------------------+-----------------------+
455461
| **boolean** | true or false | memtx TREE or HASH indexes, |br| | false |br| |
456462
| | | vinyl TREE indexes | true |
457463
+------------------+---------------------------+---------------------------------------+-----------------------+
464+
| **decimal** | exact numbers returned by | memtx TREE or HASH indexes, |br| | decimal.new(1.2) |br| |
465+
| | a function in the | vinyl TREE indexes | |
466+
| | :ref:`decimal <decimal>` | | |
467+
| | module | | |
468+
+------------------+---------------------------+---------------------------------------+-----------------------+
458469
| **array** | array of integers between | memtx RTREE indexes | {10, 11} |br| |
459470
| | -9223372036854775808 and | | {3, 5, 9, 10} |
460471
| | 9223372036854775807 | | |
@@ -790,7 +801,7 @@ Below is a list of all ``box.space`` functions and members.
790801
have the same name;
791802
* the ``type`` value may be any of those allowed for
792803
:ref:`indexed fields <index-box_indexed-field-types>`:
793-
unsigned | string | varbinary | integer | number | boolean | array | scalar
804+
unsigned | string | varbinary | integer | number | boolean | decimal | array | scalar
794805
(the same as the requirement in
795806
:ref:`"Options for space_object:create_index" <box_space-create_index-options>`);
796807
* the optional ``is_nullable`` value may be either ``true`` or ``false``
@@ -863,31 +874,60 @@ Below is a list of all ``box.space`` functions and members.
863874

864875
.. code-block:: tarantoolsession
865876
877+
tarantool> decimal = require('decimal')
878+
---
879+
...
866880
tarantool> box.schema.space.create('t')
867-
--- ...
881+
---
882+
- engine: memtx
883+
before_replace: 'function: 0x40650f60'
884+
on_replace: 'function: 0x406a3eb8'
885+
ck_constraint: []
886+
field_count: 0
887+
temporary: false
888+
index: []
889+
is_local: false
890+
enabled: false
891+
name: t
892+
id: 512
893+
- created
894+
...
868895
tarantool> box.space.t:format({{name='1',type='any'},
869-
> {name='2',type='unsigned'},
870-
> {name='3',type='string'},
871-
> {name='4',type='number'},
872-
> {name='5',type='integer'},
873-
> {name='6',type='boolean'},
874-
> {name='7',type='scalar'},
875-
> {name='8',type='array'},
876-
> {name='9',type='map'}})
877-
--- ...
896+
> {name='2',type='unsigned'},
897+
> {name='3',type='string'},
898+
> {name='4',type='number'},
899+
> {name='5',type='integer'},
900+
> {name='6',type='boolean'},
901+
> {name='7',type='decimal'},
902+
> {name='8',type='scalar'},
903+
> {name='9',type='array'},
904+
> {name='10',type='map'}})
905+
---
906+
...
878907
tarantool> box.space.t:create_index('i',{parts={2,'unsigned'}})
879-
--- ...
880-
tarantool> box.space.t:insert{{'a'}, -- any
881-
> 1, -- unsigned
882-
> 'W?', -- string
883-
> 5.5, -- number
884-
> -0, -- integer
885-
> true, -- boolean
886-
> true, -- scalar
887-
> {{'a'}}, -- array
888-
> {val=1}} -- map
889908
---
890-
- [['a'], 1, 'W?', 5.5, 0, true, true, [['a']], {'val': 1}]
909+
- unique: true
910+
parts:
911+
- type: unsigned
912+
is_nullable: false
913+
fieldno: 2
914+
id: 0
915+
space_id: 512
916+
type: TREE
917+
name: i
918+
...
919+
tarantool> box.space.t:insert{{'a'}, -- any
920+
> 1, -- unsigned
921+
> 'W?', -- string
922+
> 5.5, -- number
923+
> -0, -- integer
924+
> true, -- boolean
925+
> decimal.new(1.2), -- decimal
926+
> true, -- scalar
927+
> {{'a'}}, -- array
928+
> {val=1}} -- map
929+
---
930+
- [['a'], 1, 'W?', 5.5, 0, true, 1.2, true, [['a']], {'val': 1}]
891931
...
892932
893933
Names specified with the format clause can be used in

‎doc/2.2/book/box/data_model.rst

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -162,6 +162,8 @@ Lua vs MsgPack
162162
+-------------------+----------------------+--------------------------------+----------------------------+
163163
| scalar | bin | "`cdata`_" | [!!binary 3t7e] |
164164
+-------------------+----------------------+--------------------------------+----------------------------+
165+
| scalar | ext | (converted to exact number) | 1.2 |
166+
+-------------------+----------------------+--------------------------------+----------------------------+
165167
| compound | map | "`table`_" (with string keys) | {'a': 5, 'b': 6} |
166168
+-------------------+----------------------+--------------------------------+----------------------------+
167169
| compound | array | "`table`_" (with integer keys) | [1, 2, 3, 4, 5] |
@@ -212,6 +214,11 @@ Here are examples of numbers using regular notation, exponential notation,
212214
the ULL suffix and the ``tonumber64`` function:
213215
``-55``, ``-2.7e+20``, ``100000000000000ULL``, ``tonumber64('18446744073709551615')``.
214216

217+
An **ext** (extension) value is an addition by Tarantool, not part of the
218+
formal MsgPack definition, for storage of decimal values. Values with the
219+
decimal type are not floating-point values although they may contain decimal
220+
points. They are exact.
221+
215222
A **bin** (binary) value is not directly supported by Lua but there is
216223
a Tarantool type ``VARBINARY`` which is encoded as MessagePack binary.
217224
For an (advanced) example showing how to insert VARBINARY into a database,
@@ -309,6 +316,9 @@ Here's how Tarantool indexed field types correspond to MsgPack data types.
309316
| **boolean** | **bool** | TREE or HASH | true |
310317
| | (true or false) | | |
311318
+----------------------------+-----------------------------------+----------------------+--------------------+
319+
| **decimal** | **ext** | TREE or HASH | 1.2 |
320+
| | (extension) | | |
321+
+----------------------------+-----------------------------------+----------------------+--------------------+
312322
| **array** | **array** | RTREE | {10, 11} |
313323
| | (list of numbers representing | | |
314324
| | points in a geometric figure) | | {3, 5, 9, 10} |
@@ -329,6 +339,11 @@ Here's how Tarantool indexed field types correspond to MsgPack data types.
329339
| | point number or double-precision | | |
330340
| | floating point number) | | |
331341
| | | | |
342+
| | **decimal** | | |
343+
| | (value returned by a function in | | |
344+
| | the :ref:`decimal <decimal>` | | |
345+
| | module | | |
346+
| | | | |
332347
| | **string** (any set of octets) | | |
333348
| | | | |
334349
| | **varbinary** (any set of octets) | | |

‎doc/2.2/dev_guide/reference_capi/tuple.rst

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -138,11 +138,15 @@
138138
.. cpp:enumerator:: ::FIELD_TYPE_ANY
139139
.. cpp:enumerator:: ::FIELD_TYPE_UNSIGNED
140140
.. cpp:enumerator:: ::FIELD_TYPE_STRING
141-
.. cpp:enumerator:: ::FIELD_TYPE_ARRAY
142141
.. cpp:enumerator:: ::FIELD_TYPE_NUMBER
143142
.. cpp:enumerator:: ::FIELD_TYPE_INTEGER
143+
.. cpp:enumerator:: ::FIELD_TYPE_BOOLEAN
144+
.. cpp:enumerator:: ::FIELD_TYPE_VARBINARY
144145
.. cpp:enumerator:: ::FIELD_TYPE_SCALAR
145-
.. cpp:enumerator:: ::field_type_MAX
146+
.. cpp:enumerator:: ::FIELD_TYPE_DECIMAL
147+
.. cpp:enumerator:: ::FIELD_TYPE_ARRAY
148+
.. cpp:enumerator:; ::FIELD_TYPE_MAP
149+
.. cpp:enumerator:: ::FIELD_TYPE_MAX
146150
147151
Possible data types for tuple fields.
148152

‎doc/2.2/reference/reference_sql/sql.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2731,7 +2731,7 @@ are a number and a string, etc.
27312731
If an argument is missing or is NULL, it becomes:
27322732

27332733
* '0' if the format requires an integer,
2734-
* '0.0' if the format requires a decimal number,
2734+
* '0.0' if the format requires a number with a decimal point,
27352735
* '' if the format requires a string.
27362736

27372737
Example: ``PRINTF('%da', 5)`` is '5a'.

0 commit comments

Comments
 (0)