README.md (7046B)
1 <!-- 2 3 @license Apache-2.0 4 5 Copyright (c) 2018 The Stdlib Authors. 6 7 Licensed under the Apache License, Version 2.0 (the "License"); 8 you may not use this file except in compliance with the License. 9 You may obtain a copy of the License at 10 11 http://www.apache.org/licenses/LICENSE-2.0 12 13 Unless required by applicable law or agreed to in writing, software 14 distributed under the License is distributed on an "AS IS" BASIS, 15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 See the License for the specific language governing permissions and 17 limitations under the License. 18 19 --> 20 21 # Circular Buffer 22 23 > Circular buffer constructor. 24 25 <!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. --> 26 27 <section class="intro"> 28 29 </section> 30 31 <!-- /.intro --> 32 33 <!-- Package usage documentation. --> 34 35 <section class="usage"> 36 37 ## Usage 38 39 ```javascript 40 var circularBuffer = require( '@stdlib/utils/circular-buffer' ); 41 ``` 42 43 #### circularBuffer( buffer ) 44 45 Returns a new circular buffer instance. 46 47 ```javascript 48 var buf = circularBuffer( 3 ); 49 // returns <CircularBuffer> 50 ``` 51 52 The `buffer` argument may either be a integer which specifies the buffer size or an array-like object to use as the underlying buffer. 53 54 ```javascript 55 var Float64Array = require( '@stdlib/array/float64' ); 56 57 // Use a typed array as the underlying buffer: 58 var buf = circularBuffer( new Float64Array( 3 ) ); 59 // returns <CircularBuffer> 60 ``` 61 62 ##### buf.clear() 63 64 Clears a buffer. 65 66 ```javascript 67 var buf = circularBuffer( 3 ); 68 // returns <CircularBuffer> 69 70 // Add values to the buffer: 71 buf.push( 'foo' ); 72 buf.push( 'bar' ); 73 buf.push( 'beep' ); 74 75 // Get the number of elements currently in the buffer: 76 var n = buf.count; 77 // returns 3 78 79 // Clear all buffer items: 80 buf.clear(); 81 82 // Get the number of elements in the buffer: 83 n = buf.count; 84 // returns 0 85 ``` 86 87 ##### buf.count 88 89 Returns the number of elements currently in the buffer. 90 91 ```javascript 92 var buf = circularBuffer( 3 ); 93 // returns <CircularBuffer> 94 95 // Add values to the buffer: 96 buf.push( 'foo' ); 97 buf.push( 'bar' ); 98 99 // Determine how many elements are in the buffer: 100 var n = buf.count; 101 // returns 2 102 ``` 103 104 ##### buf.full 105 106 Returns a `boolean` indicating if a buffer is full. 107 108 ```javascript 109 var buf = circularBuffer( 3 ); 110 // returns <CircularBuffer> 111 112 // Add values to the buffer: 113 buf.push( 'foo' ); 114 buf.push( 'bar' ); 115 116 // Determine if the buffer is full: 117 var bool = buf.full; 118 // returns false 119 120 // Add another value to the buffer: 121 buf.push( 'beep' ); 122 123 // Determine if the buffer is full: 124 bool = buf.full; 125 // returns true 126 ``` 127 128 ##### buf.iterator( \[niters] ) 129 130 Returns an iterator for iterating over a buffer. If an environment supports `Symbol.iterator`, the returned iterator is iterable. 131 132 ```javascript 133 var buf = circularBuffer( 2 ); 134 135 // Add values to the buffer: 136 buf.push( 'foo' ); 137 buf.push( 'bar' ); 138 buf.push( 'beep' ); 139 buf.push( 'boop' ); 140 141 // Create an iterator: 142 var it = buf.iterator(); 143 144 // Iterate over the buffer... 145 var v = it.next().value; 146 // returns 'beep' 147 148 v = it.next().value; 149 // returns 'boop' 150 151 v = it.next().value; 152 // returns 'beep' 153 154 v = it.next().value; 155 // returns 'boop' 156 157 v = it.next().value; 158 // returns 'beep' 159 ``` 160 161 By default, provided a buffer is **full**, the method returns an infinite iterator. To limit the number of iterations, provide an `niters` argument. 162 163 ```javascript 164 var buf = circularBuffer( 2 ); 165 166 // Add values to the buffer: 167 buf.push( 'foo' ); 168 buf.push( 'bar' ); 169 buf.push( 'beep' ); 170 buf.push( 'boop' ); 171 172 // Create an iterator: 173 var it = buf.iterator( buf.length ); 174 175 // Iterate over the buffer... 176 var v = it.next().value; 177 // returns 'beep' 178 179 v = it.next().value; 180 // returns 'boop' 181 182 var bool = it.next().done; 183 // returns true 184 ``` 185 186 A returned iterator does **not** iterate over partially full circular buffers. 187 188 ```javascript 189 var buf = circularBuffer( 5 ); 190 191 // Add values to the buffer: 192 buf.push( 'foo' ); 193 buf.push( 'bar' ); 194 195 // Create an iterator: 196 var it = buf.iterator(); 197 198 // Determine if the buffer is full: 199 var bool = buf.full; 200 // returns false 201 202 // Iterate over the buffer... 203 bool = it.next().done; 204 // returns true 205 ``` 206 207 If iterating over a partially full circular buffer is necessary, use `buf.toArray()` and iterate over the returned array. 208 209 ##### buf.length 210 211 Buffer length (capacity). 212 213 ```javascript 214 var buf = circularBuffer( new Array( 3 ) ); 215 216 // Get the buffer length: 217 var len = buf.length; 218 // returns 3 219 ``` 220 221 ##### buf.push( value ) 222 223 Adds a value to the buffer. 224 225 ```javascript 226 var buf = circularBuffer( 3 ); 227 228 // Fill the buffer... 229 var v = buf.push( 'foo' ); 230 // returns undefined 231 232 v = buf.push( 'bar' ); 233 // returns undefined 234 235 v = buf.push( 'beep' ); 236 // returns undefined 237 238 // Now that the buffer is full, each push will cause a value to be removed: 239 v = buf.push( 'boop' ); 240 // returns 'foo' 241 ``` 242 243 When a circular buffer is empty or partially full, this method returns `undefined`. Once a circular buffer is **full**, the method returns removed values. 244 245 ##### buf.toArray() 246 247 Returns an array of buffer values. 248 249 ```javascript 250 var buf = circularBuffer( 3 ); 251 252 // Add values to the buffer: 253 buf.push( 'foo' ); 254 buf.push( 'bar' ); 255 buf.push( 'beep' ); 256 buf.push( 'boop' ); 257 258 // Get an array of buffer values: 259 var vals = buf.toArray(); 260 // returns [ 'bar', 'beep', 'boop' ] 261 ``` 262 263 ##### buf.toJSON() 264 265 Serializes a circular buffer as JSON. 266 267 ```javascript 268 var buf = circularBuffer( 3 ); 269 270 // Add values to the buffer: 271 buf.push( 'foo' ); 272 buf.push( 'bar' ); 273 buf.push( 'beep' ); 274 buf.push( 'boop' ); 275 276 // Serialize to JSON: 277 var o = buf.toJSON(); 278 // returns { 'type': 'circular-buffer', 'length': 3, 'data': [ 'bar', 'beep', 'boop' ] } 279 ``` 280 281 **Note**: `JSON.stringify()` implicitly calls this method when stringifying a circular buffer instance. 282 283 </section> 284 285 <!-- /.usage --> 286 287 <!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 288 289 <section class="notes"> 290 291 </section> 292 293 <!-- /.notes --> 294 295 <!-- Package usage examples. --> 296 297 <section class="examples"> 298 299 ## Examples 300 301 <!-- eslint no-undef: "error" --> 302 303 ```javascript 304 var circularBuffer = require( '@stdlib/utils/circular-buffer' ); 305 306 var buf; 307 var v; 308 var i; 309 310 // Create a circular buffer capable of holding 5 elements: 311 buf = circularBuffer( 5 ); 312 console.log( 'Buffer length: %s', buf.length ); 313 314 // Continuously add values to the buffer... 315 for ( i = 0; i < 100; i++ ) { 316 v = buf.push( i ); 317 console.log( 'Count: %d. Added value: %s. Removed value: %s.', buf.count, i, ( v === void 0 ) ? '(none)' : v ); 318 } 319 ``` 320 321 </section> 322 323 <!-- /.examples --> 324 325 <!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 326 327 <section class="references"> 328 329 </section> 330 331 <!-- /.references --> 332 333 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 334 335 <section class="links"> 336 337 </section> 338 339 <!-- /.links -->