Document the varbinary type

[TarantoolBot]

Related issue: #1542
Related doc issue: #4237

Product: Tarantool
Since: 3.0.0-alpha1
Root document: https://www.tarantool.io/en/doc/latest/reference/reference_lua/ varbinary
https://www.tarantool.io/en/doc/latest/reference/reference_lua/compat/ binary_data_decoding
https://www.tarantool.io/en/doc/latest/concepts/data_model/value_store/#data-types
https://www.tarantool.io/en/doc/latest/how-to/app/cookbook/#ffi-varbinary-insert-lua
https://www.tarantool.io/en/doc/latest/concepts/data_model/value_store/#bin
SME: @ locker

Definition of done

• Create a documentation section for the new varbinary module
• Create a documentation page for the new compat option (binary_data_decoding)
• Add a "see also" link to the option reference (doc above) on the compat.binary_data_decoding description in the configuration reference
• Delete the outdated Lua cookbook recipe ffi_varbinary_insert

Details

The new module varbinary was introduced. The module implements the
following functions:

• varbinary.new - constructs a varbinary object from a plain string
  or cdata pointer and size (to be used with the buffer module).
• varbinary.is - returns true if the argument is a varbinary object.

local bin = varbinary.new('data')
assert(varbinary.is(bin))
assert(not varbinary.is('data'))

Like a plain string, a varbinary object stores arbitrary data. Unlike
a plain string, it's encoded as a binary blob by the built-in encoders
that support the binary type (MsgPack, YAML). (Actually, encoding binary
blobs with the proper type is the main goal of the new type.)

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

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

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

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

Note, the JSON format doesn't support the binary type so a varbinary
object is still encoded as a plain string:

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

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

The built-in decoders now decode binary data fields (fields with the
'binary' tag in YAML; the MP_BIN type in MsgPack) to a varbinary
object by default:

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

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

This also implies that the data stored in the database under the
'varbinary' field type is now returned to Lua not as a plain string,
but as a varbinary object. It's possible to revert to the old behavior
by toggling the new compat option binary_data_decoding because this
change may break backward compatibility:

tarantool> compat.binary_data_decoding = 'old'
---
...

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

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

Please create a documentation page for the new compat option:
https://tarantool.io/compat/binary_data_decoding

A varbinary object implements the following meta-methods:

• __len - returns the length of the binary data, in bytes.
• __tostring - returns the data in a plain string.
• __eq - returns true if the varbinary object contains
  the same data as another varbinary object or a string.

local bin = varbinary.new('foo')
assert(#bin == 3)
assert(tostring(bin) == 'foo')
assert(bin == 'foo')
assert(bin ~= 'bar')
assert(bin == varbinary.new('foo'))
assert(bin ~= varbinary.new('bar'))

There are no string manipulation methods, like string.sub or
string.match. If you need to match a substring in a varbinary
object, you have to convert it to a string first.

For more details, see the design document.

Requested by @locker in tarantool/tarantool@ba749e8.

[andreyaksenov]

What's new section: https://www.tarantool.io/en/doc/latest/release/3.0.0/#varbinary-in-lua