Added readChars and writeChars methods

Author: Wiiseguy

CHANGELOG.md

@@ -1,5 +1,9 @@
 # **streambuf** Changelog
 
+### [2.1.0] (27-dec-2025)
+
+-   Added `readChars` and `writeChars` methods
+
 ### [2.0.0] (4-jul-2024)
 
 -   Removed support for non-new constructor, changed export

README.md

@@ -103,6 +103,16 @@ Reads a single character from the buffer according to the specified character en
 Writes a single character to the buffer according to the specified character encoding. Multi-byte characters are not written - use `writeString` for that instead.
 'encoding' defaults to utf8.
 
+## .readChars(length, [encoding])
+
+Reads a fixed number of characters from the buffer according to the specified character encoding. The resulting string strips any trailing null characters.
+'encoding' defaults to utf8.
+
+## .writeChars(str, length, [encoding])
+
+Writes a string to the underlying buffer with the specified encoding, padding with null characters (0) if the string is shorter than length.
+'encoding' defaults to utf8.
+
 ## .readString([length, [encoding]])
 
 Decodes to a string according to the specified character encoding in encoding and length.
@@ -120,7 +130,7 @@ Functions the same way as .readString(), but does not update the offset.
 
 ## .readString0([encoding])
 
-Reads a string from the buffer according to the specified character encoding, stopping at the first zero (0) byte. Similar to calling .readString() without a length parameter, but more implicit.
+Reads a string from the buffer according to the specified character encoding, stopping at the first zero (0) byte. Similar to `.readString()` or `.readString(undefined, encoding)`, but more implicit.
 'encoding' defaults to utf8.
 
 ### Example:

lib/streambuf.d.ts

@@ -58,10 +58,12 @@ export declare class StreamBuffer {
     write(src: Buffer): Buffer<ArrayBufferLike>;
     readString(length?: number, encoding?: BufferEncoding): string;
     readChar(encoding?: BufferEncoding): string;
+    readChars(length: number, encoding?: BufferEncoding): string;
     readString7(encoding?: BufferEncoding): string;
     readString0(encoding?: BufferEncoding): string;
     writeString(val: string, encoding?: BufferEncoding): string;
     writeChar(val: string, encoding?: BufferEncoding): string;
+    writeChars(val: string, length: number, encoding?: BufferEncoding): string;
     writeString7(val: string, encoding?: BufferEncoding): string;
     writeString0(val: string, encoding?: BufferEncoding): string;
     peekString(length?: number, encoding?: BufferEncoding): string;

lib/streambuf.js

@@ -6,6 +6,7 @@
   "scripts": {
     "test": "aqa",
     "test:watch": "aqa --watch",
+    "tsc:watch": "npx tsc --watch",
     "test:coverage": "c8 npm test & c8 report -r lcov"
   },
   "repository": {
@@ -41,4 +42,4 @@
     "aqa": "^1.6.12",
     "c8": "^10.1.3"
   }
-}
+}

lib/streambuf.js.map

@@ -261,6 +261,14 @@ export class StreamBuffer {
     readChar(encoding?: BufferEncoding) {
         return this.readString(1, encoding)
     }
+    readChars(length: number, encoding?: BufferEncoding) {
+        const str = this.readString(length, encoding)
+        const nullIndex = str.indexOf('\0')
+        if (nullIndex !== -1) {
+            return str.substring(0, nullIndex)
+        }
+        return str
+    }
     readString7(encoding?: BufferEncoding) {
         const len = this.read7BitInt()
         return this.readString(len, encoding)
@@ -276,6 +284,14 @@ export class StreamBuffer {
         this.#pos = this.#pos + this.#buf.write(val, this.#pos, 1, encoding)
         return val
     }
+    writeChars(val: string, length: number, encoding?: BufferEncoding) {
+        const bytesWritten = this.#buf.write(val, this.#pos, length, encoding)
+        this.#pos = this.#pos + bytesWritten
+        for (let i = bytesWritten; i < length; i++) {
+            this.writeByte(0)
+        }
+        return val
+    }
     writeString7(val: string, encoding?: BufferEncoding) {
         const len = Buffer.byteLength(val, encoding)
         this.write7BitInt(len)

lib/test.js

@@ -373,6 +373,7 @@ test('correct position increase (numeric methods)', t => {
         'readString7',
         'readString0',
         'readChar',
+        'readChars',
         'read7BitInt',
         'readIntLE',
         'readIntBE',
@@ -389,6 +390,7 @@ test('correct position increase (numeric methods)', t => {
         'writeString7',
         'writeString0',
         'writeChar',
+        'writeChars',
         'write7BitInt',
         'writeIntLE',
         'writeIntBE',
@@ -692,6 +694,22 @@ test('writeChar - multibyte utf8 strings', t => {
     t.deepEqual(buffer, [0, 0, 0, 0])
 })
 
+test('readChars', t => {
+    const buffer = Buffer.from('hi\x00\x00\x00world')
+    const sb = new StreamBuffer(buffer)
+
+    t.is(sb.readChars(5), 'hi')
+    t.is(sb.readChars(5), 'world')
+})
+
+test('writeChars', t => {
+    const buffer = Buffer.alloc(10)
+    const sb = new StreamBuffer(buffer)
+    sb.writeChars('hi', 5)
+    sb.writeChars('world', 5)
+    t.deepEqual(buffer, Buffer.from('hi\x00\x00\x00world'))
+})
+
 test('isEOF tests', t => {
     const buffer = Buffer.from([0, 1, 2])
     const sb = new StreamBuffer(buffer)