From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp37.i.mail.ru (smtp37.i.mail.ru [94.100.177.97]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by dev.tarantool.org (Postfix) with ESMTPS id 610B3469719 for ; Sun, 16 Feb 2020 18:07:29 +0300 (MSK) From: Vladislav Shpilevoy References: Message-ID: <33c5c23a-b966-b766-be4f-5e4f23665194@tarantool.org> Date: Sun, 16 Feb 2020 16:07:27 +0100 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 7bit Subject: Re: [Tarantool-patches] [PATCH 2/2] tuple: make box.tuple.is() public List-Id: Tarantool development patches List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: tarantool-patches@dev.tarantool.org, babinoleg@mail.ru, alexander.turenko@tarantool.org, imun@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 ... ```