Module: Redis::Commands::Strings

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Included In: `::Redis`, `::Redis::Commands`, `::Redis::MultiConnection`, `::Redis::PipelinedConnection`
Defined in:	lib/redis/commands/strings.rb

Instance Method Summary

#append(key, value) ⇒ Integer

Append a value to a key.
#decr(key) ⇒ Integer

Decrement the integer value of a key by one.
#decrby(key, decrement) ⇒ Integer

Decrement the integer value of a key by the given number.
#get(key) ⇒ String

Get the value of a key.
#getdel(key) ⇒ String

Get the value of key and delete the key.
#getex(key, ex: nil, px: nil, exat: nil, pxat: nil, persist: false) ⇒ String

Get the value of key and optionally set its expiration.
#getrange(key, start, stop) ⇒ Integer

Get a substring of the string stored at a key.
#getset(key, value) ⇒ String

Set the string value of a key and return its old value.
#incr(key) ⇒ Integer

Increment the integer value of a key by one.
#incrby(key, increment) ⇒ Integer

Increment the integer value of a key by the given integer number.
#incrbyfloat(key, increment) ⇒ Float

Increment the numeric value of a key by the given float number.
#increx(key, by: nil, lbound: nil, ubound: nil, saturate: nil, ex: nil, px: nil, exat: nil, pxat: nil, persist: nil, enx: nil) ⇒ Array(Integer, Integer), Array(Float, Float)

Increment the numeric value of a key atomically, with optional bounds and expiration control.
#mapped_mget(*keys) ⇒ Hash

Get the values of all the given keys.
#mapped_mset(hash) ⇒ String

Set one or more values.
#mapped_msetnx(hash) ⇒ Boolean

Set one or more values, only if none of the keys exist.
#mget(*keys, &blk) ⇒ Array<String>

Get the values of all the given keys.
#mset(*args) ⇒ String

Set one or more values.
#msetnx(*args) ⇒ Boolean

Set one or more values, only if none of the keys exist.
#psetex(key, ttl, value) ⇒ String

Set the time to live in milliseconds of a key.
#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.
#setex(key, ttl, value) ⇒ String

Set the time to live in seconds of a key.
#setnx(key, value) ⇒ Boolean

Set the value of a key, only if the key does not exist.
#setrange(key, offset, value) ⇒ Integer

Overwrite part of a string at key starting at the specified offset.
#strlen(key) ⇒ Integer

Get the length of the value stored in a key.
#increx_bound(name, value, float_mode) private

INCREX bounds decide whether the increment is applied at all, so a Float bound in integer mode must raise rather than silently truncate (Integer(2.9) => 2) — mirroring how by: selects the mode strictly.

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

[ GitHub ]

# File 'lib/redis/commands/strings.rb', line 340


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

[ GitHub ]

# 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

[ GitHub ]

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

[ GitHub ]

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


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

[ GitHub ]

# File 'lib/redis/commands/strings.rb', line 360


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.

[ GitHub ]

# File 'lib/redis/commands/strings.rb', line 378


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

[ GitHub ]

# File 'lib/redis/commands/strings.rb', line 331


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

[ GitHub ]

# File 'lib/redis/commands/strings.rb', line 350


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

[ GitHub ]

# 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

[ GitHub ]

# 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

[ GitHub ]

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


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

#increx(key, by: nil, lbound: nil, ubound: nil, saturate: nil, ex: nil, px: nil, exat: nil, pxat: nil, persist: nil, enx: nil) ⇒ `Array`(`Integer`, `Integer`), `Array`(`Float`, `Float`)

Increment the numeric value of a key atomically, with optional bounds and expiration control. Uses 0 as the initial value if the key does not exist.

Unlike incr/incrby, the reply is a two-element array of the new value and the increment that was actually applied. When the result would fall outside lbound:/ubound: (or the type limits) the operation is skipped and the reply is [current_value, 0]; with saturate: true the result is capped at the bound instead and the second element reflects the saturated delta.

Examples:

Increment by 1 (integer mode default)

redis.increx("counter")
  # => [1, 1]

Window counter rate limiter: cap at 100, TTL only on window creation

value, applied = redis.increx("ratelimit:#{user_id}", by: 1, ubound: 100, ex: 60, enx: true)
reject_request if applied == 0

Float mode — selected by the Ruby type of by:

redis.increx("temp", by: 0.25)
  # => [1.75, 0.25]

Parameters:

key (String)
by (Integer, Float) —
the increment (may be negative). The Ruby type selects the mode: an Integer is sent as BYINT (requires an integer-typed stored value, replies with Integers), a Float as BYFLOAT (stored value may be integer or float, replies with Floats) — so by: 5 and by: 5.0 behave differently. Other types raise TypeError. Without by:, increments by 1 in integer mode.
lbound (Integer, Float) —
lower bound for the result. In float mode any numeric is accepted; in integer mode it must be an Integer (a Float raises TypeError rather than silently truncating, since bounds decide whether the increment applies)
ubound (Integer, Float) —
upper bound for the result, with the same typing rules as lbound
saturate (Boolean) —
cap/floor an out-of-bounds result at the bound instead of skipping the operation
ex (Integer) —
expiration in seconds
px (Integer) —
expiration in milliseconds
exat (Integer) —
expiration as a Unix timestamp in seconds
pxat (Integer) —
expiration as a Unix timestamp in milliseconds
persist (Boolean) —
remove the key's expiration
enx (Boolean) —
only set the expiration when the key has no TTL (the increment is applied regardless); requires one of ex/px/exat/pxat

Returns:

(Array(Integer, Integer), Array(Float, Float)) —
[new_value, applied_increment] — Integers in integer mode, Floats in float mode (under RESP2 and RESP3 alike); applied_increment is 0 when the operation was skipped as out of bounds

Raises:

(ArgumentError)

[ GitHub ]

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


def increx(key, by: nil, lbound: nil, ubound: nil, saturate: nil,
           ex: nil, px: nil, exat: nil, pxat: nil, persist: nil, enx: nil)
  if [ex, px, exat, pxat, persist].count { |option| option } > 1
    raise ArgumentError, "ex, px, exat, pxat and persist are mutually exclusive"
  end
  raise ArgumentError, "enx is incompatible with persist" if enx && persist
  raise ArgumentError, "enx requires one of ex, px, exat or pxat" if enx && !(ex || px || exat || pxat)

  # The Ruby type of `by` selects the wire mode; anything else would
  # have to silently pick a mode, so it is rejected instead.
  float_mode = case by
  when nil, Integer then false
  when Float then true
  else raise TypeError, "by must be an Integer (BYINT) or a Float (BYFLOAT), got #{by.class}"
  end

  args = [:increx, key]
  args << (float_mode ? "BYFLOAT" : "BYINT") << by if by
  args << "LBOUND" << increx_bound(:lbound, lbound, float_mode) if lbound
  args << "UBOUND" << increx_bound(:ubound, ubound, float_mode) if ubound
  args << "SATURATE" if saturate
  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
  args << "ENX" if enx

  if float_mode
    # RESP2 replies with bulk strings, RESP3 with native doubles;
    # converge both on Float.
    send_command(args) { |reply| reply.is_a?(Array) ? reply.map(&Floatify) : reply }
  else
    send_command(args)
  end
end

#increx_bound(name, value, float_mode) (private)

INCREX bounds decide whether the increment is applied at all, so a Float bound in integer mode must raise rather than silently truncate (Integer(2.9) => 2) — mirroring how by: selects the mode strictly.

Raises:

(TypeError)

[ GitHub ]

# File 'lib/redis/commands/strings.rb', line 403


def increx_bound(name, value, float_mode)
  return Float(value) if float_mode
  raise TypeError, "#{name} must be an Integer in integer mode, got #{value.class}" unless value.is_a?(Integer)

  value
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:

#mget

[ GitHub ]

# File 'lib/redis/commands/strings.rb', line 304


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:

#mset

[ GitHub ]

# File 'lib/redis/commands/strings.rb', line 239


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:

#msetnx

[ GitHub ]

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


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:

#mapped_mget

[ GitHub ]

# File 'lib/redis/commands/strings.rb', line 289


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:

#mapped_mset

[ GitHub ]

# File 'lib/redis/commands/strings.rb', line 225


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:

#mapped_msetnx

[ GitHub ]

# File 'lib/redis/commands/strings.rb', line 253


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"

[ GitHub ]

# File 'lib/redis/commands/strings.rb', line 202


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

[ GitHub ]

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


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"

[ GitHub ]

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


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

[ GitHub ]

# File 'lib/redis/commands/strings.rb', line 211


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

[ GitHub ]

# File 'lib/redis/commands/strings.rb', line 320


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

[ GitHub ]

# File 'lib/redis/commands/strings.rb', line 394


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

Module: Redis::Commands::Strings

Instance Method Summary

Instance Method Details

#append(key, value) ⇒ Integer

#decr(key) ⇒ Integer

#decrby(key, decrement) ⇒ Integer

#get(key) ⇒ String

#getdel(key) ⇒ String

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

#getrange(key, start, stop) ⇒ Integer

#getset(key, value) ⇒ String

#incr(key) ⇒ Integer

#incrby(key, increment) ⇒ Integer

#incrbyfloat(key, increment) ⇒ Float

#increx(key, by: nil, lbound: nil, ubound: nil, saturate: nil, ex: nil, px: nil, exat: nil, pxat: nil, persist: nil, enx: nil) ⇒ Array(Integer, Integer), Array(Float, Float)

#increx_bound(name, value, float_mode) (private)

#mapped_mget(*keys) ⇒ Hash

#mapped_mset(hash) ⇒ String

#mapped_msetnx(hash) ⇒ Boolean

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

#mset(*args) ⇒ String

#msetnx(*args) ⇒ Boolean

#psetex(key, ttl, value) ⇒ String

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

#setex(key, ttl, value) ⇒ String

#setnx(key, value) ⇒ Boolean

#setrange(key, offset, value) ⇒ Integer

#strlen(key) ⇒ Integer

#append(key, value) ⇒ `Integer`

#decr(key) ⇒ `Integer`

#decrby(key, decrement) ⇒ `Integer`

#get(key) ⇒ `String`

#getdel(key) ⇒ `String`

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

#getrange(key, start, stop) ⇒ `Integer`

#getset(key, value) ⇒ `String`

#incr(key) ⇒ `Integer`

#incrby(key, increment) ⇒ `Integer`

#incrbyfloat(key, increment) ⇒ `Float`

#increx(key, by: nil, lbound: nil, ubound: nil, saturate: nil, ex: nil, px: nil, exat: nil, pxat: nil, persist: nil, enx: nil) ⇒ `Array`(`Integer`, `Integer`), `Array`(`Float`, `Float`)

#mapped_mget(*keys) ⇒ `Hash`

#mapped_mset(hash) ⇒ `String`

#mapped_msetnx(hash) ⇒ `Boolean`

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

#mset(*args) ⇒ `String`

#msetnx(*args) ⇒ `Boolean`

#psetex(key, ttl, value) ⇒ `String`

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

#setex(key, ttl, value) ⇒ `String`

#setnx(key, value) ⇒ `Boolean`

#setrange(key, offset, value) ⇒ `Integer`

#strlen(key) ⇒ `Integer`