Constant box.NULL

There are some major problems with using Lua nil values in tables. For example: you can't correctly assess the length of a table that is not a sequence. (Learn more about data types in Lua and LuaJIT.)

Example:

 
tarantool> t = {0, nil, 1, 2, nil}---...tarantool> t---- - 0  - null  - 1  - 2...tarantool> #t---- 4...

The console output of t processes nil values in the middle and at the end of the table differently. This is due to undefined behavior.

To avoid this problem, use Tarantool's box.NULL constant instead of nil. box.NULL is a placeholder for a nil value in tables to preserve a key without a value.

box.NULL is a value of the cdata type representing a NULL pointer. It is similar to msgpack.NULL, json.NULL and yaml.NULL. So it is some not nil value, even if it is a pointer to NULL.

Use box.NULL only with capitalized NULL (box.null is incorrect).

Example:

 
tarantool> t = {0, box.NULL, 1, 2, box.NULL}---...tarantool> t---- - 0  - null # cdata  - 1  - 2  - null # cdata...tarantool> #t---- 5...

Use the expression if x == nil to check if the x is either a nil or a box.NULL.

To check whether x is a nil but not a box.NULL, use the following condition expression:

 
type(x) == 'nil'

If it's true, then x is a nil, but not a box.NULL.

You can use the following for box.NULL:

 
x == nil and type(x) == 'cdata'

If the expression above is true, then x is a box.NULL.