123456789_123456789_123456789_123456789_123456789_

Module: Redis::Commands::Lists

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

Instance Method Summary

Instance Method Details

#_bpop(cmd, args, &blk) (private)

[ GitHub ] 

  


# File 'lib/redis/commands/lists.rb', line 306



def _bpop(cmd, args, &blk)
  timeout = if args.last.is_a?(Hash)
    options = args.pop
    options[:timeout]
  end

  timeout ||= 0
  unless timeout.is_a?(Integer) || timeout.is_a?(Float)
    raise ArgumentError, "timeout must be an Integer or Float, got: #{timeout.class}"
  end

  args.flatten!(1)
  command = [cmd].concat(args)
  command << timeout
  send_blocking_command(command, timeout, &blk)
end


  








  

    #_normalize_move_wheres(where_source, where_destination)   (private)
  

  [ GitHub ]


  

  


# File 'lib/redis/commands/lists.rb', line 323



def _normalize_move_wheres(where_source, where_destination)
  where_source      = where_source.to_s.upcase
  where_destination = where_destination.to_s.upcase

  if where_source != "LEFT" && where_source != "RIGHT"
    raise ArgumentError, "where_source must be 'LEFT' or 'RIGHT'"
  end

  if where_destination != "LEFT" && where_destination != "RIGHT"
    raise ArgumentError, "where_destination must be 'LEFT' or 'RIGHT'"
  end

  [where_source, where_destination]
end


  








  

    #blmove(source, destination, where_source, where_destination, timeout: 0)  ⇒ nil, String 
  



  

    
Remove the first/last element in a list and append/prepend it
to another list and return it, or block until one is available.


  





    

    
Examples:

        
With timeout



      
element = redis.blmove("foo", "bar", "LEFT", "RIGHT", timeout: 5)
  # => nil on timeout
  # => "element" on success

        
Without timeout



      
element = redis.blmove("foo", "bar", "LEFT", "RIGHT")
  # => "element"

  


Parameters:


    
  
  • 
    source
    (String)
—    
    source key
    

    
  
    • 
  
  • 
    destination
    (String)
—    
    destination key
    

    
  
    • 
  
  • 
    where_source
    (String, Symbol)
—    
    from where to remove the element from the source list
e.g. 'LEFT' - from head, 'RIGHT' - from tail
    

    
  
    • 
  
  • 
    where_destination
    (String, Symbol)
—    
    where to push the element to the source list
e.g. 'LEFT' - to head, 'RIGHT' - to tail
    

    
  
    • 
  
  • 
    options
    (Hash)
—    
      

    • :timeout => [Float, Integer]: timeout in seconds, defaults to no timeout
      • 

    

    
  
    • 



Returns:


    
  
  • 
    (nil, String)
—    
    the element, or nil when the source key does not exist or the timeout expired
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/lists.rb', line 55



def blmove(source, destination, where_source, where_destination, timeout: 0)
  where_source, where_destination = _normalize_move_wheres(where_source, where_destination)

  command = [:blmove, source, destination, where_source, where_destination, timeout]
  send_blocking_command(command, timeout)
end


  








  

    #blmpop(timeout, *keys, modifier: "LEFT", count: nil)  ⇒ Array<String, Array<String, Float>> 
  



  

    
Pops one or more elements from the first non-empty list key from the list
of provided key names. If lists are empty, blocks until timeout has passed.


  





    

    
Examples:

        
Popping a element



      
redis.blmpop(1.0, 'list')
#=> ['list', ['a']]

        
With count option



      
redis.blmpop(1.0, 'list', count: 2)
#=> ['list', ['a', 'b']]

  


Returns:


    
  
  • 
    (Array<String, Array<String, Float>>)
—    
    list of popped elements or nil
    

    
  
    • 



Raises:


    
  
  • 
    (ArgumentError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/lists.rb', line 205



def blmpop(timeout, *keys, modifier: "LEFT", count: nil)
  raise ArgumentError, "Pick either LEFT or RIGHT" unless modifier == "LEFT" || modifier == "RIGHT"

  args = [:lmpop, keys.size, *keys, modifier]
  args << "COUNT" << Integer(count) if count

  send_blocking_command(args, timeout)
end


  








  

    #blpop(*args)  ⇒ nil, [String, String] 
  



  

    
Remove and get the first element in a list, or block until one is available.


  





    

    
Examples:

        
With timeout



      
list, element = redis.blpop("list", :timeout => 5)
  # => nil on timeout
  # => ["list", "element"] on success

        
Without timeout



      
list, element = redis.blpop("list")
  # => ["list", "element"]

        
Blocking pop on multiple lists



      
list, element = redis.blpop(["list", "another_list"])
  # => ["list", "element"]

  


Parameters:


    
  
  • 
    keys
    (String, Array<String>)
—    
    one or more keys to perform the
blocking pop on
    

    
  
    • 
  
  • 
    options
    (Hash)
—    
      

    • :timeout => [Float, Integer]: timeout in seconds, defaults to no timeout
      • 

    

    
  
    • 



Returns:


    
  
  • 
    (nil, [String, String])
—    
      

    • nil when the operation timed out
      • 

    • tuple of the list that was popped from and element was popped otherwise
      • 

    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/lists.rb', line 150



def blpop(*args)
  _bpop(:blpop, args)
end


  








  

    #brpop(*args)  ⇒ nil, [String, String] 
  



  

    
Remove and get the last element in a list, or block until one is available.


  





  
Parameters:


    
  
  • 
    keys
    (String, Array<String>)
—    
    one or more keys to perform the
blocking pop on
    

    
  
    • 
  
  • 
    options
    (Hash)
—    
      

    • :timeout => [Float, Integer]: timeout in seconds, defaults to no timeout
      • 

    

    
  
    • 



Returns:


    
  
  • 
    (nil, [String, String])
—    
      

    • nil when the operation timed out
      • 

    • tuple of the list that was popped from and element was popped otherwise
      • 

    

    
  
    • 


  
See Also:

  



  [ GitHub ]


  

  


# File 'lib/redis/commands/lists.rb', line 166



def brpop(*args)
  _bpop(:brpop, args)
end


  








  

    #brpoplpush(source, destination, timeout: 0)  ⇒ nil, String 
  



  

    
Pop a value from a list, push it to another list and return it; or block
until one is available.


  





  
Parameters:


    
  
  • 
    source
    (String)
—    
    source key
    

    
  
    • 
  
  • 
    destination
    (String)
—    
    destination key
    

    
  
    • 
  
  • 
    options
    (Hash)
—    
      

    • :timeout => [Float, Integer]: timeout in seconds, defaults to no timeout
      • 

    

    
  
    • 



Returns:


    
  
  • 
    (nil, String)
—    
      

    • nil when the operation timed out
      • 

    • the element was popped and pushed otherwise
      • 

    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/lists.rb', line 181



def brpoplpush(source, destination, timeout: 0)
  command = [:brpoplpush, source, destination, timeout]
  send_blocking_command(command, timeout)
end


  








  

    #lindex(key, index)  ⇒ String 
  



  

    
Get an element from a list by its index.


  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    index
    (Integer)
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/lists.rb', line 245



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


  








  

    #linsert(key, where, pivot, value)  ⇒ Integer 
  



  

    
Insert an element before or after another element in a list.


  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    where
    (String, Symbol)
—    
    BEFORE or AFTER
    

    
  
    • 
  
  • 
    pivot
    (String)
—    
    reference element
    

    
  
    • 
  
  • 
    value
    (String)
  
    • 



Returns:


    
  
  • 
    (Integer)
—    
    length of the list after the insert operation, or -1
when the element pivot was not found
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/lists.rb', line 257



def linsert(key, where, pivot, value)
  send_command([:linsert, key, where, pivot, value])
end


  








  

    #llen(key)  ⇒ Integer 
  



  

    
Get the length of a list.


  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/lists.rb', line 10



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


  








  

    #lmove(source, destination, where_source, where_destination)  ⇒ nil, String 
  



  

    
  

    Note:
    
This command comes in place of the now deprecated RPOPLPUSH.
Doing LMOVE RIGHT LEFT is equivalent.



  



Remove the first/last element in a list, append/prepend it to another list and return it.


  





  
Parameters:


    
  
  • 
    source
    (String)
—    
    source key
    

    
  
    • 
  
  • 
    destination
    (String)
—    
    destination key
    

    
  
    • 
  
  • 
    where_source
    (String, Symbol)
—    
    from where to remove the element from the source list
e.g. 'LEFT' - from head, 'RIGHT' - from tail
    

    
  
    • 
  
  • 
    where_destination
    (String, Symbol)
—    
    where to push the element to the source list
e.g. 'LEFT' - to head, 'RIGHT' - to tail
    

    
  
    • 



Returns:


    
  
  • 
    (nil, String)
—    
    the element, or nil when the source key does not exist
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/lists.rb', line 27



def lmove(source, destination, where_source, where_destination)
  where_source, where_destination = _normalize_move_wheres(where_source, where_destination)

  send_command([:lmove, source, destination, where_source, where_destination])
end


  








  

    #lmpop(*keys, modifier: "LEFT", count: nil)  ⇒ Array<String, Array<String, Float>> 
  



  

    
Pops one or more elements from the first non-empty list key from the list
of provided key names.


  





    

    
Examples:

        
Popping a element



      
redis.lmpop('list')
#=> ['list', ['a']]

        
With count option



      
redis.lmpop('list', count: 2)
#=> ['list', ['a', 'b']]

  


Returns:


    
  
  • 
    (Array<String, Array<String, Float>>)
—    
    list of popped elements or nil
    

    
  
    • 



Raises:


    
  
  • 
    (ArgumentError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/lists.rb', line 231



def lmpop(*keys, modifier: "LEFT", count: nil)
  raise ArgumentError, "Pick either LEFT or RIGHT" unless modifier == "LEFT" || modifier == "RIGHT"

  args = [:lmpop, keys.size, *keys, modifier]
  args << "COUNT" << Integer(count) if count

  send_command(args)
end


  








  

    #lpop(key, count = nil)  ⇒ nil, ... 
  



  

    
Remove and get the first elements in a list.


  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    count
    (Integer)
    (defaults to: nil)
—    
    number of elements to remove
    

    
  
    • 



Returns:


    
  
  • 
    (nil, String, Array<String>)
—    
    the values of the first elements
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/lists.rb', line 103



def lpop(key, count = nil)
  command = [:lpop, key]
  command << Integer(count) if count
  send_command(command)
end


  








  

    #lpush(key, value)  ⇒ Integer 
  



  

    
Prepend one or more values to a list, creating the list if it doesn't exist


  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    value
    (String, Array<String>)
—    
    string value, or array of string values to push
    

    
  
    • 



Returns:


    
  
  • 
    (Integer)
—    
    the length of the list after the push operation
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/lists.rb', line 67



def lpush(key, value)
  send_command([:lpush, key, value])
end


  








  

    #lpushx(key, value)  ⇒ Integer 
  



  

    
Prepend a value to a list, only if the list exists.


  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    value
    (String)
  
    • 



Returns:


    
  
  • 
    (Integer)
—    
    the length of the list after the push operation
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/lists.rb', line 76



def lpushx(key, value)
  send_command([:lpushx, key, value])
end


  








  

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



  

    
Get a range of elements from a list.


  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    start
    (Integer)
—    
    start index
    

    
  
    • 
  
  • 
    stop
    (Integer)
—    
    stop index
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/lists.rb', line 267



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


  








  

    #lrem(key, count, value)  ⇒ Integer 
  



  

    
Remove elements from a list.


  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    count
    (Integer)
—    
    number of elements to remove. Use a positive
value to remove the first count occurrences of value. A negative
value to remove the last count occurrences of value. Or zero, to
remove all occurrences of value from the list.
    

    
  
    • 
  
  • 
    value
    (String)
  
    • 



Returns:


    
  
  • 
    (Integer)
—    
    the number of removed elements
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/lists.rb', line 280



def lrem(key, count, value)
  send_command([:lrem, key, Integer(count), value])
end


  








  

    #lset(key, index, value)  ⇒ String 
  



  

    
Set the value of an element in a list by its index.


  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    index
    (Integer)
  
    • 
  
  • 
    value
    (String)
  
    • 



Returns:


    
  
  • 
    (String)
—    
    OK
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/lists.rb', line 290



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


  








  

    #ltrim(key, start, stop)  ⇒ String 
  



  

    
Trim a list to the specified range.


  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    start
    (Integer)
—    
    start index
    

    
  
    • 
  
  • 
    stop
    (Integer)
—    
    stop index
    

    
  
    • 



Returns:


    
  
  • 
    (String)
—    
    OK
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/lists.rb', line 300



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


  








  

    #rpop(key, count = nil)  ⇒ nil, ... 
  



  

    
Remove and get the last elements in a list.


  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    count
    (Integer)
    (defaults to: nil)
—    
    number of elements to remove
    

    
  
    • 



Returns:


    
  
  • 
    (nil, String, Array<String>)
—    
    the values of the last elements
    

    
  
    • 





  [ GitHub ]


  

  


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



def rpop(key, count = nil)
  command = [:rpop, key]
  command << Integer(count) if count
  send_command(command)
end


  








  

    #rpoplpush(source, destination)  ⇒ nil, String 
  



  

    
Remove the last element in a list, append it to another list and return it.


  





  
Parameters:


    
  
  • 
    source
    (String)
—    
    source key
    

    
  
    • 
  
  • 
    destination
    (String)
—    
    destination key
    

    
  
    • 



Returns:


    
  
  • 
    (nil, String)
—    
    the element, or nil when the source key does not exist
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/lists.rb', line 125



def rpoplpush(source, destination)
  send_command([:rpoplpush, source, destination])
end


  








  

    #rpush(key, value)  ⇒ Integer 
  



  

    
Append one or more values to a list, creating the list if it doesn't exist


  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    value
    (String, Array<String>)
—    
    string value, or array of string values to push
    

    
  
    • 



Returns:


    
  
  • 
    (Integer)
—    
    the length of the list after the push operation
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/lists.rb', line 85



def rpush(key, value)
  send_command([:rpush, key, value])
end


  








  

    #rpushx(key, value)  ⇒ Integer 
  



  

    
Append a value to a list, only if the list exists.


  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    value
    (String)
  
    • 



Returns:


    
  
  • 
    (Integer)
—    
    the length of the list after the push operation
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/lists.rb', line 94



def rpushx(key, value)
  send_command([:rpushx, key, value])
end