Module: Valkey::Commands::StringCommands

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

Overview

This module contains commands on the String data type.

See Also:

Instance Method Summary collapse

Instance Method Details

#append(key, value) ⇒ Integer

Append a value to a key.

Parameters:

  • key (String)
  • value (String)

Returns:

  • (Integer) —

    the length of the string after the append operation



285
286
287
 
# File 'lib/valkey/commands/string_commands.rb', line 285

def append(key, value)
  send_command(RequestType::APPEND, [key, value])
end

#decr(key) ⇒ Integer

Decrement the integer value of a key by one.

Examples:

valkey.decr("value")
  # => 4

Parameters:

  • key (String)

Returns:

  • (Integer) —

    value after decrementing it



18
19
20
 
# File 'lib/valkey/commands/string_commands.rb', line 18

def decr(key)
  send_command(RequestType::DECR, [key])
end

#decrby(key, decrement) ⇒ Integer

Decrement the integer value of a key by the given number.

Examples:

valkey.decrby("value", 5)
  # => 0

Parameters:

  • key (String)
  • decrement (Integer)

Returns:

  • (Integer) —

    value after decrementing it



31
32
33
 
# File 'lib/valkey/commands/string_commands.rb', line 31

def decrby(key, decrement)
  send_command(RequestType::DECR_BY, [key, Integer(decrement)])
end

#get(key) ⇒ String

Get the value of a key.

Parameters:

  • key (String)

Returns:

  • (String) 


207
208
209
210
211
 
# File 'lib/valkey/commands/string_commands.rb', line 207

def get(key)
  result = send_command(RequestType::GET, [key])
  result = handle_transaction_isolation_get(key, result) if should_intercept_get?(result)
  result
end

#getdel(key) ⇒ String?

Get the value of key and delete it.

Parameters:

  • key (String)

Returns:

  • (String, nil) —

    the value of key, or nil when key does not exist



293
294
295
 
# File 'lib/valkey/commands/string_commands.rb', line 293

def getdel(key)
  send_command(RequestType::GET_DEL, [key])
end

#getex(key, ex: nil, px: nil, exat: nil, pxat: nil, persist: false) ⇒ String?

Get the value of key and optionally set its expiration.

Parameters:

  • key (String)
  • options (Hash) —
    • :ex => Integer: Set the specified expire time, in seconds.
    • :px => Integer: Set the specified expire time, in milliseconds.
    • :exat => Integer : Set the specified Unix time at which the key will expire, in seconds.
    • :pxat => Integer : Set the specified Unix time at which the key will expire, in milliseconds.
    • :persist => true: Remove the time to live associated with the key.

Returns:

  • (String, nil) —

    the value of key, or nil when key does not exist



307
308
309
310
311
312
313
314
315
316
 
# File 'lib/valkey/commands/string_commands.rb', line 307

def getex(key, ex: nil, px: nil, exat: nil, pxat: nil, persist: false)
  args = [key]
  args << "EX" << Integer(ex) if ex
  args << "PX" << Integer(px) if px
  args << "EXAT" << Integer(exat) if exat
  args << "PXAT" << Integer(pxat) if pxat
  args << "PERSIST" if persist

  send_command(RequestType::GET_EX, args)
end

#getrange(key, start, stop) ⇒ String

Get a substring of the string stored at key.

Parameters:

  • key (String)
  • start (Integer) —

    start position

  • stop (Integer) —

    end position

Returns:

  • (String) —

    the substring



276
277
278
 
# File 'lib/valkey/commands/string_commands.rb', line 276

def getrange(key, start, stop)
  send_command(RequestType::GET_RANGE, [key, start, stop])
end

#getset(key, value) ⇒ String?

Atomically set key to value and return the previous value.

Implemented as SET key value GET (Redis 6.2+ / Valkey 7+). This matches GETSET and avoids RequestType::GET_SET, which the Glide FFI layer does not implement yet.

Parameters:

  • key (String)
  • value (#to_s)

Returns:

  • (String, nil) —

    the old value, or nil if the key did not exist



221
222
223
 
# File 'lib/valkey/commands/string_commands.rb', line 221

def getset(key, value)
  set(key, value, get: true)
end

#incr(key) ⇒ Integer

Increment the integer value of a key by one.

Examples:

valkey.incr("value")
  # => 6

Parameters:

  • key (String)

Returns:

  • (Integer) —

    value after incrementing it



43
44
45
 
# File 'lib/valkey/commands/string_commands.rb', line 43

def incr(key)
  send_command(RequestType::INCR, [key])
end

#incrby(key, increment) ⇒ Integer

Increment the integer value of a key by the given integer number.

Examples:

valkey.incrby("value", 5)
  # => 10

Parameters:

  • key (String)
  • increment (Integer)

Returns:

  • (Integer) —

    value after incrementing it



56
57
58
 
# File 'lib/valkey/commands/string_commands.rb', line 56

def incrby(key, increment)
  send_command(RequestType::INCR_BY, [key, Integer(increment)])
end

#incrbyfloat(key, increment) ⇒ Float

Increment the numeric value of a key by the given float number.

Examples:

valkey.incrbyfloat("value", 1.23)
  # => 1.23

Parameters:

  • key (String)
  • increment (Float)

Returns:

  • (Float) —

    value after incrementing it



69
70
71
 
# File 'lib/valkey/commands/string_commands.rb', line 69

def incrbyfloat(key, increment)
  send_command(RequestType::INCR_BY_FLOAT, [key, increment])
end

#lcs(key1, key2, len: nil, idx: nil, min_match_len: nil, with_match_len: nil) ⇒ String, ...

Find the longest common subsequence between two strings.

Parameters:

  • key1 (String)
  • key2 (String)
  • options (Hash) —
    • :len => true: Return the length of the LCS
    • :idx => true: Return the positions of the LCS
    • :min_match_len => Integer: Minimum match length
    • :with_match_len => true: Include match length in results

Returns:

  • (String, Integer, Hash) —

    the LCS result based on options (Hash when idx: true)



336
337
338
339
340
341
342
343
344
 
# File 'lib/valkey/commands/string_commands.rb', line 336

def lcs(key1, key2, len: nil, idx: nil, min_match_len: nil, with_match_len: nil)
  args = [key1, key2]
  args << "LEN" if len
  args << "IDX" if idx
  args << "MINMATCHLEN" << min_match_len if min_match_len
  args << "WITHMATCHLEN" if with_match_len

  send_command(RequestType::LCS, args)
end

#mapped_mget(*keys) ⇒ Hash

Get the values of all the given keys.

Examples:

valkey.mapped_mget("key1", "key2")
  # => { "key1" => "v1", "key2" => "v2" }

Parameters:

  • keys (Array<String>) —

    array of keys

Returns:

  • (Hash) —

    a hash mapping the specified keys to their values

See Also:



250
251
252
253
254
255
256
257
258
 
# File 'lib/valkey/commands/string_commands.rb', line 250

def mapped_mget(*keys)
  mget(*keys) do |reply|
    if reply.is_a?(Array)
      keys.zip(reply).to_h
    else
      reply
    end
  end
end

#mapped_mset(hash) ⇒ String

Set one or more values.

Examples:

valkey.mapped_mset({ "f1" => "v1", "f2" => "v2" })
  # => "OK"

Parameters:

  • hash (Hash) —

    keys mapping to values

Returns:

  • (String) —

    "OK"

See Also:



171
172
173
 
# File 'lib/valkey/commands/string_commands.rb', line 171

def mapped_mset(hash)
  mset(*hash.flatten)
end

#mapped_msetnx(hash) ⇒ Boolean

Set one or more values, only if none of the keys exist.

Examples:

valkey.mapped_msetnx({ "key1" => "v1", "key2" => "v2" })
  # => true

Parameters:

  • hash (Hash) —

    keys mapping to values

Returns:

  • (Boolean) —

    whether or not all values were set

See Also:



199
200
201
 
# File 'lib/valkey/commands/string_commands.rb', line 199

def mapped_msetnx(hash)
  msetnx(*hash.flatten)
end

#mget(*keys, &blk) ⇒ Array<String>

Get the values of all the given keys.

Examples:

valkey.mget("key1", "key2")
  # => ["v1", "v2"]

Parameters:

  • keys (Array<String>)

Returns:

  • (Array<String>) —

    an array of values for the specified keys

See Also:



235
236
237
238
 
# File 'lib/valkey/commands/string_commands.rb', line 235

def mget(*keys, &blk)
  keys.flatten!(1)
  send_command(RequestType::MGET, keys, &blk)
end

#mset(*args) ⇒ String

Set one or more values.

Examples:

valkey.mset("key1", "v1", "key2", "v2")
  # => "OK"

Parameters:

  • args (Array<String>) —

    array of keys and values

Returns:

  • (String) —

    "OK"

See Also:



157
158
159
 
# File 'lib/valkey/commands/string_commands.rb', line 157

def mset(*args)
  send_command(RequestType::MSET, args)
end

#msetnx(*args) ⇒ Boolean

Set one or more values, only if none of the keys exist.

Examples:

valkey.msetnx("key1", "v1", "key2", "v2")
  # => true

Parameters:

  • args (Array<String>) —

    array of keys and values

Returns:

  • (Boolean) —

    whether or not all values were set

See Also:



185
186
187
 
# File 'lib/valkey/commands/string_commands.rb', line 185

def msetnx(*args)
  send_command(RequestType::MSET_NX, args)
end

#psetex(key, ttl, value) ⇒ String

Set the time to live in milliseconds of a key.

Parameters:

  • key (String)
  • ttl (Integer)
  • value (String)

Returns:

  • (String) —

    "OK"



127
128
129
 
# File 'lib/valkey/commands/string_commands.rb', line 127

def psetex(key, ttl, value)
  send_command(RequestType::PSET_EX, [key, Integer(ttl), value.to_s])
end

#set(key, value, ex: nil, px: nil, exat: nil, pxat: nil, nx: nil, xx: nil, keepttl: nil, get: nil) ⇒ String, Boolean

Set the string value of a key.

Parameters:

  • key (String)
  • value (String)
  • options (Hash) —
    • :ex => Integer: Set the specified expire time, in seconds.
    • :px => Integer: Set the specified expire time, in milliseconds.
    • :exat => Integer : Set the specified Unix time at which the key will expire, in seconds.
    • :pxat => Integer : Set the specified Unix time at which the key will expire, in milliseconds.
    • :nx => true: Only set the key if it does not already exist.
    • :xx => true: Only set the key if it already exist.
    • :keepttl => true: Retain the time to live associated with the key.
    • :get => true: Return the old string stored at key, or nil if key did not exist.

Returns:

  • (String, Boolean) —

    "OK" or true, false if :nx => true or :xx => true



87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/valkey/commands/string_commands.rb', line 87

def set(key, value, ex: nil, px: nil, exat: nil, pxat: nil, nx: nil, xx: nil, keepttl: nil, get: nil)
  # value.to_s (matching redis-rb): a non-String value (e.g. an Array,
  # in test_set_and_get_with_non_string_value) must become ONE opaque
  # value here, not get flattened as if it were a multi-value list -
  # see build_command_args's flat_map fix for why this must happen
  # before command_args is built, not be left to that generic layer.
  args = [key, value.to_s]
  args << "EX" << Integer(ex) if ex
  args << "PX" << Integer(px) if px
  args << "EXAT" << Integer(exat) if exat
  args << "PXAT" << Integer(pxat) if pxat
  args << "NX" if nx
  args << "XX" if xx
  args << "KEEPTTL" if keepttl
  args << "GET" if get

  send_command(RequestType::SET, args)
  # if nx || xx
  #   send_command(RequestType::SET, &Utils::BoolifySet))
  # else
  #   send_command(RequestType::SET, args)
  # end
end

#setex(key, ttl, value) ⇒ String

Set the time to live in seconds of a key.

Parameters:

  • key (String)
  • ttl (Integer)
  • value (String)

Returns:

  • (String) —

    "OK"



117
118
119
 
# File 'lib/valkey/commands/string_commands.rb', line 117

def setex(key, ttl, value)
  send_command(RequestType::SET_EX, [key, Integer(ttl), value.to_s])
end

#setnx(key, value) ⇒ Boolean

Set the value of a key, only if the key does not exist.

Parameters:

  • key (String)
  • value (String)

Returns:

  • (Boolean) —

    whether the key was set or not



136
137
138
139
140
141
142
143
144
145
 
# File 'lib/valkey/commands/string_commands.rb', line 136

def setnx(key, value)
  # &Utils::Boolify (not glide-core's generic Boolean-coercion table) is
  # deliberately used here: glide-core's per-command coercion is keyed by
  # command name alone, so it can't distinguish this dedicated SETNX
  # RequestType from a raw `customCommand(["SETNX", ...])` call, which
  # other GLIDE bindings' existing contracts expect to keep returning a
  # plain 0/1 integer. Doing the conversion here keeps it scoped to this
  # one Ruby-level method - see hexists/hsetnx for the same pattern.
  send_command(RequestType::SET_NX, [key, value.to_s], &Utils::Boolify)
end

#setrange(key, offset, value) ⇒ Integer

Overwrite part of a string at key starting at the specified offset.

Parameters:

  • key (String)
  • offset (Integer) —

    byte offset

  • value (String)

Returns:

  • (Integer) —

    length of the string after it was modified



266
267
268
 
# File 'lib/valkey/commands/string_commands.rb', line 266

def setrange(key, offset, value)
  send_command(RequestType::SET_RANGE, [key, Integer(offset), value.to_s])
end

#strlen(key) ⇒ Integer

Get the length of the value stored in a key.

Parameters:

  • key (String)

Returns:

  • (Integer) —

    the length of the string at key, or 0 when key does not exist



322
323
324
 
# File 'lib/valkey/commands/string_commands.rb', line 322

def strlen(key)
  send_command(RequestType::STRLEN, [key])
end