SETRANGE

Syntax

  1. SETRANGE key offset value

Time complexity: O(1), not counting the time taken to copy the new string in place. Usually, this string is very small so the amortized complexity is O(1). Otherwise, complexity is O(M) with M being the length of the value argument.

ACL categories: @write, @string, @slow

Overwrites part of the string stored at key, starting at the specified offset, for the entire length of value. If the offset is larger than the current length of the string at key, the string is padded with zero-bytes to make offset fit. Non-existing keys are considered as empty strings, so this command will make sure it holds a string large enough to be able to set value at offset.

Warning: When setting the last possible byte (with large offset), and the string value stored at key does not holds a value (or holds a small string), the operation will take some time, as Dragonfly is required to allocate all memory leading to that bit. Subsequent calls will not have the performance penalty.

Return

Integer reply: the length of the string after it was modified by the command.

Patterns

Thanks to SETRANGE and the analogous GETRANGE commands, you can use Redis strings as a linear array with O(1) random access. This is a very fast and efficient storage in many real world use cases.

Examples

Basic usage:

  1. dragonfly> SET key1 "Hello World"
  2. OK
  3. dragonfly> SETRANGE key1 6 "Dragonfly"
  4. (integer) 15
  5. dragonfly> GET key1
  6. "Hello Dragonfly"

Example of zero padding:

  1. dragonfly> SETRANGE key2 6 "Dragonfly"
  2. (integer) 15
  3. dragonfly> GET key2
  4. "\x00\x00\x00\x00\x00\x00Dragonfly

where \x00 stands for the NUL character, inserted by the zero padding.