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

[Vladislav Shpilevoy <v.shpilevoy@tarantool.org>]

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