[Tarantool-patches] [PATCH 2/2] tuple: make box.tuple.is() public

[Oleg Babin]

HI! Vlad!

It seems that "slice" is redundant. I've filed an issue 
https://github.com/tarantool/doc/issues/1123. Alexandr T. found that 
"slise" was removed from doc in 1.6.5.

Quite strange why this method was not deleted later. But I think that it 
should be dropped from your commit message. And may be we should discuss 
depreciation and deletion os this method.

On 16/02/2020 18:07, Vladislav Shpilevoy wrote:
> As Oleg noticed, some other tuple methods were public, but
> were not documented. I changed the commit message and doc
> request to document them too.
> 
> ================================================================================
> 
> tuple: document all box.tuple.* methods
> 
> In #4684 it was found that box.tuple.* contained some private
> functions: bless(), encode(), and is().
> 
> Bless() and encode() didn't make any sense for a user, so they
> were hidden into box.internal.tuple.*.
> 
> But box.tuple.is() is actually a useful thing. It is harnessed in
> the tests a lot, and is likely to be already used by customers,
> because it is available in box.tuple.* for a long time. It is a
> matter of time when someone will open a doc ticket saying that
> box.tuple.is() is not documented. The patch makes it legally
> public.
> 
> Alongside it was discovered that tuple:next()/ipairs()/slice()/
> upsert() were public, but were not documented. The patch carries a
> docbot request for them all.
> 
> Follow-up #4684
> 
> @TarantoolBot document
> Title: box.tuple.is()/next()/ipairs()/slice()/upsert()
> 
> ```Lua
> box.tuple.is(object)
> ```
> A function to check whether a given object is a tuple cdata
> object. Returns true or false. Never raises nor returns an error.
> 
> ```Lua
> tuple_object:next(pos)
> ```
> An analogue of Lua `next()` function, but for a tuple object.
> Although `tuple:next()` is not really efficient, and it is better
> to use `tuple:pairs()/ipairs()`.
> ```
> tarantool> t = box.tuple.new({1, 2, 3})
> tarantool> ctx, field = t:next()
> tarantool> while field do
>      print(field)
>      ctx, field = t:next(ctx)
> end
> tarantool>
> 1 2 3
> ```
> 
> ```Lua
> tuple_object:ipairs()
> ```
> The same as `tuple_object:pairs()`. Because tuple fields are
> integer always.
> 
> ```Lua
> tuple_object:slice(from[, to])
> ```
> Extract tuple fields by a given range. `From` is not included. So
> to take fields starting from the first use `from = 0`. `To` is
> included and should be > `from`.
> ```
> tarantool> t = box.tuple.new({1, 2, 3})
> tarantool> t:slice(0)
> ---
> - 1
> - 2
> - 3
> ...
> 
> tarantool> t:slice(0, 1)
> ---
> - 1
> ...
> 
> tarantool> t:slice(1, 3)
> ---
> - 2
> - 3
> ...
> ```
> 
> ```Lua
> tuple_object:upsert()
> ```
> The same as `tuple_object:update()`, but ignores errors. In case
> of an error the tuple is left intact, but an error message is
> printed. Only client errors are ignored, such as a bad field type,
> or wrong field index/name. System errors, such as OOM, are not
> ignored and raised just like with normal `update()`. Note, that
> only bad operations are ignored. All correct operations are
> applied.
> ```
> tarantool> t = box.tuple.new({1, 2, 3})
> tarantool> t2 = t:upsert({{'=', 5, 100}})
> UPSERT operation failed:
> ER_NO_SUCH_FIELD_NO: Field 5 was not found in the tuple
> ---
> ...
> 
> tarantool> t
> ---
> - [1, 2, 3]
> ...
> 
> tarantool> t2
> ---
> - [1, 2, 3]
> ...
> 
> tarantool> t2 = t:upsert({{'=', 5, 100}, {'+', 1, 3}})
> UPSERT operation failed:
> ER_NO_SUCH_FIELD_NO: Field 5 was not found in the tuple
> ---
> ...
> 
> tarantool> t
> ---
> - [1, 2, 3]
> ...
> 
> tarantool> t2
> ---
> - [4, 2, 3]
> ...
> ```
> See how in the last example one operation is applied, and one is
> not.
> 
> All methods of `tuple_object` are also available in `box.tuple.*`,
> and a tuple needs to be passed explicitly then. Example below:
> ```
> tarantool> t = box.tuple.new({1, 2, 3})
> tarantool> box.tuple.slice(t, 0, 1)
> ---
> - 1
> ...
> ```
>