Module varbinary

Since: 3.0.0

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 objectlocal bin = varbinary.new('data')local bin_hex = varbinary.new('\xFF\xFE')-- Check whether a value is a varbinary objectvarbinary.is(bin) -- truevarbinary.is(bin_hex) -- truevarbinary.is(100) -- falsevarbinary.is('data') -- false-- Check varbinary objects equalityprint(bin == varbinary.new('data')) -- trueprint(bin == 'data') -- trueprint(bin ~= 'data1') -- trueprint(bin_hex ~= '\xFF\xFE') -- false-- Check varbinary objects lengthprint(#bin) -- 4print(#bin_hex) -- 2-- Print string representationprint(tostring(bin)) -- datalocal bin2 = varbinary.new(ffi.cast('const char *', 'data'), 4)varbinary.is(bin2) -- trueprint(bin2) -- datalocal luatest = require('luatest')local test_group = luatest.group()test_group.test_varbinary = function()    luatest.assert_equals(varbinary.is(bin), true)    luatest.assert_equals(bin, 'data')    luatest.assert_equals(#bin, 4)    luatest.assert_equals(#varbinary.new('\xFF\xFE'), 2)end

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=...

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...

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

Check that the given object is a varbinary object.

Parameters:

• object (object) — an object to check

Returns

Whether the given object is of varbinary type

Return type

boolean

Example:

Create a new varbinary object from a given string.

• string (string) — a string object

Returns

A varbinary object containing the string data

Return type

cdata

Example:

 
local bin = varbinary.new('data')local bin_hex = varbinary.new('\xFF\xFE')-- Check whether a value is a varbinary objectvarbinary.is(bin) -- truevarbinary.is(bin_hex) -- truevarbinary.is(100) -- falsevarbinary.is('data') -- false-- Check varbinary objects equalityprint(bin == varbinary.new('data')) -- trueprint(bin == 'data') -- trueprint(bin ~= 'data1') -- trueprint(bin_hex ~= '\xFF\xFE') -- false-- Check varbinary objects lengthprint(#bin) -- 4print(#bin_hex) -- 2-- Print string representationprint(tostring(bin)) -- datalocal bin2 = varbinary.new(ffi.cast('const char *', 'data'), 4)varbinary.is(bin2) -- trueprint(bin2) -- datalocal luatest = require('luatest')local test_group = luatest.group()test_group.test_varbinary = function()    luatest.assert_equals(varbinary.is(bin), true)    luatest.assert_equals(bin, 'data')    luatest.assert_equals(#bin, 4)    luatest.assert_equals(#varbinary.new('\xFF\xFE'), 2)end

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

• ptr (cdata) — a cdata pointer

• size (number) — object size in bytes

Returns

A varbinary object containing the data

Return type

cdata

Example:

: varbinary_object

method __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.

Return type

boolean

Example:

method __len()

Returns the length of the binary data in bytes.

Defines the # operator for varbinary objects.

Return type

number

Example:

Returns the binary data in a plain string.

Defines the tostring() function for varbinary objects.

Return type

string