123456789_123456789_123456789_123456789_123456789_

Module: Redis::Commands::Arrays

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Included In:
::Redis, ::Redis::Commands, ::Redis::MultiConnection, ::Redis::PipelinedConnection
Defined in: lib/redis/commands/arrays.rb

Instance Method Summary

Instance Method Details

#arcount(key) ⇒ Integer

Get the number of non-empty elements in an array.

Parameters:

  • key (String)

Returns:

  • (Integer) —

    the number of set elements, or 0 if the key does not exist

[ GitHub ] 

  


# File 'lib/redis/commands/arrays.rb', line 130



def arcount(key)
  send_command([:arcount, key])
end


  








  

    #ardel(key, *indices)  ⇒ Integer 
  



  

    
Delete elements at the specified indices in an array.


Deleting an index that is not set counts as zero elements deleted and
does not modify the array.

  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    indices
    (Integer, Array<Integer>)
—    
    one or more zero-based indices to delete
    
  
    • 



Returns:


    
  
  • 
    (Integer)
—    
    the number of elements deleted
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/arrays.rb', line 142



def ardel(key, *indices)
  indices = indices.flatten(1).map { |index| Integer(index) }
  send_command([:ardel, key, *indices])
end


  








  

    #ardelrange(key, *ranges)  ⇒ Integer 
  



  

    
Delete elements in one or more inclusive index ranges.


Ranges may overlap; each element is counted at most once. A range
given with start > stop is processed in ascending order regardless.

  





    

    
Examples:

        
Delete two ranges

      
redis.ardelrange("foo", 0, 2, 5, 7)
  # => 6

        
Ranges as pairs

      
redis.ardelrange("foo", [0, 2], [5, 7])
  # => 6

  


Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    ranges
    (Integer, Array<Integer>)
—    
    one or more start/stop pairs,
as flat alternating integers or one array per range
    
  
    • 



Returns:


    
  
  • 
    (Integer)
—    
    the number of elements deleted
    
  
    • 



Raises:


    
  
  • 
    (ArgumentError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/arrays.rb', line 163



def ardelrange(key, *ranges)
  ranges = ranges.flatten(1).map { |index| Integer(index) }
  raise ArgumentError, "ranges must be given as start/stop pairs" if ranges.empty? || ranges.size.odd?

  send_command([:ardelrange, key, *ranges])
end


  








  

    #arget(key, index)  ⇒ String? 
  



  

    
Get the value at an index in an array.

  





    

    
Examples:

      
redis.arget("foo", 0)
  # => "a"

        
A missing key, an empty slot or an index past the end

      
redis.arget("foo", 99)
  # => nil

  


Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    index
    (Integer)
—    
    zero-based index of the element to retrieve
    
  
    • 



Returns:


    
  
  • 
    (String, nil)
—    
    the value at the given index, or nil if the
key does not exist or the index holds no value
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/arrays.rb', line 42



def arget(key, index)
  send_command([:arget, key, Integer(index)])
end


  








  

    #argetrange(key, start, stop)  ⇒ Array<String, nil> 
  



  

    
Get values in a range of indices.


Empty slots inside the range are returned as nil. When start is
greater than stop, elements are returned in reverse index order.

  





    

    
Examples:

      
redis.argetrange("foo", 0, 2)
  # => ["a", nil, "c"]

        
Reverse order

      
redis.argetrange("foo", 2, 0)
  # => ["c", nil, "a"]

  


Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    start
    (Integer)
—    
    zero-based index of the first element (inclusive)
    
  
    • 
  
  • 
    stop
    (Integer)
—    
    zero-based index of the last element (inclusive)
    
  
    • 



Returns:


    
  
  • 
    (Array<String, nil>)
—    
    the values in traversal order
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/arrays.rb', line 114



def argetrange(key, start, stop)
  send_command([:argetrange, key, Integer(start), Integer(stop)])
end


  








  

    #argrep(key, start, stop, exact: nil, match: nil, glob: nil, re: nil, logic: nil, limit: nil, with_values: nil, nocase: nil)  ⇒ Array<Integer>, Array<Array(Integer, String)> 
  



  

    
Search array elements within an inclusive index range using one or
more textual predicates. Empty slots are skipped.


Each predicate keyword accepts a single value or an array of values;
multiple predicates are combined with logic: (:or by default).

  





    

    
Examples:

        
Substring search

      
redis.argrep("foo", 0, 9, match: "an")
  # => [1, 2]

        
Combined predicates with values

      
redis.argrep("foo", 0, 9, glob: "a*", exact: "cherry", logic: :or, with_values: true)
  # => [[0, "apple"], [2, "cherry"]]

  


Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    start
    (Integer, String)
—    
    zero-based start index (inclusive), or
"-" for the start of the array; iteration is reversed when greater
than stop
    
  
    • 
  
  • 
    stop
    (Integer, String)
—    
    zero-based end index (inclusive), or
"+" for the end of the array
    
  
    • 
  
  • 
    exact
    (String, Array<String>)
—    
    match by exact equality
    
  
    • 
  
  • 
    match
    (String, Array<String>)
—    
    match by substring
    
  
    • 
  
  • 
    glob
    (String, Array<String>)
—    
    match by glob-style pattern (*, ?, [...])
    
  
    • 
  
  • 
    re
    (String, Array<String>)
—    
    match by regular expression
    
  
    • 
  
  • 
    logic
    (Symbol)
—    
    :and or :or — how multiple predicates combine (server default is OR)
    
  
    • 
  
  • 
    limit
    (Integer)
—    
    stop after this many matches
    
  
    • 
  
  • 
    with_values
    (Boolean)
—    
    return [index, value] pairs instead of indices
    
  
    • 
  
  • 
    nocase
    (Boolean)
—    
    case-insensitive comparison for all predicates
    
  
    • 



Returns:


    
  
  • 
    (Array<Integer>, Array<Array(Integer, String)>)
—    
    matching
indices in traversal order, or [index, value] pairs with with_values
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/arrays.rb', line 278



def argrep(key, start, stop, exact: nil, match: nil, glob: nil, re: nil,
           logic: nil, limit: nil, with_values: nil, nocase: nil)
  args = [:argrep, key, argrep_bound(start), argrep_bound(stop)]
  { "EXACT" => exact, "MATCH" => match, "GLOB" => glob, "RE" => re }.each do |predicate, values|
    Array(values).each { |value| args << predicate << value }
  end
  if logic
    operator = logic.to_s.upcase
    raise ArgumentError, "logic must be :and or :or" unless %w[AND OR].include?(operator)

    args << operator
  end
  args << "LIMIT" << Integer(limit) if limit
  args << "WITHVALUES" if with_values
  args << "NOCASE" if nocase
  send_command(args)
end


  








  

    #argrep_bound(index)   (private)
  



  

    
ARGREP accepts "-" / "+" as full-range bounds — unlike the other AR*
range commands, which take numeric indices only (verified on ::Redis
8.8). Anything else is coerced so typos still fail fast client-side.

  



  [ GitHub ]


  

  


# File 'lib/redis/commands/arrays.rb', line 353



def argrep_bound(index)
  index == "-" || index == "+" ? index : Integer(index)
end


  








  

    #arinfo(key, full: false)  ⇒ Hash{String => Integer, Float} 
  



  

    
Get metadata about an array.

  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    full
    (Boolean)
—    
    include per-slice statistics
    
  
    • 



Returns:


    
  
  • 
    (Hash{String => Integer, Float})
—    
    metadata fields such as
count, len, next-insert-index and slices; with full: the
avg-* slice statistics are returned as Float
    
  
    • 



Raises:





  [ GitHub ]


  

  


# File 'lib/redis/commands/arrays.rb', line 342



def arinfo(key, full: false)
  args = [:arinfo, key]
  args << "FULL" if full
  send_command(args, &HashifyArrayInfo)
end


  








  

    #arinsert(key, *values)  ⇒ Integer 
  



  

    
Insert one or more values at consecutive indices, beginning at the
array's insert cursor. The cursor advances by one for each value.

  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    values
    (String)
—    
    one or more values to insert
    
  
    • 



Returns:


    
  
  • 
    (Integer)
—    
    the last index where a value was inserted
    
  
    • 


  
See Also:

  



  [ GitHub ]


  

  


# File 'lib/redis/commands/arrays.rb', line 179



def arinsert(key, *values)
  send_command([:arinsert, key, *values])
end


  








  

    #arlastitems(key, count, rev: false)  ⇒ Array<String> 
  



  

    
Get the most recently inserted elements.

  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    count
    (Integer)
—    
    maximum number of elements to return; if the
array holds fewer elements, all of them are returned
    
  
    • 
  
  • 
    rev
    (Boolean)
—    
    return elements most recent first instead of the
default oldest-first order
    
  
    • 



Returns:


    
  
  • 
    (Array<String>)
—    
    the most recently inserted elements
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/arrays.rb', line 209



def arlastitems(key, count, rev: false)
  args = [:arlastitems, key, Integer(count)]
  args << "REV" if rev
  send_command(args)
end


  








  

    #arlen(key)  ⇒ Integer 
  



  

    
Get the length of an array (max index + 1).

  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 



Returns:


    
  
  • 
    (Integer)
—    
    the array length, or 0 if the key does not exist
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/arrays.rb', line 122



def arlen(key)
  send_command([:arlen, key])
end


  








  

    #armget(key, *indices)  ⇒ Array<String, nil> 
  



  

    
Get values at multiple indices in an array.


The reply preserves the order of the requested indices and contains
nil for any index that is not set.

  





    

    
Examples:

      
redis.armget("foo", 0, 1, 9)
  # => ["a", "b", nil]

        
With an array of indices

      
redis.armget("foo", [0, 1, 9])
  # => ["a", "b", nil]

  


Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    indices
    (Integer, Array<Integer>)
—    
    one or more zero-based indices
    
  
    • 



Returns:


    
  
  • 
    (Array<String, nil>)
—    
    the values at the requested indices
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/arrays.rb', line 93



def armget(key, *indices)
  indices = indices.flatten(1).map { |index| Integer(index) }
  send_command([:armget, key, *indices])
end


  








  

    #armset(key, *pairs)  ⇒ Integer 
  



  

    
Set multiple index-value pairs in an array.


Pairs may be non-contiguous and given in any order, as a flat list or
a Hash.

  





    

    
Examples:

        
With a flat list of pairs

      
redis.armset("foo", 0, "a", 5, "f")
  # => 2

        
With an array (flat, or one array per pair)

      
redis.armset("foo", [0, "a"], [5, "f"])
  # => 2

        
With a Hash

      
redis.armset("foo", { 0 => "a", 5 => "f" })
  # => 2

  


Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    pairs
    (Integer, String, Array<Integer, String>, Array<Array(Integer, String)>, Hash{Integer => String})
—    
    index-value pairs — as alternating
index/value arguments, a single flat array, one array per pair, or a Hash
    
  
    • 



Returns:


    
  
  • 
    (Integer)
—    
    the number of previously empty slots that were set
    
  
    • 



Raises:


    
  
  • 
    (ArgumentError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/arrays.rb', line 66



def armset(key, *pairs)
  pairs = if pairs.size == 1 && pairs.first.is_a?(Hash)
    pairs.first.flatten
  else
    pairs.flatten(1)
  end
  raise ArgumentError, "wrong number of arguments" if pairs.empty? || pairs.size.odd?

  args = pairs.each_slice(2).flat_map { |index, value| [Integer(index), value] }
  send_command([:armset, key, *args])
end


  








  

    #arnext(key)  ⇒ Integer? 
  



  

    
Get the next index #arinsert would use.

  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 



Returns:


    
  
  • 
    (Integer, nil)
—    
    the next insert index (0 for missing keys or
before any insert), or nil when the insertion cursor is exhausted
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/arrays.rb', line 197



def arnext(key)
  send_command([:arnext, key])
end


  








  

    #arop(key, start, stop, operation, value: nil)  ⇒ Float, ... 
  



  

    
Perform an aggregate operation on the non-empty elements in a range.


Supported operations: :sum, :min, :max (numeric, returned as
Float), :and, :or, :xor (bitwise, floats truncated toward
zero), :match (count of elements equal to value) and :used
(count of non-empty elements).

  





    

    
Examples:

      
redis.arop("foo", 0, 9, :sum)
  # => 6.0

        
Count elements equal to a value

      
redis.arop("foo", 0, 9, :match, value: "2")
  # => 1

  


Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    start
    (Integer)
—    
    zero-based index of the first element (inclusive);
the range is always scanned from the lower to the higher index
    
  
    • 
  
  • 
    stop
    (Integer)
—    
    zero-based index of the last element (inclusive)
    
  
    • 
  
  • 
    operation
    (Symbol, String)
—    
    one of :sum, :min, :max,
:and, :or, :xor, :match, :used
    
  
    • 
  
  • 
    value
    (String)
—    
    the value to compare against (required for :match)
    
  
    • 



Returns:


    
  
  • 
    (Float, Integer, nil)
—    
    the aggregate result — a Float for
:sum/:min/:max, an Integer otherwise; nil when no elements
qualify
    
  
    • 



Raises:


    
  
  • 
    (ArgumentError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/arrays.rb', line 320



def arop(key, start, stop, operation, value: nil)
  operation = operation.to_s.upcase
  raise ArgumentError, "value is required for the MATCH operation" if operation == "MATCH" && value.nil?

  args = [:arop, key, Integer(start), Integer(stop), operation]
  args << value if operation == "MATCH"

  if %w[SUM MIN MAX].include?(operation)
    send_command(args, &Floatify)
  else
    send_command(args)
  end
end


  








  

    #arring(key, size, *values)  ⇒ Integer 
  



  

    
Insert one or more values into an array used as a fixed-size ring
buffer. Each value is placed at the next position in the ring and the
cursor advances, wrapping around to index 0 once the ring is full.

  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    size
    (Integer)
—    
    the size of the ring buffer window
    
  
    • 
  
  • 
    values
    (String)
—    
    one or more values to insert
    
  
    • 



Returns:


    
  
  • 
    (Integer)
—    
    the last index where a value was inserted
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/arrays.rb', line 223



def arring(key, size, *values)
  send_command([:arring, key, Integer(size), *values])
end


  








  

    #arscan(key, start, stop, limit: nil)  ⇒ Array<Array(Integer, String)> 
  



  

    
Iterate existing elements in an index range.


Empty slots are excluded. When start is greater than stop the
iteration is reversed.

  





    

    
Examples:

      
redis.arscan("foo", 0, 9)
  # => [[0, "a"], [3, "d"]]

  


Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    start
    (Integer)
—    
    zero-based start index (inclusive)
    
  
    • 
  
  • 
    stop
    (Integer)
—    
    zero-based end index (inclusive)
    
  
    • 
  
  • 
    limit
    (Integer)
—    
    cap on the number of elements returned;
all populated elements in range are returned when omitted
    
  
    • 



Returns:


    
  
  • 
    (Array<Array(Integer, String)>)
—    
    [index, value] pairs in
traversal order; empty when the key does not exist
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/arrays.rb', line 243



def arscan(key, start, stop, limit: nil)
  args = [:arscan, key, Integer(start), Integer(stop)]
  args << "LIMIT" << Integer(limit) if limit
  send_command(args)
end


  








  

    #arseek(key, index)  ⇒ Boolean 
  



  

    
Set the insert cursor of an array to a specific index.

  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    index
    (Integer)
—    
    zero-based index for the new cursor position
    
  
    • 



Returns:


    
  
  • 
    (Boolean)
—    
    whether the cursor was set (false if the key does not exist)
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/arrays.rb', line 188



def arseek(key, index)
  send_command([:arseek, key, Integer(index)], &Boolify)
end


  








  

    #arset(key, index, *values)  ⇒ Integer 
  



  

    
Set one or more contiguous values starting at an index in an array.


When multiple values are given they are stored at consecutive indices
beginning at index. Writing past the current end of the array
extends it; slots that are skipped over stay empty. Only non-negative
indices are valid.

  





    

    
Examples:

        
Set two values at the head of the array

      
redis.arset("foo", 0, "a", "b")
  # => 2

        
Overwrite an existing slot (no new slot is filled)

      
redis.arset("foo", 1, "B")
  # => 0

  


Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    index
    (Integer)
—    
    zero-based index at which to start writing
    
  
    • 
  
  • 
    values
    (String)
—    
    one or more values stored at consecutive
indices beginning at index
    
  
    • 



Returns:


    
  
  • 
    (Integer)
—    
    the number of previously empty slots that were set
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/arrays.rb', line 25



def arset(key, index, *values)
  send_command([:arset, key, Integer(index), *values])
end