Skip to content

Append and consume bytes using only no-copy operations

License

Notifications You must be signed in to change notification settings

dao-xyz/uint8arraylist

 
 

Repository files navigation

uint8arraylist

codecov CI

Append and consume bytes using only no-copy operations

Table of contents

Install

$ npm i uint8arraylist

Browser <script> tag

Loading this module through a script tag will make it's exports available as Uint8arraylist in the global namespace.

<script src="https://unpkg.com/uint8arraylist/dist/index.min.js"></script>

Usage

import { Uint8ArrayList } from 'uint8arraylist'

const list = new Uint8ArrayList()
list.append(Uint8Array.from([0, 1, 2]))
list.append(Uint8Array.from([3, 4, 5]))

list.subarray()
// -> Uint8Array([0, 1, 2, 3, 4, 5])

list.consume(3)
list.subarray()
// -> Uint8Array([3, 4, 5])

// you can also iterate over the list
for (const buf of list) {
  // ..do something with `buf`
}

list.subarray(0, 1)
// -> Uint8Array([0])

Converting Uint8ArrayLists to Uint8Arrays

There are two ways to turn a Uint8ArrayList into a Uint8Array - .slice and .subarray and one way to turn a Uint8ArrayList into a Uint8ArrayList with different contents - .sublist.

slice

Slice follows the same semantics as Uint8Array.slice in that it creates a new Uint8Array and copies bytes into it using an optional offset & length.

const list = new Uint8ArrayList()
list.append(Uint8Array.from([0, 1, 2]))
list.append(Uint8Array.from([3, 4, 5]))

list.slice(0, 1)
// -> Uint8Array([0])

subarray

Subarray attempts to follow the same semantics as Uint8Array.subarray with one important different - this is a no-copy operation, unless the requested bytes span two internal buffers in which case it is a copy operation.

const list = new Uint8ArrayList()
list.append(Uint8Array.from([0, 1, 2]))
list.append(Uint8Array.from([3, 4, 5]))

list.slice(0, 1)
// -> Uint8Array([0]) - no-copy

list.slice(2, 5)
// -> Uint8Array([2, 3]) - copy

sublist

Sublist creates and returns a new Uint8ArrayList that shares the underlying buffers with the original so is always a no-copy operation.

const list = new Uint8ArrayList()
list.append(Uint8Array.from([0, 1, 2]))
list.append(Uint8Array.from([3, 4, 5]))

list.sublist(0, 1)
// -> Uint8ArrayList([0]) - no-copy

list.sublist(2, 5)
// -> Uint8ArrayList([2, 3]) - no-copy

Inspiration

Borrows liberally from bl but only uses native JS types.

API Docs

License

Licensed under either of

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

About

Append and consume bytes using only no-copy operations

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • TypeScript 93.0%
  • JavaScript 7.0%