Module: Redis::Commands::Lists

Included in:
Redis::Commands
Defined in:
lib/redis/commands/lists.rb

Instance Method Summary collapse

Instance Method Details

#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



55
56
57
58
59
60
 
# 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) 


205
206
207
208
209
210
211
212
 
# 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



150
151
152
 
# 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:



166
167
168
 
# 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



181
182
183
184
 
# 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)

Returns:

  • (String) 


245
246
247
 
# 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



257
258
259
 
# 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)

Returns:

  • (Integer) 


10
11
12
 
# 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



27
28
29
30
31
 
# 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) 


231
232
233
234
235
236
237
238
 
# 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



103
104
105
106
107
 
# 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



67
68
69
 
# 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



76
77
78
 
# 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

Returns:

  • (Array<String>) 


267
268
269
 
# 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



280
281
282
 
# 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`



290
291
292
 
# 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`



300
301
302
 
# 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



114
115
116
117
118
 
# 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



125
126
127
 
# 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



85
86
87
 
# 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



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

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