Module: Redis::Commands::Strings

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

Instance Method Summary collapse

Instance Method Details

#append(key, value) ⇒ Integer

Append a value to a key.

Parameters:

  • key (String)
  • value (String)

    value to append

Returns:

  • (Integer)

    length of the string after appending



255
256
257
# File 'lib/redis/commands/strings.rb', line 255

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

#decr(key) ⇒ Integer

Decrement the integer value of a key by one.

Examples:

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

Parameters:

  • key (String)

Returns:

  • (Integer)

    value after decrementing it



14
15
16
# File 'lib/redis/commands/strings.rb', line 14

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

#decrby(key, decrement) ⇒ Integer

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

Examples:

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

Parameters:

  • key (String)
  • decrement (Integer)

Returns:

  • (Integer)

    value after decrementing it



27
28
29
# File 'lib/redis/commands/strings.rb', line 27

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

#get(key) ⇒ String

Get the value of a key.

Parameters:

  • key (String)

Returns:

  • (String)


190
191
192
# File 'lib/redis/commands/strings.rb', line 190

def get(key)
  send_command([:get, key])
end

#getdel(key) ⇒ String

Get the value of key and delete the key. This command is similar to GET, except for the fact that it also deletes the key on success.

Parameters:

  • key (String)

Returns:

  • (String)

    the old value stored in the key, or ‘nil` if the key did not exist



275
276
277
# File 'lib/redis/commands/strings.rb', line 275

def getdel(key)
  send_command([:getdel, 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. GETEX is similar to GET, but is a write command with additional options. When no options are provided, GETEX behaves like GET.

Parameters:

  • key (String)
  • options (Hash)
    • ‘:ex => Integer`: Set the specified expire time, in seconds.

    • ‘:px => Integer`: Set the specified expire time, in milliseconds.

    • ‘:exat => true`: Set the specified Unix time at which the key will

      expire, in seconds.
      
    • ‘:pxat => true`: 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)

    The value of key, or nil when key does not exist.



293
294
295
296
297
298
299
300
301
302
# File 'lib/redis/commands/strings.rb', line 293

def getex(key, ex: nil, px: nil, exat: nil, pxat: nil, persist: false)
  args = [:getex, 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(args)
end

#getrange(key, start, stop) ⇒ Integer

Get a substring of the string stored at a key.

Parameters:

  • key (String)
  • start (Integer)

    zero-based start offset

  • stop (Integer)

    zero-based end offset. Use -1 for representing the end of the string

Returns:

  • (Integer)

    ‘0` or `1`



246
247
248
# File 'lib/redis/commands/strings.rb', line 246

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

#getset(key, value) ⇒ String

Set the string value of a key and return its old value.

Parameters:

  • key (String)
  • value (String)

    value to replace the current value with

Returns:

  • (String)

    the old value stored in the key, or ‘nil` if the key did not exist



265
266
267
# File 'lib/redis/commands/strings.rb', line 265

def getset(key, value)
  send_command([:getset, key, value.to_s])
end

#incr(key) ⇒ Integer

Increment the integer value of a key by one.

Examples:

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

Parameters:

  • key (String)

Returns:

  • (Integer)

    value after incrementing it



39
40
41
# File 'lib/redis/commands/strings.rb', line 39

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

#incrby(key, increment) ⇒ Integer

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

Examples:

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

Parameters:

  • key (String)
  • increment (Integer)

Returns:

  • (Integer)

    value after incrementing it



52
53
54
# File 'lib/redis/commands/strings.rb', line 52

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

#incrbyfloat(key, increment) ⇒ Float

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

Examples:

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

Parameters:

  • key (String)
  • increment (Float)

Returns:

  • (Float)

    value after incrementing it



65
66
67
# File 'lib/redis/commands/strings.rb', line 65

def incrbyfloat(key, increment)
  send_command([:incrbyfloat, key, Float(increment)], &Floatify)
end

#mapped_mget(*keys) ⇒ Hash

Get the values of all the given keys.

Examples:

redis.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:



219
220
221
222
223
224
225
226
227
# File 'lib/redis/commands/strings.rb', line 219

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

#mapped_mset(hash) ⇒ String

Set one or more values.

Examples:

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

Parameters:

  • hash (Hash)

    keys mapping to values

Returns:

  • (String)

    ‘“OK”`

See Also:



154
155
156
# File 'lib/redis/commands/strings.rb', line 154

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:

redis.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:



182
183
184
# File 'lib/redis/commands/strings.rb', line 182

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

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

Get the values of all the given keys.

Examples:

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

Parameters:

  • keys (Array<String>)

Returns:

  • (Array<String>)

    an array of values for the specified keys

See Also:



204
205
206
207
# File 'lib/redis/commands/strings.rb', line 204

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

#mset(*args) ⇒ String

Set one or more values.

Examples:

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

Parameters:

  • args (Array<String>)

    array of keys and values

Returns:

  • (String)

    ‘“OK”`

See Also:



140
141
142
# File 'lib/redis/commands/strings.rb', line 140

def mset(*args)
  send_command([:mset] + args)
end

#msetnx(*args) ⇒ Boolean

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

Examples:

redis.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:



168
169
170
# File 'lib/redis/commands/strings.rb', line 168

def msetnx(*args)
  send_command([:msetnx, *args], &Boolify)
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”`



117
118
119
# File 'lib/redis/commands/strings.rb', line 117

def psetex(key, ttl, value)
  send_command([:psetex, 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`



83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
# File 'lib/redis/commands/strings.rb', line 83

def set(key, value, ex: nil, px: nil, exat: nil, pxat: nil, nx: nil, xx: nil, keepttl: nil, get: nil)
  args = [:set, 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

  if nx || xx
    send_command(args, &BoolifySet)
  else
    send_command(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”`



107
108
109
# File 'lib/redis/commands/strings.rb', line 107

def setex(key, ttl, value)
  send_command([:setex, 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



126
127
128
# File 'lib/redis/commands/strings.rb', line 126

def setnx(key, value)
  send_command([:setnx, key, value.to_s], &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



235
236
237
# File 'lib/redis/commands/strings.rb', line 235

def setrange(key, offset, value)
  send_command([:setrange, 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 value stored in the key, or 0 if the key does not exist



309
310
311
# File 'lib/redis/commands/strings.rb', line 309

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