From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp43.i.mail.ru (smtp43.i.mail.ru [94.100.177.103]) (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 769CA469719 for ; Mon, 17 Feb 2020 23:21:43 +0300 (MSK) Received: by smtp43.i.mail.ru with esmtpa (envelope-from ) id 1j3mti-0004H4-UN for tarantool-patches@dev.tarantool.org; Mon, 17 Feb 2020 23:21:43 +0300 References: <33c5c23a-b966-b766-be4f-5e4f23665194@tarantool.org> From: Oleg Babin Message-ID: <88d81178-4ada-c346-5c2c-7f2132d181d9@tarantool.org> Date: Mon, 17 Feb 2020 23:21:42 +0300 MIME-Version: 1.0 In-Reply-To: <33c5c23a-b966-b766-be4f-5e4f23665194@tarantool.org> Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-GB 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 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 > ... > ``` >