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

#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.
#blmovem(source, destination, where_source, where_destination, timeout: 0, count: nil, exactly: nil, order: nil) ⇒ nil, Array<String>

Remove multiple elements from the head/tail of a list, append/prepend them to another list and return them; or block until the request can be satisfied or the timeout expires.
#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.
#blpop(*args) ⇒ nil, [String, String]

Remove and get the first element in a list, or block until one is available.
#brpop(*args) ⇒ nil, [String, String]

Remove and get the last element in a list, or block until one is available.
#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.
#lindex(key, index) ⇒ String

Get an element from a list by its index.
#linsert(key, where, pivot, value) ⇒ Integer

Insert an element before or after another element in a list.
#llen(key) ⇒ Integer

Get the length of a list.
#lmove(source, destination, where_source, where_destination) ⇒ nil, String

Remove the first/last element in a list, append/prepend it to another list and return it.
#lmovem(source, destination, where_source, where_destination, count: nil, exactly: nil, order: nil) ⇒ nil, Array<String>

Remove multiple elements from the head/tail of a list, append/prepend them to another list and return them.
#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.
#lpop(key, count = nil) ⇒ nil, ...

Remove and get the first elements in a list.
#lpush(key, value) ⇒ Integer

Prepend one or more values to a list, creating the list if it doesn't exist.
#lpushx(key, value) ⇒ Integer

Prepend a value to a list, only if the list exists.
#lrange(key, start, stop) ⇒ Array<String>

Get a range of elements from a list.
#lrem(key, count, value) ⇒ Integer

Remove elements from a list.
#lset(key, index, value) ⇒ String

Set the value of an element in a list by its index.
#ltrim(key, start, stop) ⇒ String

Trim a list to the specified range.
#rpop(key, count = nil) ⇒ nil, ...

Remove and get the last elements in a list.
#rpoplpush(source, destination) ⇒ nil, String

Remove the last element in a list, append it to another list and return it.
#rpush(key, value) ⇒ Integer

Append one or more values to a list, creating the list if it doesn't exist.
#rpushx(key, value) ⇒ Integer

Append a value to a list, only if the list exists.
#_bpop(cmd, args, &blk) private
#_movem_amount_args(count, exactly, order) private
#_normalize_move_wheres(where_source, where_destination) private

Instance Method Details

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

[ GitHub ]

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


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

#_movem_amount_args(count, exactly, order) (private)

Raises:

(ArgumentError)

[ GitHub ]

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


def _movem_amount_args(count, exactly, order)
  raise ArgumentError, "Pick either count or exactly, not both" if count && exactly

  if count || exactly
    order = order.to_s.upcase
    raise ArgumentError, "order must be 'OBO' or 'BULK'" if order != "OBO" && order != "BULK"

    [count ? "COUNT" : "EXACTLY", Integer(count || exactly), order]
  elsif order
    raise ArgumentError, "order requires count or exactly"
  else
    []
  end
end

#_normalize_move_wheres(where_source, where_destination) (private)

[ GitHub ]

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


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 133


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

#blmovem(source, destination, where_source, where_destination, timeout: 0, count: nil, exactly: nil, order: nil) ⇒ `nil`, `Array`<`String`>

Remove multiple elements from the head/tail of a list, append/prepend them to another list and return them; or block until the request can be satisfied or the timeout expires.

when 'OBO' - push each element as popped, so the moved block order is reversed
when 'BULK' - preserve the original relative order of the moved elements

Examples:

Move up to 3 elements as soon as any are available

redis.blmovem("foo", "bar", "LEFT", "LEFT", timeout: 1, count: 3, order: "BULK")
  # => ["s1", "s2", "s3"]

Block until the source holds at least 2 elements

redis.blmovem("foo", "bar", "LEFT", "RIGHT", timeout: 1, exactly: 2, order: "OBO")
  # => nil on timeout

Parameters:

source (String) —
source key
destination (String) —
destination key
where_source (String, Symbol) —
from where to remove elements from the source list e.g. 'LEFT' - from head, 'RIGHT' - from tail
where_destination (String, Symbol) —
where to push elements to the destination list e.g. 'LEFT' - to head, 'RIGHT' - to tail
timeout (Float, Integer) —
seconds to block, 0 blocks indefinitely
count (Integer) —
move up to count elements as soon as at least one is available
exactly (Integer) —
move exactly exactly elements, blocking until the source holds that many
order (String, Symbol) —
ordering at the destination, required together with count or exactly:

Returns:

(nil, Array<String>) —
the moved elements in destination order, or nil when the timeout expired and nothing was moved

#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 283


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

  args = [:blmpop, timeout, 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 228


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

#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 259


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 323


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 335


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

#lmovem(source, destination, where_source, where_destination, count: nil, exactly: nil, order: nil) ⇒ `nil`, `Array`<`String`>

Remove multiple elements from the head/tail of a list, append/prepend them to another list and return them.

when 'OBO' - push each element as popped, so the moved block order is reversed
when 'BULK' - preserve the original relative order of the moved elements

Examples:

Move a single element (still an array reply)

redis.lmovem("foo", "bar", "LEFT", "LEFT")
  # => ["s1"]

Move up to 3 elements, pushed one-by-one (block order reversed)

redis.lmovem("foo", "bar", "LEFT", "LEFT", count: 3, order: "OBO")
  # => ["s3", "s2", "s1"]

Move exactly 2 elements, preserving their relative order

redis.lmovem("foo", "bar", "LEFT", "RIGHT", exactly: 2, order: "BULK")
  # => ["s1", "s2"]

Parameters:

source (String) —
source key
destination (String) —
destination key
where_source (String, Symbol) —
from where to remove elements from the source list e.g. 'LEFT' - from head, 'RIGHT' - from tail
where_destination (String, Symbol) —
where to push elements to the destination list e.g. 'LEFT' - to head, 'RIGHT' - to tail
count (Integer) —
move up to count elements, fewer when the source holds fewer
exactly (Integer) —
move exactly exactly elements; when the source holds fewer, nothing is moved
order (String, Symbol) —
ordering at the destination, required together with count or exactly:

Returns:

(nil, Array<String>) —
the moved elements in destination order, or nil when nothing was moved

[ GitHub ]

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


def lmovem(source, destination, where_source, where_destination, count: nil, exactly: nil, order: nil)
  where_source, where_destination = _normalize_move_wheres(where_source, where_destination)

  args = [:lmovem, source, destination, where_source, where_destination]
  args.concat(_movem_amount_args(count, exactly, order))

  send_command(args)
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 309


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 181


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 145


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 154


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 345


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 358


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 368


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 378


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 192


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 203


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 163


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 172


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

Module: Redis::Commands::Lists

Instance Method Summary

Instance Method Details

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

#_movem_amount_args(count, exactly, order) (private)

#_normalize_move_wheres(where_source, where_destination) (private)

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

#blmovem(source, destination, where_source, where_destination, timeout: 0, count: nil, exactly: nil, order: nil) ⇒ nil, Array<String>

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

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

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

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

#lindex(key, index) ⇒ String

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

#llen(key) ⇒ Integer

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

#lmovem(source, destination, where_source, where_destination, count: nil, exactly: nil, order: nil) ⇒ nil, Array<String>

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

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

#lpush(key, value) ⇒ Integer

#lpushx(key, value) ⇒ Integer

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

#lrem(key, count, value) ⇒ Integer

#lset(key, index, value) ⇒ String

#ltrim(key, start, stop) ⇒ String

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

#rpoplpush(source, destination) ⇒ nil, String

#rpush(key, value) ⇒ Integer

#rpushx(key, value) ⇒ Integer

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

#blmovem(source, destination, where_source, where_destination, timeout: 0, count: nil, exactly: nil, order: nil) ⇒ `nil`, `Array`<`String`>

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

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

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

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

#lindex(key, index) ⇒ `String`

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

#llen(key) ⇒ `Integer`

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

#lmovem(source, destination, where_source, where_destination, count: nil, exactly: nil, order: nil) ⇒ `nil`, `Array`<`String`>

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

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

#lpush(key, value) ⇒ `Integer`

#lpushx(key, value) ⇒ `Integer`

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

#lrem(key, count, value) ⇒ `Integer`

#lset(key, index, value) ⇒ `String`

#ltrim(key, start, stop) ⇒ `String`

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

#rpoplpush(source, destination) ⇒ `nil`, `String`

#rpush(key, value) ⇒ `Integer`

#rpushx(key, value) ⇒ `Integer`