source: trip-planner-front/node_modules/smart-buffer/docs/README_v3.md

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

initial commit

  • Property mode set to 100644
File size: 12.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 light Buffer wrapper that takes away the need to keep track of what position to read and write data to and from the underlying Buffer. It also adds null terminating string operations and **grows** as you add more data.
5
6![stats](https://nodei.co/npm/smart-buffer.png?downloads=true&downloadRank=true&stars=true "stats")
7
8### What it's useful for:
9
10I created smart-buffer because I wanted to simplify the process of using Buffer for building and reading network packets to send over a socket. Rather than having to keep track of which position I need to write a UInt16 to after adding a string of variable length, I simply don't have to.
11
12Key Features:
13* Proxies all of the Buffer write and read functions.
14* Keeps track of read and write positions for you.
15* Grows the internal Buffer as you add data to it.
16* Useful string operations. (Null terminating strings)
17* Allows for inserting values at specific points in the internal Buffer.
18* Built in TypeScript
19* Type Definitions Provided
20
21Requirements:
22* Node v4.0+ is supported at this time. (Versions prior to 2.0 will work on node 0.10)
23
24
25#### Note:
26smart-buffer can be used for writing to an underlying buffer as well as reading from it. It however does not function correctly if you're mixing both read and write operations with each other.
27
28## Breaking Changes with 2.0
29The latest version (2.0+) is written in TypeScript, and are compiled to ES6 Javascript. This means the earliest Node.js it supports will be 4.x (in strict mode.) If you're using version 6 and above it will work without any issues. From an API standpoint, 2.0 is backwards compatible. The only difference is SmartBuffer is not exported directly as the root module.
30
31## Breaking Changes with 3.0
32Starting with 3.0, if any of the readIntXXXX() methods are called and the requested data is larger than the bounds of the internally managed valid buffer data, an exception will now be thrown.
33
34## Installing:
35
36`npm install smart-buffer`
37
38or
39
40`yarn add smart-buffer`
41
42Note: The published NPM package includes the built javascript library.
43If you cloned this repo and wish to build the library manually use:
44
45`tsc -p ./`
46
47## Using smart-buffer
48
49### Example
50
51Say you were building a packet that had to conform to the following protocol:
52
53`[PacketType:2][PacketLength:2][Data:XX]`
54
55To 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.
56
57```javascript
58// 1.x (javascript)
59var SmartBuffer = require('smart-buffer');
60
61// 1.x (typescript)
62import SmartBuffer = require('smart-buffer');
63
64// 2.x+ (javascript)
65const SmartBuffer = require('smart-buffer').SmartBuffer;
66
67// 2.x+ (typescript)
68import { SmartBuffer, SmartBufferOptions} from 'smart-buffer';
69
70function createLoginPacket(username, password, age, country) {
71 let packet = new SmartBuffer();
72 packet.writeUInt16LE(0x0060); // Login Packet Type/ID
73 packet.writeStringNT(username);
74 packet.writeStringNT(password);
75 packet.writeUInt8(age);
76 packet.writeStringNT(country);
77 packet.writeUInt16LE(packet.length - 2, 2);
78
79 return packet.toBuffer();
80}
81```
82With the above function, you now can do this:
83```javascript
84let login = createLoginPacket("Josh", "secret123", 22, "United States");
85
86// <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>
87```
88Notice that the `[PacketLength:2]` part of the packet was inserted after we had added everything else, and as shown in the Buffer dump above, is in the correct location along with everything else.
89
90Reading back the packet we created above is just as easy:
91```javascript
92
93let reader = SmartBuffer.fromBuffer(login);
94
95let logininfo = {
96 packetType: reader.readUInt16LE(),
97 packetLength: reader.readUInt16LE(),
98 username: reader.readStringNT(),
99 password: reader.readStringNT(),
100 age: reader.readUInt8(),
101 country: reader.readStringNT()
102};
103
104/*
105{
106 packetType: 96, (0x0060)
107 packetLength: 30,
108 username: 'Josh',
109 password: 'secret123',
110 age: 22,
111 country: 'United States'
112};
113*/
114```
115
116# Api Reference:
117
118### Constructing a smart-buffer
119
120smart-buffer has a few different ways to construct an instance. Starting with version 2.0, the following factory methods are preffered.
121
122```javascript
123let SmartBuffer = require('smart-buffer');
124
125// Creating SmartBuffer from existing Buffer
126let buff = SmartBuffer.fromBuffer(buffer); // Creates instance from buffer. (Uses default utf8 encoding)
127let buff = SmartBuffer.fromBuffer(buffer, 'ascii'); // Creates instance from buffer with ascii encoding for Strings.
128
129// Creating SmartBuffer with specified internal Buffer size.
130let buff = SmartBuffer.fromSize(1024); // Creates instance with internal Buffer size of 1024.
131let buff = SmartBuffer.fromSize(1024, 'utf8'); // Creates instance with intenral Buffer size of 1024, and utf8 encoding.
132
133// Creating SmartBuffer with options object. This one specifies size and encoding.
134let buff = SmartBuffer.fromOptions({
135 size: 1024,
136 encoding: 'ascii'
137});
138
139// Creating SmartBuffer with options object. This one specified an existing Buffer.
140let buff = SmartBuffer.fromOptions({
141 buff: buffer
142});
143
144// Just want a regular SmartBuffer with all default options?
145let buff = new SmartBuffer();
146```
147
148## Backwards Compatibility:
149
150All constructors used prior to 2.0 still are supported. However it's not recommended to use these.
151
152```javascript
153let writer = new SmartBuffer(); // Defaults to utf8, 4096 length internal Buffer.
154let writer = new SmartBuffer(1024); // Defaults to utf8, 1024 length internal Buffer.
155let writer = new SmartBuffer('ascii'); // Sets to ascii encoding, 4096 length internal buffer.
156let writer = new SmartBuffer(1024, 'ascii'); // Sets to ascii encoding, 1024 length internal buffer.
157```
158
159## Reading Data
160
161smart-buffer supports all of the common read functions you will find in the vanilla Buffer class. The only difference is, you do not need to specify which location to start reading from. This is possible because as you read data out of a smart-buffer, it automatically progresses an internal read offset/position to know where to pick up from on the next read.
162
163## Reading Numeric Values
164
165When numeric values, you simply need to call the function you want, and the data is returned.
166
167Supported Operations:
168* readInt8
169* readInt16BE
170* readInt16LE
171* readInt32BE
172* readInt32LE
173* readBigInt64LE
174* readBigInt64BE
175* readUInt8
176* readUInt16BE
177* readUInt16LE
178* readUInt32BE
179* readUInt32LE
180* readBigUInt64LE
181* readBigUInt64BE
182* readFloatBE
183* readFloatLE
184* readDoubleBE
185* readDoubleLE
186
187```javascript
188let reader = new SmartBuffer(somebuffer);
189let num = reader.readInt8();
190```
191
192## Reading String Values
193
194When reading String values, you can either choose to read a null terminated string, or a string of a specified length.
195
196### SmartBuffer.readStringNT( [encoding] )
197> `String` **String encoding to use** - Defaults to the encoding set in the constructor.
198
199returns `String`
200
201> Note: When readStringNT is called and there is no null character found, smart-buffer will read to the end of the internal Buffer.
202
203### SmartBuffer.readString( [length] )
204### SmartBuffer.readString( [encoding] )
205### SmartBuffer.readString( [length], [encoding] )
206> `Number` **Length of the string to read**
207
208> `String` **String encoding to use** - Defaults to the encoding set in the constructor, or utf8.
209
210returns `String`
211
212> Note: When readString is called without a specified length, smart-buffer will read to the end of the internal Buffer.
213
214
215
216## Reading Buffer Values
217
218### SmartBuffer.readBuffer( length )
219> `Number` **Length of data to read into a Buffer**
220
221returns `Buffer`
222
223> Note: This function uses `slice` to retrieve the Buffer.
224
225
226### SmartBuffer.readBufferNT()
227
228returns `Buffer`
229
230> Note: This reads the next sequence of bytes in the buffer until a null (0x00) value is found. (Null terminated buffer)
231> Note: This function uses `slice` to retrieve the Buffer.
232
233
234## Writing Data
235
236smart-buffer supports all of the common write functions you will find in the vanilla Buffer class. The only difference is, you do not need to specify which location to write to in your Buffer by default. You do however have the option of **inserting** a piece of data into your smart-buffer at a given location.
237
238
239## Writing Numeric Values
240
241
242For numeric values, you simply need to call the function you want, and the data is written at the end of the internal Buffer's current write position. You can specify a offset/position to **insert** the given value at, but keep in mind this does not override data at the given position. This feature also does not work properly when inserting a value beyond the current internal length of the smart-buffer (length being the .length property of the smart-buffer instance you're writing to)
243
244Supported Operations:
245* writeInt8
246* writeInt16BE
247* writeInt16LE
248* writeInt32BE
249* writeInt32LE
250* writeBigInt64BE
251* writeBigInt64LE
252* writeUInt8
253* writeUInt16BE
254* writeUInt16LE
255* writeUInt32BE
256* writeUInt32LE
257* writeBigUInt64BE
258* writeBigUInt64LE
259* writeFloatBE
260* writeFloatLE
261* writeDoubleBE
262* writeDoubleLE
263
264The following signature is the same for all the above functions:
265
266### SmartBuffer.writeInt8( value, [offset] )
267> `Number` **A valid Int8 number**
268
269> `Number` **The position to insert this value at**
270
271returns this
272
273> Note: All write operations return `this` to allow for chaining.
274
275## Writing String Values
276
277When reading String values, you can either choose to write a null terminated string, or a non null terminated string.
278
279### SmartBuffer.writeStringNT( value, [offset], [encoding] )
280### SmartBuffer.writeStringNT( value, [offset] )
281### SmartBuffer.writeStringNT( value, [encoding] )
282> `String` **String value to write**
283
284> `Number` **The position to insert this String at**
285
286> `String` **The String encoding to use.** - Defaults to the encoding set in the constructor, or utf8.
287
288returns this
289
290### SmartBuffer.writeString( value, [offset], [encoding] )
291### SmartBuffer.writeString( value, [offset] )
292### SmartBuffer.writeString( value, [encoding] )
293> `String` **String value to write**
294
295> `Number` **The position to insert this String at**
296
297> `String` **The String encoding to use** - Defaults to the encoding set in the constructor, or utf8.
298
299returns this
300
301
302## Writing Buffer Values
303
304### SmartBuffer.writeBuffer( value, [offset] )
305> `Buffer` **Buffer value to write**
306
307> `Number` **The position to insert this Buffer's content at**
308
309returns this
310
311### SmartBuffer.writeBufferNT( value, [offset] )
312> `Buffer` **Buffer value to write**
313
314> `Number` **The position to insert this Buffer's content at**
315
316returns this
317
318
319## Utility Functions
320
321### SmartBuffer.clear()
322Resets the SmartBuffer to its default state where it can be reused for reading or writing.
323
324### SmartBuffer.remaining()
325
326returns `Number` The amount of data left to read based on the current read Position.
327
328### SmartBuffer.skip( value )
329> `Number` **The amount of bytes to skip ahead**
330
331Skips the read position ahead by the given value.
332
333returns this
334
335### SmartBuffer.rewind( value )
336> `Number` **The amount of bytes to reward backwards**
337
338Rewinds the read position backwards by the given value.
339
340returns this
341
342### SmartBuffer.moveTo( position )
343> `Number` **The point to skip the read position to**
344
345Moves the read position to the given point.
346returns this
347
348### SmartBuffer.toBuffer()
349
350returns `Buffer` A Buffer containing the contents of the internal Buffer.
351
352> Note: This uses the slice function.
353
354### SmartBuffer.toString( [encoding] )
355> `String` **The String encoding to use** - Defaults to the encoding set in the constructor, or utf8.
356
357returns `String` The internal Buffer in String representation.
358
359## Properties
360
361### SmartBuffer.length
362
363returns `Number` **The length of the data that is being tracked in the internal Buffer** - Does NOT return the absolute length of the internal Buffer being written to.
364
365## License
366
367This work is licensed under the [MIT license](http://en.wikipedia.org/wiki/MIT_License).
Note: See TracBrowser for help on using the repository browser.