Skip to content

Commit

Permalink
README: Add frozen netstring example
Browse files Browse the repository at this point in the history
  • Loading branch information
gibson042 authored Oct 6, 2024
1 parent 8eeea75 commit 07410ef
Showing 1 changed file with 24 additions and 0 deletions.
24 changes: 24 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,30 @@ An immutable buffer cannot be detached, resized, or further transferred. Its `ma

The ArrayBuffer `slice` method and TypedArray methods that create new ArrayBuffers (`filter`, `map`, `slice`, `toReversed`, etc.) make no effort to preserve immutability, just like they make no effort to preserve resizability (although use of SpeciesConstructor in those methods means that _lack_ of resizability/immutability in the result cannot be guaranteed for the latter).

## Use cases

### Represent arbitrary binary data as an immutable [netstring](https://en.wikipedia.org/wiki/Netstring)

```js
// Read data from base64 input and calculate its length.
const data = Uint8Array.fromBase64(inputBase64);
const dataLen = data.length;
const dataLenStr = String(dataLen);
const digitCount = dataLenStr.length;
// Transfer to a new ArrayBuffer with room for the netstring framing.
const tmpBuf = data.buffer.transfer(digitCount + 1 + dataLen + 1);
const tmpArr = new Uint8Array(tmpBuf);
assert(tmpArr.buffer === tmpBuf);
// Frame the data.
tmpArr.copyWithin(digitCount + 1, 0);
for (let i = 0; i < digitCount; i++) tmpArr[i] = dataLenStr.charCodeAt(i);
tmpArr[digitCount] = 0x3A;
tmpArr[tmpArr.length - 1] = 0x2C;
// Transfer to an immutable ArrayBuffer backing a frozen Uint8Array.
const netstringArr = Object.freeze(new Uint8Array(tmpBuf.transferToImmutable()));
assert(tmpBuf.detached);
```

## Implementations

### Polyfill/transpiler implementations
Expand Down

0 comments on commit 07410ef

Please sign in to comment.