Class: ByteVector

November 25, 2024 · View on GitHub

node-taglib-sharp / Exports / ByteVector

Class: ByteVector

Wrapper around a Uint8Array that provides functionality for reading and writing byte arrays.

Remarks

Implementation of this class uses a single Uint8Array to store bytes. Due to Uint8Arrays being fixed length, any operation that inserts or removes values into the instance will result in a copy of the internal array being made. If multiple additions will be made, rather than using multiple inserts/adds, the concatenate method is provided to group additions/inserts and therefore improve performance.

The original .NET implementation had a ubiquitous `mid` method that would return a subset
of the bytes in the current instance. In versions <5 of the node port, `mid` would make a
copy of the subset of the bytes. Since this was frequently done right before reading a
number or string, this copy was extremely wasteful. In version 5, the `mid` method was
replaced with `subarray` which behaves identically to `Uint8Array.subarray` and returns
an instance that is a 'view' of an existing instance - no copying involved. However, all
write operations make copies, instances that are backed by 'views' may waste memory by
referencing a `Uint8Array` that is much larger than the view.

With this in mind, best practices for using `ByteVectors`:
* Calling [subarray](ByteVector.md#subarray) is cheap, use it when possible
* If storing a subset of a `ByteVector`, store a copy with [toByteVector](ByteVector.md#tobytevector)
* If building a `ByteVector`, use [concatenate](ByteVector.md#concatenate) when possible
* If the instance should be immutable, use [makeReadOnly](ByteVector.md#makereadonly)

Accessors

Methods

Accessors

checksum

• get checksum(): number

Calculates the CRC32 of the current instance.

Name	Type	Description
`data`	`Uint8Array`	Array of bytes to add to the end of the ByteVector
`length?`	`number`	Number of elements from `data` to copy into the current instance

Name	Type	Default value	Description
`pattern`	`ByteVector`	`undefined`	ByteVector to search for at in this byte vector
`offset`	`number`	`0`	Position in this byte vector to search for the pattern. If omitted, defaults to `0`

Name	Type	Description
`pattern`	`ByteVector`	Pattern of bytes to search this instance for
`offset`	`number`	Index into the instance to begin searching for `pattern`
`byteAlign?`	`number`	Optional, byte alignment the pattern much align to

Name	Type	Default value	Description
`size`	`number`	`undefined`	Length of the byte vector after resizing. Must be unsigned 32-bit integer
`padding`	`number`	`0x0`	Byte to fill any excess space created after resizing

Name	Type	Description
`index`	`number`	Index to set the value of
`value`	`number`	Value to set at the index. Must be a valid integer betweenInclusive 0x0 and 0xff

Name	Type	Description
`start`	`number`	Index at which to start changing the array. Must be less than the length of the instance
`deleteCount`	`number`	Number of elements in the array to remove from start. If greater than the remaining length of the element, it will be capped at the remaining length
`items?`	`ByteVector` \| `Uint8Array` \| `number`[]	Elements to add to the array beginning from start. If omitted, the method will only remove elements from the current instance.

Name	Type	Default value	Description
`separator`	`ByteVector`	`undefined`	Object to use to split this byte vector
`byteAlign`	`number`	`1`	Byte align to use when splitting. in order to split when a pattern is encountered, the index at which it is found must be divisible by this value.
`max`	`number`	`0`	Maximum number of objects to return or 0 to not limit the number. If that number is reached, the last value will contain the remainder of the file even if it contains more instances of `separator`.

Name	Type	Description
`startIndex`	`number`	Offset into this instance where the comprehension begins
`length`	`number`	Number of elements from the instance to include. If omitted, defaults to the remainder of the instance

Name	Type	Default value	Description
`type`	`StringType`	`undefined`	A StringType value indicating the encoding to use when converting
`count`	`number`	`Number.MAX_SAFE_INTEGER`	Value specifying a limit to the number of strings to create. Once the limit has been reached, the last string will be filled by the remainder of the data

Name	Type	Description
`a`	`ByteVector`	Byte vector to compare against `b`
`b`	`ByteVector`	Byte vector to compare against `a`

Name	Type	Default value	Description
`value`	`number` \| `bigint`	`undefined`	Signed 64-bit integer to use as the data. If using a `bigint`, it must fit within 8 bytes. If using a `number`, it must be a safe integer.
`isBigEndian`	`boolean`	`true`	If `true`, `value` will be stored in big endian format. If `false`, `value` will be stored in little endian format

Name	Type	Description
`first`	`ByteVector`	ByteVector to compare with `second`
`second`	`ByteVector`	ByteVector to compare with `first`

Name	Type	Default value	Description
`bytes`	`Uint8Array` \| `Buffer` \| `number`[]	`undefined`	Uint8Array of the bytes to put in the ByteVector
`length`	`number`	`bytes.length`	Optionally, number of bytes to read. If this is not provided, it will default to the full length of `bytes`. If it is less than the length of `bytes`, `bytes` will be copied into the ByteVector.

Name	Type	Default value	Description
`text`	`string`	`undefined`	String to store in the ByteVector
`type`	`StringType`	`undefined`	StringType to use to encode the string. If UTF16 is used, the string will be encoded as UTF16-LE.
`length`	`number`	`Number.MAX_SAFE_INTEGER`	Number of characters from the string to store in the ByteVector. Must be a positive 32-bit integer.