source: trip-planner-front/node_modules/smart-buffer/README.md@ 571e0df

Last change on this file since 571e0df was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 18.3 KB
Line 
1smart-buffer [![Build Status](https://travis-ci.org/JoshGlazebrook/smart-buffer.svg?branch=master)](https://travis-ci.org/JoshGlazebrook/smart-buffer) [![Coverage Status](https://coveralls.io/repos/github/JoshGlazebrook/smart-buffer/badge.svg?branch=master)](https://coveralls.io/github/JoshGlazebrook/smart-buffer?branch=master)
2=============
3
4smart-buffer is a Buffer wrapper that adds automatic read & write offset tracking, string operations, data insertions, and more.
5
6![stats](https://nodei.co/npm/smart-buffer.png?downloads=true&downloadRank=true&stars=true "stats")
7
8**Key Features**:
9* Proxies all of the Buffer write and read functions
10* Keeps track of read and write offsets automatically
11* Grows the internal Buffer as needed
12* Useful string operations. (Null terminating strings)
13* Allows for inserting values at specific points in the Buffer
14* Built in TypeScript
15* Type Definitions Provided
16* Browser Support (using Webpack/Browserify)
17* Full test coverage
18
19**Requirements**:
20* Node v4.0+ is supported at this time. (Versions prior to 2.0 will work on node 0.10)
21
22
23
24## Breaking Changes in v4.0
25
26* Old constructor patterns have been completely removed. It's now required to use the SmartBuffer.fromXXX() factory constructors.
27* rewind(), skip(), moveTo() have been removed. (see [offsets](#offsets))
28* Internal private properties are now prefixed with underscores (_)
29* **All** writeXXX() methods that are given an offset will now **overwrite data** instead of insert. (see [write vs insert](#write-vs-insert))
30* insertXXX() methods have been added for when you want to insert data at a specific offset (this replaces the old behavior of writeXXX() when an offset was provided)
31
32
33## Looking for v3 docs?
34
35Legacy documentation for version 3 and prior can be found [here](https://github.com/JoshGlazebrook/smart-buffer/blob/master/docs/README_v3.md).
36
37## Installing:
38
39`yarn add smart-buffer`
40
41or
42
43`npm install smart-buffer`
44
45Note: The published NPM package includes the built javascript library.
46If you cloned this repo and wish to build the library manually use:
47
48`npm run build`
49
50## Using smart-buffer
51
52```javascript
53// Javascript
54const SmartBuffer = require('smart-buffer').SmartBuffer;
55
56// Typescript
57import { SmartBuffer, SmartBufferOptions} from 'smart-buffer';
58```
59
60### Simple Example
61
62Building a packet that uses the following protocol specification:
63
64`[PacketType:2][PacketLength:2][Data:XX]`
65
66To build this packet using the vanilla Buffer class, you would have to count up the length of the data payload beforehand. You would also need to keep track of the current "cursor" position in your Buffer so you write everything in the right places. With smart-buffer you don't have to do either of those things.
67
68```javascript
69function createLoginPacket(username, password, age, country) {
70 const packet = new SmartBuffer();
71 packet.writeUInt16LE(0x0060); // Some packet type
72 packet.writeStringNT(username);
73 packet.writeStringNT(password);
74 packet.writeUInt8(age);
75 packet.writeStringNT(country);
76 packet.insertUInt16LE(packet.length - 2, 2);
77
78 return packet.toBuffer();
79}
80```
81With the above function, you now can do this:
82```javascript
83const login = createLoginPacket("Josh", "secret123", 22, "United States");
84
85// <Buffer 60 00 1e 00 4a 6f 73 68 00 73 65 63 72 65 74 31 32 33 00 16 55 6e 69 74 65 64 20 53 74 61 74 65 73 00>
86```
87Notice that the `[PacketLength:2]` value (1e 00) was inserted at position 2.
88
89Reading back the packet we created above is just as easy:
90```javascript
91
92const reader = SmartBuffer.fromBuffer(login);
93
94const logininfo = {
95 packetType: reader.readUInt16LE(),
96 packetLength: reader.readUInt16LE(),
97 username: reader.readStringNT(),
98 password: reader.readStringNT(),
99 age: reader.readUInt8(),
100 country: reader.readStringNT()
101};
102
103/*
104{
105 packetType: 96, (0x0060)
106 packetLength: 30,
107 username: 'Josh',
108 password: 'secret123',
109 age: 22,
110 country: 'United States'
111}
112*/
113```
114
115
116## Write vs Insert
117In prior versions of SmartBuffer, .writeXXX(value, offset) calls would insert data when an offset was provided. In version 4, this will now overwrite the data at the offset position. To insert data there are now corresponding .insertXXX(value, offset) methods.
118
119**SmartBuffer v3**:
120```javascript
121const buff = SmartBuffer.fromBuffer(new Buffer([1,2,3,4,5,6]));
122buff.writeInt8(7, 2);
123console.log(buff.toBuffer())
124
125// <Buffer 01 02 07 03 04 05 06>
126```
127
128**SmartBuffer v4**:
129```javascript
130const buff = SmartBuffer.fromBuffer(new Buffer([1,2,3,4,5,6]));
131buff.writeInt8(7, 2);
132console.log(buff.toBuffer());
133
134// <Buffer 01 02 07 04 05 06>
135```
136
137To insert you instead should use:
138```javascript
139const buff = SmartBuffer.fromBuffer(new Buffer([1,2,3,4,5,6]));
140buff.insertInt8(7, 2);
141console.log(buff.toBuffer());
142
143// <Buffer 01 02 07 03 04 05 06>
144```
145
146**Note:** Insert/Writing to a position beyond the currently tracked internal Buffer will zero pad to your offset.
147
148## Constructing a smart-buffer
149
150There are a few different ways to construct a SmartBuffer instance.
151
152```javascript
153// Creating SmartBuffer from existing Buffer
154const buff = SmartBuffer.fromBuffer(buffer); // Creates instance from buffer. (Uses default utf8 encoding)
155const buff = SmartBuffer.fromBuffer(buffer, 'ascii'); // Creates instance from buffer with ascii encoding for strings.
156
157// Creating SmartBuffer with specified internal Buffer size. (Note: this is not a hard cap, the internal buffer will grow as needed).
158const buff = SmartBuffer.fromSize(1024); // Creates instance with internal Buffer size of 1024.
159const buff = SmartBuffer.fromSize(1024, 'utf8'); // Creates instance with internal Buffer size of 1024, and utf8 encoding for strings.
160
161// Creating SmartBuffer with options object. This one specifies size and encoding.
162const buff = SmartBuffer.fromOptions({
163 size: 1024,
164 encoding: 'ascii'
165});
166
167// Creating SmartBuffer with options object. This one specified an existing Buffer.
168const buff = SmartBuffer.fromOptions({
169 buff: buffer
170});
171
172// Creating SmartBuffer from a string.
173const buff = SmartBuffer.fromBuffer(Buffer.from('some string', 'utf8'));
174
175// Just want a regular SmartBuffer with all default options?
176const buff = new SmartBuffer();
177```
178
179# Api Reference:
180
181**Note:** SmartBuffer is fully documented with Typescript definitions as well as jsdocs so your favorite editor/IDE will have intellisense.
182
183**Table of Contents**
184
1851. [Constructing](#constructing)
1862. **Numbers**
187 1. [Integers](#integers)
188 2. [Floating Points](#floating-point-numbers)
1893. **Strings**
190 1. [Strings](#strings)
191 2. [Null Terminated Strings](#null-terminated-strings)
1924. [Buffers](#buffers)
1935. [Offsets](#offsets)
1946. [Other](#other)
195
196
197## Constructing
198
199### constructor()
200### constructor([options])
201- ```options``` *{SmartBufferOptions}* An optional options object to construct a SmartBuffer with.
202
203Examples:
204```javascript
205const buff = new SmartBuffer();
206const buff = new SmartBuffer({
207 size: 1024,
208 encoding: 'ascii'
209});
210```
211
212### Class Method: fromBuffer(buffer[, encoding])
213- ```buffer``` *{Buffer}* The Buffer instance to wrap.
214- ```encoding``` *{string}* The string encoding to use. ```Default: 'utf8'```
215
216Examples:
217```javascript
218const someBuffer = Buffer.from('some string');
219const buff = SmartBuffer.fromBuffer(someBuffer); // Defaults to utf8
220const buff = SmartBuffer.fromBuffer(someBuffer, 'ascii');
221```
222
223### Class Method: fromSize(size[, encoding])
224- ```size``` *{number}* The size to initialize the internal Buffer.
225- ```encoding``` *{string}* The string encoding to use. ```Default: 'utf8'```
226
227Examples:
228```javascript
229const buff = SmartBuffer.fromSize(1024); // Defaults to utf8
230const buff = SmartBuffer.fromSize(1024, 'ascii');
231```
232
233### Class Method: fromOptions(options)
234- ```options``` *{SmartBufferOptions}* The Buffer instance to wrap.
235
236```typescript
237interface SmartBufferOptions {
238 encoding?: BufferEncoding; // Defaults to utf8
239 size?: number; // Defaults to 4096
240 buff?: Buffer;
241}
242```
243
244Examples:
245```javascript
246const buff = SmartBuffer.fromOptions({
247 size: 1024
248};
249const buff = SmartBuffer.fromOptions({
250 size: 1024,
251 encoding: 'utf8'
252});
253const buff = SmartBuffer.fromOptions({
254 encoding: 'utf8'
255});
256
257const someBuff = Buffer.from('some string', 'utf8');
258const buff = SmartBuffer.fromOptions({
259 buffer: someBuff,
260 encoding: 'utf8'
261});
262```
263
264## Integers
265
266### buff.readInt8([offset])
267### buff.readUInt8([offset])
268- ```offset``` *{number}* Optional position to start reading data from. **Default**: ```Auto managed offset```
269- Returns *{number}*
270
271Read a Int8 value.
272
273### buff.readInt16BE([offset])
274### buff.readInt16LE([offset])
275### buff.readUInt16BE([offset])
276### buff.readUInt16LE([offset])
277- ```offset``` *{number}* Optional position to start reading data from. **Default**: ```Auto managed offset```
278- Returns *{number}*
279
280Read a 16 bit integer value.
281
282### buff.readInt32BE([offset])
283### buff.readInt32LE([offset])
284### buff.readUInt32BE([offset])
285### buff.readUInt32LE([offset])
286- ```offset``` *{number}* Optional position to start reading data from. **Default**: ```Auto managed offset```
287- Returns *{number}*
288
289Read a 32 bit integer value.
290
291
292### buff.writeInt8(value[, offset])
293### buff.writeUInt8(value[, offset])
294- ```value``` *{number}* The value to write.
295- ```offset``` *{number}* An optional offset to write this value to. **Default:** ```Auto managed offset```
296- Returns *{this}*
297
298Write a Int8 value.
299
300### buff.insertInt8(value, offset)
301### buff.insertUInt8(value, offset)
302- ```value``` *{number}* The value to insert.
303- ```offset``` *{number}* The offset to insert this data at.
304- Returns *{this}*
305
306Insert a Int8 value.
307
308
309### buff.writeInt16BE(value[, offset])
310### buff.writeInt16LE(value[, offset])
311### buff.writeUInt16BE(value[, offset])
312### buff.writeUInt16LE(value[, offset])
313- ```value``` *{number}* The value to write.
314- ```offset``` *{number}* An optional offset to write this value to. **Default:** ```Auto managed offset```
315- Returns *{this}*
316
317Write a 16 bit integer value.
318
319### buff.insertInt16BE(value, offset)
320### buff.insertInt16LE(value, offset)
321### buff.insertUInt16BE(value, offset)
322### buff.insertUInt16LE(value, offset)
323- ```value``` *{number}* The value to insert.
324- ```offset``` *{number}* The offset to insert this data at.
325- Returns *{this}*
326
327Insert a 16 bit integer value.
328
329
330### buff.writeInt32BE(value[, offset])
331### buff.writeInt32LE(value[, offset])
332### buff.writeUInt32BE(value[, offset])
333### buff.writeUInt32LE(value[, offset])
334- ```value``` *{number}* The value to write.
335- ```offset``` *{number}* An optional offset to write this value to. **Default:** ```Auto managed offset```
336- Returns *{this}*
337
338Write a 32 bit integer value.
339
340### buff.insertInt32BE(value, offset)
341### buff.insertInt32LE(value, offset)
342### buff.insertUInt32BE(value, offset)
343### buff.nsertUInt32LE(value, offset)
344- ```value``` *{number}* The value to insert.
345- ```offset``` *{number}* The offset to insert this data at.
346- Returns *{this}*
347
348Insert a 32 bit integer value.
349
350
351## Floating Point Numbers
352
353### buff.readFloatBE([offset])
354### buff.readFloatLE([offset])
355- ```offset``` *{number}* Optional position to start reading data from. **Default**: ```Auto managed offset```
356- Returns *{number}*
357
358Read a Float value.
359
360### buff.readDoubleBE([offset])
361### buff.readDoubleLE([offset])
362- ```offset``` *{number}* Optional position to start reading data from. **Default**: ```Auto managed offset```
363- Returns *{number}*
364
365Read a Double value.
366
367
368### buff.writeFloatBE(value[, offset])
369### buff.writeFloatLE(value[, offset])
370- ```value``` *{number}* The value to write.
371- ```offset``` *{number}* An optional offset to write this value to. **Default:** ```Auto managed offset```
372- Returns *{this}*
373
374Write a Float value.
375
376### buff.insertFloatBE(value, offset)
377### buff.insertFloatLE(value, offset)
378- ```value``` *{number}* The value to insert.
379- ```offset``` *{number}* The offset to insert this data at.
380- Returns *{this}*
381
382Insert a Float value.
383
384
385### buff.writeDoubleBE(value[, offset])
386### buff.writeDoubleLE(value[, offset])
387- ```value``` *{number}* The value to write.
388- ```offset``` *{number}* An optional offset to write this value to. **Default:** ```Auto managed offset```
389- Returns *{this}*
390
391Write a Double value.
392
393### buff.insertDoubleBE(value, offset)
394### buff.insertDoubleLE(value, offset)
395- ```value``` *{number}* The value to insert.
396- ```offset``` *{number}* The offset to insert this data at.
397- Returns *{this}*
398
399Insert a Double value.
400
401## Strings
402
403### buff.readString()
404### buff.readString(size[, encoding])
405### buff.readString(encoding)
406- ```size``` *{number}* The number of bytes to read. **Default:** ```Reads to the end of the Buffer.```
407- ```encoding``` *{string}* The string encoding to use. **Default:** ```utf8```.
408
409Read a string value.
410
411Examples:
412```javascript
413const buff = SmartBuffer.fromBuffer(Buffer.from('hello there', 'utf8'));
414buff.readString(); // 'hello there'
415buff.readString(2); // 'he'
416buff.readString(2, 'utf8'); // 'he'
417buff.readString('utf8'); // 'hello there'
418```
419
420### buff.writeString(value)
421### buff.writeString(value[, offset])
422### buff.writeString(value[, encoding])
423### buff.writeString(value[, offset[, encoding]])
424- ```value``` *{string}* The string value to write.
425- ```offset``` *{number}* The offset to write this value to. **Default:** ```Auto managed offset```
426- ```encoding``` *{string}* An optional string encoding to use. **Default:** ```utf8```
427
428Write a string value.
429
430Examples:
431```javascript
432buff.writeString('hello'); // Auto managed offset
433buff.writeString('hello', 2);
434buff.writeString('hello', 'utf8') // Auto managed offset
435buff.writeString('hello', 2, 'utf8');
436```
437
438### buff.insertString(value, offset[, encoding])
439- ```value``` *{string}* The string value to write.
440- ```offset``` *{number}* The offset to write this value to.
441- ```encoding``` *{string}* An optional string encoding to use. **Default:** ```utf8```
442
443Insert a string value.
444
445Examples:
446```javascript
447buff.insertString('hello', 2);
448buff.insertString('hello', 2, 'utf8');
449```
450
451## Null Terminated Strings
452
453### buff.readStringNT()
454### buff.readStringNT(encoding)
455- ```encoding``` *{string}* The string encoding to use. **Default:** ```utf8```.
456
457Read a null terminated string value. (If a null is not found, it will read to the end of the Buffer).
458
459Examples:
460```javascript
461const buff = SmartBuffer.fromBuffer(Buffer.from('hello\0 there', 'utf8'));
462buff.readStringNT(); // 'hello'
463
464// If we called this again:
465buff.readStringNT(); // ' there'
466```
467
468### buff.writeStringNT(value)
469### buff.writeStringNT(value[, offset])
470### buff.writeStringNT(value[, encoding])
471### buff.writeStringNT(value[, offset[, encoding]])
472- ```value``` *{string}* The string value to write.
473- ```offset``` *{number}* The offset to write this value to. **Default:** ```Auto managed offset```
474- ```encoding``` *{string}* An optional string encoding to use. **Default:** ```utf8```
475
476Write a null terminated string value.
477
478Examples:
479```javascript
480buff.writeStringNT('hello'); // Auto managed offset <Buffer 68 65 6c 6c 6f 00>
481buff.writeStringNT('hello', 2); // <Buffer 00 00 68 65 6c 6c 6f 00>
482buff.writeStringNT('hello', 'utf8') // Auto managed offset
483buff.writeStringNT('hello', 2, 'utf8');
484```
485
486### buff.insertStringNT(value, offset[, encoding])
487- ```value``` *{string}* The string value to write.
488- ```offset``` *{number}* The offset to write this value to.
489- ```encoding``` *{string}* An optional string encoding to use. **Default:** ```utf8```
490
491Insert a null terminated string value.
492
493Examples:
494```javascript
495buff.insertStringNT('hello', 2);
496buff.insertStringNT('hello', 2, 'utf8');
497```
498
499## Buffers
500
501### buff.readBuffer([length])
502- ```length``` *{number}* The number of bytes to read into a Buffer. **Default:** ```Reads to the end of the Buffer```
503
504Read a Buffer of a specified size.
505
506### buff.writeBuffer(value[, offset])
507- ```value``` *{Buffer}* The buffer value to write.
508- ```offset``` *{number}* An optional offset to write the value to. **Default:** ```Auto managed offset```
509
510### buff.insertBuffer(value, offset)
511- ```value``` *{Buffer}* The buffer value to write.
512- ```offset``` *{number}* The offset to write the value to.
513
514
515### buff.readBufferNT()
516
517Read a null terminated Buffer.
518
519### buff.writeBufferNT(value[, offset])
520- ```value``` *{Buffer}* The buffer value to write.
521- ```offset``` *{number}* An optional offset to write the value to. **Default:** ```Auto managed offset```
522
523Write a null terminated Buffer.
524
525
526### buff.insertBufferNT(value, offset)
527- ```value``` *{Buffer}* The buffer value to write.
528- ```offset``` *{number}* The offset to write the value to.
529
530Insert a null terminated Buffer.
531
532
533## Offsets
534
535### buff.readOffset
536### buff.readOffset(offset)
537- ```offset``` *{number}* The new read offset value to set.
538- Returns: ```The current read offset```
539
540Gets or sets the current read offset.
541
542Examples:
543```javascript
544const currentOffset = buff.readOffset; // 5
545
546buff.readOffset = 10;
547
548console.log(buff.readOffset) // 10
549```
550
551### buff.writeOffset
552### buff.writeOffset(offset)
553- ```offset``` *{number}* The new write offset value to set.
554- Returns: ```The current write offset```
555
556Gets or sets the current write offset.
557
558Examples:
559```javascript
560const currentOffset = buff.writeOffset; // 5
561
562buff.writeOffset = 10;
563
564console.log(buff.writeOffset) // 10
565```
566
567### buff.encoding
568### buff.encoding(encoding)
569- ```encoding``` *{string}* The new string encoding to set.
570- Returns: ```The current string encoding```
571
572Gets or sets the current string encoding.
573
574Examples:
575```javascript
576const currentEncoding = buff.encoding; // 'utf8'
577
578buff.encoding = 'ascii';
579
580console.log(buff.encoding) // 'ascii'
581```
582
583## Other
584
585### buff.clear()
586
587Clear and resets the SmartBuffer instance.
588
589### buff.remaining()
590- Returns ```Remaining data left to be read```
591
592Gets the number of remaining bytes to be read.
593
594
595### buff.internalBuffer
596- Returns: *{Buffer}*
597
598Gets the internally managed Buffer (Includes unmanaged data).
599
600Examples:
601```javascript
602const buff = SmartBuffer.fromSize(16);
603buff.writeString('hello');
604console.log(buff.InternalBuffer); // <Buffer 68 65 6c 6c 6f 00 00 00 00 00 00 00 00 00 00 00>
605```
606
607### buff.toBuffer()
608- Returns: *{Buffer}*
609
610Gets a sliced Buffer instance of the internally managed Buffer. (Only includes managed data)
611
612Examples:
613```javascript
614const buff = SmartBuffer.fromSize(16);
615buff.writeString('hello');
616console.log(buff.toBuffer()); // <Buffer 68 65 6c 6c 6f>
617```
618
619### buff.toString([encoding])
620- ```encoding``` *{string}* The string encoding to use when converting to a string. **Default:** ```utf8```
621- Returns *{string}*
622
623Gets a string representation of all data in the SmartBuffer.
624
625### buff.destroy()
626
627Destroys the SmartBuffer instance.
628
629
630
631## License
632
633This work is licensed under the [MIT license](http://en.wikipedia.org/wiki/MIT_License).
Note: See TracBrowser for help on using the repository browser.