Module: Valkey::Commands::ListCommands

Included in:
Valkey::Commands
Defined in:
lib/valkey/commands/list_commands.rb

Overview

this module contains commands related to list data type.

See Also:

Instance Method Summary collapse

Instance Method Details

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

Note:

This command comes in place of the now deprecated BRPOPLPUSH. Doing BLMOVE RIGHT LEFT is equivalent.

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 = valkey.blmove("foo", "bar", "LEFT", "RIGHT", timeout: 5)
  # => nil on timeout
  # => "element" on success

Without timeout

element = valkey.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

  • timeout (Float, Integer) (defaults to: 0) —

    timeout in seconds; 0 blocks indefinitely

Returns:

  • (nil, String) —

    the element, or nil when the source key does not exist or the timeout expired



60
61
62
63
64
65
66
 
# File 'lib/valkey/commands/list_commands.rb', line 60

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

  args = [source, destination, where_source, where_destination, timeout]
  send_command(RequestType::BLMOVE, args)
end

#blmpop(timeout, *keys, modifier: "LEFT", count: nil) ⇒ Hash?

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

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

With count option

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

Returns:

  • (Hash, nil) —

    hash mapping key to popped elements, or nil on timeout

Raises:

  • (ArgumentError) 


242
243
244
245
246
247
248
249
 
# File 'lib/valkey/commands/list_commands.rb', line 242

def blmpop(timeout, *keys, modifier: "LEFT", count: nil)
  raise ArgumentError, "Pick either LEFT or RIGHT" unless %w[LEFT RIGHT].include?(modifier)

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

  send_command(RequestType::BLMPOP, args)
end

#blpop(*keys, timeout: 0) ⇒ nil, [String, String]

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

Examples:

With timeout

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

Without timeout

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

Blocking pop on multiple lists

list, element = valkey.blpop("list", "another_list", timeout: 5)
list, element = valkey.blpop(["list", "another_list"], timeout: 5)

Parameters:

  • keys (String, Array<String>) —

    one or more keys, checked in the given order; in cluster mode all keys must map to the same hash slot

  • timeout (Float, Integer) (defaults to: 0) —

    timeout in seconds; 0 blocks indefinitely

Returns:

  • (nil, [String, String]) —
    • nil when the operation timed out
    • tuple of the list that was popped from and element was popped otherwise


197
198
199
 
# File 'lib/valkey/commands/list_commands.rb', line 197

def blpop(*keys, timeout: 0)
  _bpop(keys, is_left: true, timeout: timeout)
end

#brpop(*keys, timeout: 0) ⇒ nil, [String, String]

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

Examples:

With timeout

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

Blocking pop on multiple lists

list, element = valkey.brpop("list", "another_list", timeout: 5)

Parameters:

  • keys (String, Array<String>) —

    one or more keys, checked in the given order; in cluster mode all keys must map to the same hash slot

  • timeout (Float, Integer) (defaults to: 0) —

    timeout in seconds; 0 blocks indefinitely

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:



219
220
221
 
# File 'lib/valkey/commands/list_commands.rb', line 219

def brpop(*keys, timeout: 0)
  _bpop(keys, is_left: false, timeout: timeout)
end

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

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

Deprecated in Redis 6.2 in favour of BLMOVE so implemented as facade over #blmove as BLMOVE src dst RIGHT LEFT. Note that glide-core has no command mapping for RequestType::BRPopLPush, so dispatching it directly is not an option.

Examples:

With timeout

valkey.brpoplpush("src", "dst", timeout: 5)
  # => nil on timeout
  # => "element" on success

Parameters:

  • source (String) —

    source key

  • destination (String) —

    destination key

  • timeout (Float, Integer) (defaults to: 0) —

    timeout in seconds; 0 blocks indefinitely

Returns:

  • (nil, String) —
    • nil when the operation timed out
    • the element that was popped and pushed otherwise

See Also:



110
111
112
113
 
# File 'lib/valkey/commands/list_commands.rb', line 110

def brpoplpush(source, destination, timeout: 0)
  # TODO: https://github.com/valkey-io/valkey-glide-ruby/issues/242
  blmove(source, destination, "RIGHT", "LEFT", timeout: timeout)
end

#lindex(key, index) ⇒ String

Get an element from a list by its index.

Parameters:

  • key (String)
  • index (Integer)

Returns:

  • (String) 


284
285
286
 
# File 'lib/valkey/commands/list_commands.rb', line 284

def lindex(key, index)
  send_command(RequestType::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



296
297
298
 
# File 'lib/valkey/commands/list_commands.rb', line 296

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

#llen(key) ⇒ Integer

Get the length of a list.

Parameters:

  • key (String)

Returns:

  • (Integer) 


14
15
16
 
# File 'lib/valkey/commands/list_commands.rb', line 14

def llen(key)
  send_command(RequestType::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



31
32
33
34
35
 
# File 'lib/valkey/commands/list_commands.rb', line 31

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

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

#lmpop(*keys, modifier: "LEFT", count: nil) ⇒ Hash?

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

Examples:

Popping a element

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

With count option

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

Returns:

  • (Hash, nil) —

    hash mapping key to popped elements, or nil if no elements

Raises:

  • (ArgumentError) 


268
269
270
271
272
273
274
275
276
277
 
# File 'lib/valkey/commands/list_commands.rb', line 268

def lmpop(*keys, modifier: "LEFT", count: nil)
  raise ArgumentError, "Pick either LEFT or RIGHT" unless %w[LEFT RIGHT].include?(modifier)

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

  # pp args

  send_command(RequestType::LMPOP, 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



160
161
162
163
164
 
# File 'lib/valkey/commands/list_commands.rb', line 160

def lpop(key, count = nil)
  args = [key]
  args << Integer(count) if count
  send_command(RequestType::LPOP, args)
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>) —

    one or more values, or array of values

Returns:

  • (Integer) —

    the length of the list after the push operation



120
121
122
123
 
# File 'lib/valkey/commands/list_commands.rb', line 120

def lpush(key, *value)
  value.flatten!(1)
  send_command(RequestType::LPUSH, [key].concat(value))
end

#lpushx(key, *value) ⇒ Integer

Prepend one or more values to a list, only if the list exists.

Parameters:

  • key (String)
  • value (String, Array<String>) —

    one or more values, or array of values

Returns:

  • (Integer) —

    the length of the list after the push operation



130
131
132
133
 
# File 'lib/valkey/commands/list_commands.rb', line 130

def lpushx(key, *value)
  value.flatten!(1)
  send_command(RequestType::LPUSHX, [key].concat(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>) 


306
307
308
 
# File 'lib/valkey/commands/list_commands.rb', line 306

def lrange(key, start, stop)
  send_command(RequestType::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



319
320
321
 
# File 'lib/valkey/commands/list_commands.rb', line 319

def lrem(key, count, value)
  send_command(RequestType::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



329
330
331
 
# File 'lib/valkey/commands/list_commands.rb', line 329

def lset(key, index, value)
  send_command(RequestType::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



339
340
341
 
# File 'lib/valkey/commands/list_commands.rb', line 339

def ltrim(key, start, stop)
  send_command(RequestType::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



171
172
173
174
175
 
# File 'lib/valkey/commands/list_commands.rb', line 171

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

#rpoplpush(source, destination) ⇒ nil, String

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

Deprecated in Redis 6.2 in favour of LMOVE so implemented as facade over #lmove as LMOVE src dst RIGHT LEFT``. Note that glide-core has no command mapping for RequestType::RPopLPush`, so dispatching it directly is not an option.

Examples:

valkey.rpush("src", "a", "b")
valkey.rpoplpush("src", "dst") # => "b"

Parameters:

  • source (String) —

    source key

  • destination (String) —

    destination key

Returns:

  • (nil, String) —

    the element, or nil when the source key does not exist

See Also:



84
85
86
87
 
# File 'lib/valkey/commands/list_commands.rb', line 84

def rpoplpush(source, destination)
  # TODO: https://github.com/valkey-io/valkey-glide-ruby/issues/242
  lmove(source, destination, "RIGHT", "LEFT")
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>) —

    one or more values, or array of values

Returns:

  • (Integer) —

    the length of the list after the push operation



140
141
142
143
 
# File 'lib/valkey/commands/list_commands.rb', line 140

def rpush(key, *value)
  value.flatten!(1)
  send_command(RequestType::RPUSH, [key].concat(value))
end

#rpushx(key, *value) ⇒ Integer

Append one or more values to a list, only if the list exists.

Parameters:

  • key (String)
  • value (String, Array<String>) —

    one or more values, or array of values

Returns:

  • (Integer) —

    the length of the list after the push operation



150
151
152
153
 
# File 'lib/valkey/commands/list_commands.rb', line 150

def rpushx(key, *value)
  value.flatten!(1)
  send_command(RequestType::RPUSHX, [key].concat(value))
end