Module varbinary

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

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

Functions

varbinary.is(object)¶

Check that the given object is a varbinary object.

Параметры:	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.

Параметры:	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.

Параметры:	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