module Redis::Commands::Lists

Public Instance Methods

blmove(source, destination, where_source, where_destination, timeout: 0) click to toggle source

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

@example With timeout

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

@example Without timeout

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

@param [String] source source key @param [String] destination destination key @param [String, Symbol] where_source from where to remove the element from the source list

e.g. 'LEFT' - from head, 'RIGHT' - from tail

@param [String, Symbol] where_destination where to push the element to the source list

e.g. 'LEFT' - to head, 'RIGHT' - to tail

@param [Hash] options

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

@return [nil, String] the element, or nil when the source key does not exist or the timeout expired

# 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
blpop(*args) click to toggle source

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

@example With timeout

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

@example Without timeout

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

@example Blocking pop on multiple lists

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

@param [String, Array<String>] keys one or more keys to perform the

blocking pop on

@param [Hash] options

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

@return [nil, [String, String]]

- `nil` when the operation timed out
- tuple of the list that was popped from and element was popped otherwise
# File lib/redis/commands/lists.rb, line 150
def blpop(*args)
  _bpop(:blpop, args)
end
brpop(*args) click to toggle source

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

@param [String, Array<String>] keys one or more keys to perform the

blocking pop on

@param [Hash] options

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

@return [nil, [String, String]]

- `nil` when the operation timed out
- tuple of the list that was popped from and element was popped otherwise

@see blpop

# File lib/redis/commands/lists.rb, line 166
def brpop(*args)
  _bpop(:brpop, args)
end
brpoplpush(source, destination, timeout: 0) click to toggle source

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

@param [String] source source key @param [String] destination destination key @param [Hash] options

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

@return [nil, String]

- `nil` when the operation timed out
- the element was popped and pushed otherwise
# 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) click to toggle source

Get an element from a list by its index.

@param [String] key @param [Integer] index @return [String]

# File lib/redis/commands/lists.rb, line 191
def lindex(key, index)
  send_command([:lindex, key, Integer(index)])
end
linsert(key, where, pivot, value) click to toggle source

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

@param [String] key @param [String, Symbol] where ‘BEFORE` or `AFTER` @param [String] pivot reference element @param [String] value @return [Integer] length of the list after the insert operation, or `-1`

when the element `pivot` was not found
# File lib/redis/commands/lists.rb, line 203
def linsert(key, where, pivot, value)
  send_command([:linsert, key, where, pivot, value])
end
llen(key) click to toggle source

Get the length of a list.

@param [String] key @return [Integer]

# File lib/redis/commands/lists.rb, line 10
def llen(key)
  send_command([:llen, key])
end
lmove(source, destination, where_source, where_destination) click to toggle source

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

@param [String] source source key @param [String] destination destination key @param [String, Symbol] where_source from where to remove the element from the source list

e.g. 'LEFT' - from head, 'RIGHT' - from tail

@param [String, Symbol] where_destination where to push the element to the source list

e.g. 'LEFT' - to head, 'RIGHT' - to tail

@return [nil, String] the element, or nil when the source key does not exist

@note This command comes in place of the now deprecated RPOPLPUSH.

Doing LMOVE RIGHT LEFT is equivalent.
# 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
lpop(key, count = nil) click to toggle source

Remove and get the first elements in a list.

@param [String] key @param [Integer] count number of elements to remove @return [nil, String, Array<String>] the values of the first elements

# 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) click to toggle source

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

@param [String] key @param [String, Array<String>] value string value, or array of string values to push @return [Integer] the length of the list after the push operation

# File lib/redis/commands/lists.rb, line 67
def lpush(key, value)
  send_command([:lpush, key, value])
end
lpushx(key, value) click to toggle source

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

@param [String] key @param [String] value @return [Integer] the length of the list after the push operation

# File lib/redis/commands/lists.rb, line 76
def lpushx(key, value)
  send_command([:lpushx, key, value])
end
lrange(key, start, stop) click to toggle source

Get a range of elements from a list.

@param [String] key @param [Integer] start start index @param [Integer] stop stop index @return [Array<String>]

# File lib/redis/commands/lists.rb, line 213
def lrange(key, start, stop)
  send_command([:lrange, key, Integer(start), Integer(stop)])
end
lrem(key, count, value) click to toggle source

Remove elements from a list.

@param [String] key @param [Integer] count 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.

@param [String] value @return [Integer] the number of removed elements

# File lib/redis/commands/lists.rb, line 226
def lrem(key, count, value)
  send_command([:lrem, key, Integer(count), value])
end
lset(key, index, value) click to toggle source

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

@param [String] key @param [Integer] index @param [String] value @return [String] ‘OK`

# File lib/redis/commands/lists.rb, line 236
def lset(key, index, value)
  send_command([:lset, key, Integer(index), value])
end
ltrim(key, start, stop) click to toggle source

Trim a list to the specified range.

@param [String] key @param [Integer] start start index @param [Integer] stop stop index @return [String] ‘OK`

# File lib/redis/commands/lists.rb, line 246
def ltrim(key, start, stop)
  send_command([:ltrim, key, Integer(start), Integer(stop)])
end
rpop(key, count = nil) click to toggle source

Remove and get the last elements in a list.

@param [String] key @param [Integer] count number of elements to remove @return [nil, String, Array<String>] the values of the last elements

# 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) click to toggle source

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

@param [String] source source key @param [String] destination destination key @return [nil, String] the element, or nil when the source key does not exist

# File lib/redis/commands/lists.rb, line 125
def rpoplpush(source, destination)
  send_command([:rpoplpush, source, destination])
end
rpush(key, value) click to toggle source

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

@param [String] key @param [String, Array<String>] value string value, or array of string values to push @return [Integer] the length of the list after the push operation

# File lib/redis/commands/lists.rb, line 85
def rpush(key, value)
  send_command([:rpush, key, value])
end
rpushx(key, value) click to toggle source

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

@param [String] key @param [String] value @return [Integer] the length of the list after the push operation

# File lib/redis/commands/lists.rb, line 94
def rpushx(key, value)
  send_command([:rpushx, key, value])
end

Private Instance Methods

_bpop(cmd, args, &blk) click to toggle source
# File lib/redis/commands/lists.rb, line 252
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) click to toggle source
# File lib/redis/commands/lists.rb, line 269
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