class Aerospike::Exp::List

List expression generator. See {Exp}.

The bin expression argument in these methods can be a reference to a bin or the result of another expression. Expressions that modify bin values are only used for temporary expression evaluation and are not permanently applied to the bin.

List modify expressions the bin’s value. This value will be a list except when the list is nested within a map. In that case, a map is returned for the list modify expression.

List expressions support negative indexing. If the index is negative, the resolved index starts backwards from end of list. If an index is out of bounds, a parameter error will be returned. If a range is partially out of bounds, the valid part of the range will be returned. Index/Range examples:

Index 0: First item in list. Index 4: Fifth item in list. Index -1: Last item in list. Index -3: Third to last item in list. Index 1 Count 2: Second and third items in list. Index -3 Count 3: Last three items in list. Index -5 Count 4: Range between fifth to last item to second to last item inclusive.

Nested expressions are supported by optional CTX context arguments. Example:

bin = [[7,9,5],,[6,5,4,1]] Get size of last list. ListExp.size(Exp.listBin(“bin”), CTX.listIndex(-1)) result = 4

Constants

APPEND
APPEND_ITEMS
CLEAR
GET_BY_INDEX
GET_BY_INDEX_RANGE
GET_BY_RANK
GET_BY_RANK_RANGE
GET_BY_VALUE
GET_BY_VALUE_INTERVAL
GET_BY_VALUE_LIST
GET_BY_VALUE_REL_RANK_RANGE
INCREMENT
INSERT
INSERT_ITEMS
MODULE
REMOVE_BY_INDEX
REMOVE_BY_INDEX_RANGE
REMOVE_BY_RANK
REMOVE_BY_RANK_RANGE
REMOVE_BY_VALUE
REMOVE_BY_VALUE_INTERVAL
REMOVE_BY_VALUE_LIST
REMOVE_BY_VALUE_REL_RANK_RANGE
SET
SIZE
SORT

Public Class Methods

add_read(bin, bytes, ret_type) click to toggle source
# File lib/aerospike/exp/exp_list.rb, line 363
def self.add_read(bin, bytes, ret_type)
  Exp::Module.new(bin, bytes, ret_type, MODULE)
end
add_write(bin, bytes, ctx) click to toggle source
# File lib/aerospike/exp/exp_list.rb, line 354
def self.add_write(bin, bytes, ctx)
  ret_type = if ctx.to_a.empty?
    Exp::Type::LIST
             else
    (ctx[0].id & 0x10) == 0 ? Exp::Type::MAP : Exp::Type::LIST
             end
  Exp::Module.new(bin, bytes, ret_type, MODULE | Exp::MODIFY)
end
append(value, bin, ctx: nil, policy: CDT::ListPolicy::DEFAULT) click to toggle source

Create expression that appends value to end of list.

# File lib/aerospike/exp/exp_list.rb, line 51
def self.append(value, bin, ctx: nil, policy: CDT::ListPolicy::DEFAULT)
  bytes = Exp.pack(ctx, APPEND, value, policy.order, policy.flags)
  add_write(bin, bytes, ctx)
end
append_items(list, bin, ctx: nil, policy: CDT::ListPolicy::DEFAULT) click to toggle source

Create expression that appends list items to end of list.

# File lib/aerospike/exp/exp_list.rb, line 57
def self.append_items(list, bin, ctx: nil, policy: CDT::ListPolicy::DEFAULT)
  bytes = Exp.pack(ctx, APPEND_ITEMS, list, policy.order, policy.flags)
  add_write(bin, bytes, ctx)
end
clear(bin, ctx: nil) click to toggle source

Create expression that removes all items in list.

# File lib/aerospike/exp/exp_list.rb, line 88
def self.clear(bin, ctx: nil)
  bytes = Exp.pack(ctx, CLEAR)
  add_write(bin, bytes, ctx)
end
get_by_index(return_type, value_type, index, bin, ctx: nil) click to toggle source

Create expression that selects list item identified by index and returns selected data specified by return_type.

Examples

# a == 5 Exp.eq(

ListExp.getByIndex(CDT::ListReturnType::VALUE, Exp::Type::INT, Exp.val(3), Exp.listBin("a")),
Exp.val(5))

end</pre>

@param return_type metadata attributes to return. See {CDT::ListReturnType} @param value_type expected type of value @param index list index expression @param bin list bin or list value expression @param ctx optional context path for nested CDT

# File lib/aerospike/exp/exp_list.rb, line 266
def self.get_by_index(return_type, value_type, index, bin, ctx: nil)
  bytes = Exp.pack(ctx, GET_BY_INDEX, return_type, index)
  add_read(bin, bytes, value_type)
end
get_by_index_range(return_type, index, bin, ctx: nil) click to toggle source

Create expression that selects list items starting at specified index to the end of list and returns selected data specified by return_type (See {CDT::ListReturnType}).

# File lib/aerospike/exp/exp_list.rb, line 273
def self.get_by_index_range(return_type, index, bin, ctx: nil)
  bytes = Exp.pack(ctx, GET_BY_INDEX_RANGE, return_type, index)
  add_read(bin, bytes, get_value_type(return_type))
end
get_by_rank(return_type, value_type, rank, bin, ctx: nil) click to toggle source

Create expression that selects list item identified by rank and returns selected data specified by return_type.

Examples

# Player with lowest score. ListExp.getByRank(CDT::ListReturnType::VALUE, Type.STRING, Exp.val(0), Exp.listBin(“a”)) end</pre>

@param return_type metadata attributes to return. See {CDT::ListReturnType} @param value_type expected type of value @param rank rank expression @param bin list bin or list value expression @param ctx optional context path for nested CDT

# File lib/aerospike/exp/exp_list.rb, line 302
def self.get_by_rank(return_type, value_type, rank, bin, ctx: nil)
  bytes = Exp.pack(ctx, GET_BY_RANK, return_type, rank)
  add_read(bin, bytes, value_type)
end
get_by_rank_range(return_type, rank, bin, ctx: nil) click to toggle source

Create expression that selects list items starting at specified rank to the last ranked item and returns selected data specified by return_type (See {CDT::ListReturnType}).

# File lib/aerospike/exp/exp_list.rb, line 309
def self.get_by_rank_range(return_type, rank, bin, ctx: nil)
  bytes = Exp.pack(ctx, GET_BY_RANK_RANGE, return_type, rank)
  add_read(bin, bytes, get_value_type(return_type))
end
get_by_value(return_type, value, bin, ctx: nil) click to toggle source

Create expression that selects list items identified by value and returns selected data specified by return_type.

Examples

# List bin “a” contains at least one item == “abc” Exp.gt(

ListExp.getByValue(CDT::ListReturnType::COUNT, Exp.val("abc"), Exp.listBin("a")),
Exp.val(0))

end</pre>

@param return_type metadata attributes to return. See {CDT::ListReturnType} @param value search expression @param bin list bin or list value expression @param ctx optional context path for nested CDT

# File lib/aerospike/exp/exp_list.rb, line 200
def self.get_by_value(return_type, value, bin, ctx: nil)
  bytes = Exp.pack(ctx, GET_BY_VALUE, return_type, value)
  add_read(bin, bytes, get_value_type(return_type))
end
get_by_value_list(return_type, values, bin, ctx: nil) click to toggle source

Create expression that selects list items identified by values and returns selected data specified by return_type.

# File lib/aerospike/exp/exp_list.rb, line 225
def self.get_by_value_list(return_type, values, bin, ctx: nil)
  bytes = Exp.pack(ctx, GET_BY_VALUE_LIST, return_type, values)
  add_read(bin, bytes, get_value_type(return_type))
end
get_by_value_range(return_type, value_begin, value_end, bin, ctx: nil) click to toggle source

Create expression that selects list items identified by value range and returns selected data specified by return_type.

Examples

# List bin “a” items >= 10 && items < 20 ListExp.getByValueRange(CDT::ListReturnType::VALUE, Exp.val(10), Exp.val(20), Exp.listBin(“a”)) end</pre>

@param return_type metadata attributes to return. See {CDT::ListReturnType} @param value_begin begin expression inclusive. If nil, range is less than value_end. @param value_end end expression exclusive. If nil, range is greater than equal to value_begin. @param bin bin or list value expression @param ctx optional context path for nested CDT

# File lib/aerospike/exp/exp_list.rb, line 218
def self.get_by_value_range(return_type, value_begin, value_end, bin, ctx: nil)
  bytes = pack_range_operation(GET_BY_VALUE_INTERVAL, return_type, value_begin, value_end, ctx)
  add_read(bin, bytes, get_value_type(return_type))
end
get_by_value_relative_rank_range(return_type, value, rank, bin, ctx: nil, count: nil) click to toggle source

Create expression that selects list items nearest to value and greater by relative rank with a count limit and returns selected data specified by return_type (See {CDT::ListReturnType}).

Examples for ordered list [0,4,5,9,11,15]:

(value,rank,count) = [selected items] (5,0,2) = [5,9] (5,1,1) = [9] (5,-1,2) = [4,5] (3,0,1) = [4] (3,3,7) = [11,15] (3,-3,2) = []

# File lib/aerospike/exp/exp_list.rb, line 242
def self.get_by_value_relative_rank_range(return_type, value, rank, bin, ctx: nil, count: nil)
  bytes = if count.nil?
    Exp.pack(ctx, GET_BY_VALUE_REL_RANK_RANGE, return_type, value, rank)
          else
    Exp.pack(ctx, GET_BY_VALUE_REL_RANK_RANGE, return_type, value, rank, count)
          end
  add_read(bin, bytes, get_value_type(return_type))
end
get_value_type(return_type) click to toggle source
# File lib/aerospike/exp/exp_list.rb, line 367
def self.get_value_type(return_type)
  t = return_type & ~CDT::ListReturnType::INVERTED
  case t
  when ListReturnType::INDEX,
     ListReturnType::REVERSE_INDEX,
     ListReturnType::RANK,
     ListReturnType::REVERSE_RANK
      # This method only called from expressions that can return multiple integers (ie list).
      Exp::Type::LIST

  when ListReturnType::COUNT
    Exp::Type::INT

  when ListReturnType::VALUE
      # This method only called from expressions that can return multiple objects (ie list)::
      Exp::Type::LIST

  when ListReturnType::EXISTS
      Exp::Type::BOOL

  else
      raise Exceptions::Aerospike.new(Aerospike::ResultCode::PARAMETER_ERROR, "Invalid ListReturnType: #{return_type}")
  end
end
increment(index, value, bin, ctx: nil, policy: CDT::ListPolicy::DEFAULT) click to toggle source

Create expression that increments list by value. Value expression should resolve to a number.

# File lib/aerospike/exp/exp_list.rb, line 76
def self.increment(index, value, bin, ctx: nil, policy: CDT::ListPolicy::DEFAULT)
  bytes = Exp.pack(ctx, INCREMENT, index, value, policy.order, policy.flags)
  add_write(bin, bytes, ctx)
end
insert(index, value, bin, ctx: nil, policy: CDT::ListPolicy::DEFAULT) click to toggle source

Create expression that inserts value to specified index of list.

# File lib/aerospike/exp/exp_list.rb, line 63
def self.insert(index, value, bin, ctx: nil, policy: CDT::ListPolicy::DEFAULT)
  bytes = Exp.pack(ctx, INSERT, index, value, policy.flags)
  add_write(bin, bytes, ctx)
end
insert_items(index, list, bin, ctx: nil, policy: CDT::ListPolicy::DEFAULT) click to toggle source

Create expression that inserts each input list item starting at specified index of list.

# File lib/aerospike/exp/exp_list.rb, line 69
def self.insert_items(index, list, bin, ctx: nil, policy: CDT::ListPolicy::DEFAULT)
  bytes = Exp.pack(ctx, INSERT_ITEMS, index, list, policy.flags)
  add_write(bin, bytes, ctx)
end
pack_range_operation(command, return_type, value_begin, value_end, ctx) click to toggle source
# File lib/aerospike/exp/exp_list.rb, line 392
def self.pack_range_operation(command, return_type, value_begin, value_end, ctx)
  Packer.use do |packer|
    Exp.pack_ctx(packer, ctx)
    packer.write_array_header(value_end.nil? ? 3 : 4)
    packer.write(command)
    packer.write(return_type)

    if value_begin.nil?
      packer.write(nil)
    elsif value_begin.is_a?(Exp)
      value_begin.pack(packer)
    else
        Value.of(value_begin).pack(packer)
    end

    unless value_end.nil?
      if value_end.is_a?(Exp)
        value_end.pack(packer)
      else
        Value.of(value_end).pack(packer)
      end
    end
    packer.bytes
  end
end
remove_by_index(index, bin, ctx: nil) click to toggle source

Create expression that removes list item identified by index.

# File lib/aerospike/exp/exp_list.rb, line 144
def self.remove_by_index(index, bin, ctx: nil)
  bytes = Exp.pack(ctx, REMOVE_BY_INDEX, CDT::ListReturnType::NONE, index)
  add_write(bin, bytes, ctx)
end
remove_by_index_range(index, bin, ctx: nil, count: nil) click to toggle source

Create expression that removes “count” list items starting at specified index.

# File lib/aerospike/exp/exp_list.rb, line 150
def self.remove_by_index_range(index, bin, ctx: nil, count: nil)
  bytes = if count.nil?
    Exp.pack(ctx, REMOVE_BY_INDEX_RANGE, CDT::ListReturnType::NONE, index)
          else
    Exp.pack(ctx, REMOVE_BY_INDEX_RANGE, CDT::ListReturnType::NONE, index, count)
          end
  add_write(bin, bytes, ctx)
end
remove_by_rank(rank, bin, ctx: nil) click to toggle source

Create expression that removes list item identified by rank.

# File lib/aerospike/exp/exp_list.rb, line 160
def self.remove_by_rank(rank, bin, ctx: nil)
  bytes = Exp.pack(ctx, REMOVE_BY_RANK, CDT::ListReturnType::NONE, rank)
  add_write(bin, bytes, ctx)
end
remove_by_rank_range(rank, bin, ctx: nil, count: nil) click to toggle source

Create expression that removes “count” list items starting at specified rank.

# File lib/aerospike/exp/exp_list.rb, line 166
def self.remove_by_rank_range(rank, bin, ctx: nil, count: nil)
  bytes = if count.nil?
    Exp.pack(ctx, REMOVE_BY_RANK_RANGE, CDT::ListReturnType::NONE, rank)
          else
    Exp.pack(ctx, REMOVE_BY_RANK_RANGE, CDT::ListReturnType::NONE, rank, count)
          end
  add_write(bin, bytes, ctx)
end
remove_by_value(value, bin, ctx: nil) click to toggle source

Create expression that removes list items identified by value.

# File lib/aerospike/exp/exp_list.rb, line 104
def self.remove_by_value(value, bin, ctx: nil)
  bytes = Exp.pack(ctx, REMOVE_BY_VALUE, CDT::ListReturnType::NONE, value)
  add_write(bin, bytes, ctx)
end
remove_by_value_list(values, bin, ctx: nil) click to toggle source

Create expression that removes list items identified by values.

# File lib/aerospike/exp/exp_list.rb, line 110
def self.remove_by_value_list(values, bin, ctx: nil)
  bytes = Exp.pack(ctx, REMOVE_BY_VALUE_LIST, CDT::ListReturnType::NONE, values)
  add_write(bin, bytes, ctx)
end
remove_by_value_range(value_begin, value_end, bin, ctx: nil) click to toggle source

Create expression that removes list items identified by value range (value_begin inclusive, value_end exclusive). If value_begin is nil, the range is less than value_end. If value_end is nil, the range is greater than equal to value_begin.

# File lib/aerospike/exp/exp_list.rb, line 118
def self.remove_by_value_range(value_begin, value_end, bin, ctx: nil)
  bytes = pack_range_operation(REMOVE_BY_VALUE_INTERVAL, CDT::ListReturnType::NONE, value_begin, value_end, ctx)
  add_write(bin, bytes, ctx)
end
remove_by_value_relative_rank_range(value, rank, bin, ctx: nil, count: nil) click to toggle source

Create expression that removes list items nearest to value and greater by relative rank with a count limit if provided.

Examples for ordered list [0,4,5,9,11,15]:

(value,rank,count) = [removed items] (5,0,2) = [5,9] (5,1,1) = [9] (5,-1,2) = [4,5] (3,0,1) = [4] (3,3,7) = [11,15] (3,-3,2) = []

# File lib/aerospike/exp/exp_list.rb, line 134
def self.remove_by_value_relative_rank_range(value, rank, bin, ctx: nil, count: nil)
  bytes = if count.nil?
    Exp.pack(ctx, REMOVE_BY_VALUE_REL_RANK_RANGE, CDT::ListReturnType::NONE, value, rank)
          else
    Exp.pack(ctx, REMOVE_BY_VALUE_REL_RANK_RANGE, CDT::ListReturnType::NONE, value, rank, count)
          end
  add_write(bin, bytes, ctx)
end
set(index, value, bin, ctx: nil, policy: CDT::ListPolicy::DEFAULT) click to toggle source

Create expression that sets item value at specified index in list.

# File lib/aerospike/exp/exp_list.rb, line 82
def self.set(index, value, bin, ctx: nil, policy: CDT::ListPolicy::DEFAULT)
  bytes = Exp.pack(ctx, SET, index, value, policy.flags)
  add_write(bin, bytes, ctx)
end
size(bin, ctx: nil) click to toggle source

Create expression that returns list size.

Examples

# List bin “a” size > 7 Exp.gt(ListExp.size(Exp.listBin(“a”)), Exp.val(7)) end</pre>

# File lib/aerospike/exp/exp_list.rb, line 181
def self.size(bin, ctx: nil)
  bytes = Exp.pack(ctx, SIZE)
  add_read(bin, bytes, Exp::Type::INT)
end
sort(sort_flags, bin, ctx: nil) click to toggle source

Create expression that sorts list according to sort_flags.

@param sort_flags sort flags. See {ListSortFlagsend. @param bin bin or list value expression @param ctx optional context path for nested CDT

# File lib/aerospike/exp/exp_list.rb, line 98
def self.sort(sort_flags, bin, ctx: nil)
  bytes = Exp.pack(ctx, SORT, sort_flags)
  add_write(bin, bytes, ctx)
end