Module varbinary

Since: 3.0.0

Overview

The varbinary module provides functions for operating variable-length binary objects in Lua. It provides functions for creating varbinary objects, checking their type, and also defines basic operators on such objects.

For example:

local varbinary = require('varbinary')

-- Create a varbinary object
local bin = varbinary.new('data')
local bin_hex = varbinary.new('\xFF\xFE')

-- Check whether a value is a varbinary object
varbinary.is(bin) -- true
varbinary.is(bin_hex) -- true
varbinary.is(100) -- false
varbinary.is('data') -- false

-- Check varbinary objects equality
print(bin == varbinary.new('data')) -- true
print(bin == 'data') -- true
print(bin ~= 'data1') -- true
print(bin_hex ~= '\xFF\xFE') -- false

-- Check varbinary objects length
print(#bin) -- 4
print(#bin_hex) -- 2

-- Print string representation
print(tostring(bin)) -- data

Encoding varbinary objects

varbinary objects preserve their binary type when encoded by the built-in MsgPack and YAML encoders. See the difference with strings:

String to MsgPack:

tarantool> msgpack.encode('\xFF\xFE')
---
- "\xA2\xFF\xFE"
...

varbinary to MsgPack:

tarantool> msgpack.encode(varbinary.new('\xFF\xFE'))
---
- "\xC4\x02\xFF\xFE"
...

String to YAML:

tarantool> '\xFF\xFE'
---
- "\xFF\xFE"
...

varbinary to YAML:

tarantool> varbinary.new('\xFF\xFE')
---
- !!binary //4=
...

Note

The JSON format doesn’t support the binary type so varbinary objects are encoded as plain strings in JSON:

tarantool> json.encode('\xFF\xFE')
---
- "\"\xFF\xFE\""
...

tarantool> json.encode(varbinary.new('\xFF\xFE'))
---
- "\"\xFF\xFE\""
...

Decoding binary data to varbinary objects

The built-in decoders also decode binary data fields (fields with the binary tag in YAML and the MP_BIN type in MsgPack) to varbinary objects by default:

tarantool> varbinary.is(msgpack.decode('\xC4\x02\xFF\xFE'))
---
- true
...

tarantool> varbinary.is(yaml.decode('!!binary //4='))
---
- true
...

Important

This behavior is different from what it was before Tarantool 3.0. In earlier versions, such fields were decoded to plain strings. To return to this behavior, use the compat option binary_data_decoding.

API Reference

Below is a list of varbinary functions, properties, and related objects.

Functions
varbinary.is()	Check that the argument is a `varbinary` object
varbinary.new()	Create a `varbinary` object
Metamethods
varbinary_object.__eq	Checks the equality of two `varbinary` objects
varbinary_object.__len	Returns the length of the binary data in bytes
varbinary_object.__tostring	Returns the binary data in a plain string

Functions

varbinary.is(object)¶

Check that the given object is a varbinary object.

Parameters:	object (`object`) – an object to check
Return:	Whether the given object is of `varbinary` type
Rtype:	boolean

Example:

local bin = varbinary.new('data')
local bin_hex = varbinary.new('\xFF\xFE')

-- Check whether a value is a varbinary object
varbinary.is(bin) -- true
varbinary.is(bin_hex) -- true
varbinary.is(100) -- false
varbinary.is('data') -- false

varbinary.new(string)¶

Create a new varbinary object from a given string.

Parameters:	string (`string`) – a string object
Return:	A `varbinary` object containing the string data
Rtype:	cdata

Example:

local bin = varbinary.new('data')
local bin_hex = varbinary.new('\xFF\xFE')

varbinary.new(ptr, size)

Create a new varbinary object from a cdata pointer and size.

Parameters:	ptr (`cdata`) – a `cdata` pointer size (`number`) – object size in bytes
Return:	A `varbinary` object containing the data
Rtype:	cdata

Example:

local bin2 = varbinary.new(ffi.cast('const char *', 'data'), 4)
varbinary.is(bin2) -- true
print(bin2) -- data

Metamethods

object varbinary_object¶

varbinary_object:__eq(object)¶

Checks the equality of two varbinary objects or a varbinary object and a string. A varbinary object equals to another varbinary object or a string if it contains the same data.

Defines the == and ~= operators for varbinary objects.

Rtype:	boolean

Example:

print(bin == varbinary.new('data')) -- true
print(bin == 'data') -- true
print(bin ~= 'data1') -- true
print(bin_hex ~= '\xFF\xFE') -- false

varbinary_object:__len()¶

Returns the length of the binary data in bytes.

Defines the # operator for varbinary objects.

Rtype:	number

Example:

print(#bin) -- 4
print(#bin_hex) -- 2

varbinary_object:__tostring()¶

Returns the binary data in a plain string.

Defines the tostring() function for varbinary objects.

Rtype:	string

Version:

Module varbinary

Overview

Encoding varbinary objects

Decoding binary data to varbinary objects

API Reference

Functions

Metamethods