doc/SetrangeCommand.html

   1
   2 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
   3 <html>
   4     <head>
   5         <link type="text/css" rel="stylesheet" href="style.css" />
   6     </head>
   7     <body>
   8         <div id="page">
   9
  10             <div id='header'>
  11             <a href="index.html">
  12             <img style="border:none" alt="Redis Documentation" src="redis.png">
  13             </a>
  14             </div>
  15
  16             <div id="pagecontent">
  17                 <div class="index">
  18 <!-- This is a (PRE) block.  Make sure it's left aligned or your toc title will be off. -->
  19 <b>SetrangeCommand: Contents</b><br>&nbsp;&nbsp;<a href="#SETRANGE _key_ _offset_ _value_ (Redis &gt;">SETRANGE _key_ _offset_ _value_ (Redis &gt;</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Examples">Examples</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Patterns">Patterns</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Return value">Return value</a>
  20                 </div>
  21
  22                 <h1 class="wikiname">SetrangeCommand</h1>
  23
  24                 <div class="summary">
  25
  26                 </div>
  27
  28                 <div class="narrow">
  29                     &iuml;&raquo;&iquest;#sidebar <a href="StringCommandsSidebar.html">StringCommandsSidebar</a><h1><a name="SETRANGE _key_ _offset_ _value_ (Redis &gt;">SETRANGE _key_ _offset_ _value_ (Redis &gt;</a></h1> 2.1.8) =
  30 <i>Time complexity: O(1) not counting the time taken to copy the new string in place, as usually this string is small so the amoritzed time is O(1). Otheriwse O(M) with M being the length of the value argument</i><blockquote>Overwrites part of a string at <i>key</i> starting at the specified offset,for all the length of <i>value</i>.If the offset is over the old length of the string, the string is paddedwith zero bytes until needed. Non existing keys are considered likealready containing an empty string.</blockquote>
  31 <h2><a name="Examples">Examples</a></h2>First example, basic usage setting a range.<br/><br/><pre class="codeblock python" name="code">
  32 redis&gt; set foo &quot;Hello World&quot;
  33 OK
  34 redis&gt; setrange foo 6 &quot;Redis&quot;
  35 (integer) 11
  36 redis&gt; get foo
  37 &quot;Hello Redis&quot;
  38 </pre>Example of the zero padding behavior.<br/><br/><pre class="codeblock python python" name="code">
  39 redis&gt; del foo
  40 (integer) 1
  41 redis&gt; setrange foo 10 bar
  42 (integer) 13
  43 redis&gt; get foo
  44 &quot;\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00bar&quot;
  45 </pre>Note that the maximum offset that you can set is 536870911 as Redis Strings are limited to 512 megabytes. You can still create longer arrays of values using multiple keys.<br/><br/><b>Warning</b>: When setting the last possible byte and the string value stored at <i>key</i> does not yet hold a string value, or holds a small string value, Redis needs to allocate all intermediate memory which can block the server for some time.
  46 On a 2010 Macbook Pro, setting byte number 536870911 (512MB allocation) takes ~300ms,
  47 setting byte number 134217728 (128MB allocation) takes ~80ms,
  48 setting bit number 33554432 (32MB allocation) takes ~30ms and
  49 setting bit number 8388608 (8MB allocation) takes ~8ms.
  50 Note that once this first allocation is done, subsequent calls to SETRANGE for the same <i>key</i> will not have the allocation overhead.<h2><a name="Patterns">Patterns</a></h2>Thanks to SETRANGE and the analogous GETRANGE command you can use Redis strings as a linear array of memory with O(1) random access. This is a very fast and efficient storage in many real world use cases.<h2><a name="Return value">Return value</a></h2><a href="ReplyTypes.html">Integer reply</a>, specifically: the length of the string after it was modified by the command.
  51
  52                 </div>
  53
  54             </div>
  55         </div>
  56     </body>
  57 </html>
  58