ByteVector.md

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)

Table of contents

Accessors

• checksum
• isEmpty
• isReadOnly
• isView
• length

Methods

• [iterator]
• addByte
• addByteArray
• addByteVector
• clear
• compareTo
• containsAt
• endsWith
• endsWithPartialMatch
• equals
• find
• get
• indexOf
• makeReadOnly
• offsetFind
• rFind
• resize
• set
• splice
• split
• startsWith
• subarray
• toBase64String
• toByteVector
• toDouble
• toFloat
• toInt
• toLong
• toShort
• toString
• toStrings
• toUint
• toUlong
• toUshort
• compare
• concatenate
• empty
• equals
• fromBase64String
• fromByte
• fromByteArray
• fromFileAbstraction
• fromInt
• fromInternalStream
• fromLong
• fromPath
• fromShort
• fromSize
• fromStream
• fromString
• fromUint
• fromUlong
• fromUshort
• getTextDelimiter

Accessors

checksum

• get checksum(): number

Calculates the CRC32 of the current instance.

Returns

number

---

isEmpty

• get isEmpty(): boolean

Whether the current instance has 0 bytes stored.

Returns

boolean

---

isReadOnly

• get isReadOnly(): boolean

Whether the current instance is read-only. If true, any call that will modify the instance will throw.

Returns

boolean

---

isView

• get isView(): boolean

Whether the current instance is a 'view' of another byte vector.

Returns

boolean

---

length

• get length(): number

Number of bytes currently in this instance.

Returns

number

Methods

[iterator]

▸ [iterator](): Iterator<number, any, undefined>

Gets iterator for iterating over bytes in the current instance.

Returns

Iterator<number, any, undefined>

---

addByte

▸ addByte(byte): void

Adds a single byte to the end of the current instance

Parameters

Name	Type	Description
byte	number	Value to add to the end of the ByteVector. Must be positive 8-bit integer.

Returns

void

---

addByteArray

▸ addByteArray(data, length?): void

Adds an array of bytes to the end of the current instance

Parameters

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

Returns

void

---

addByteVector

▸ addByteVector(data): void

Adds a ByteVector to the end of this ByteVector

Parameters

Name	Type	Description
data	ByteVector	ByteVector to add to the end of this ByteVector

Returns

void

---

clear

▸ clear(): void

Removes all elements from this ByteVector

Remarks

This method replaces the internal byte array with a new one.

Returns

void

---

compareTo

▸ compareTo(other): number

Compares the current instance to another byte vector. Returns a numeric result.

Parameters

Name	Type	Description
other	ByteVector	Other byte vector to compare against the current instance.

Returns

number

---

containsAt

▸ containsAt(pattern, offset?): boolean

Determines if pattern exists at a certain offset in this byte vector.

Parameters

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

Returns

boolean

---

endsWith

▸ endsWith(pattern): boolean

Determines whether this byte vector ends with the provided pattern.

Parameters

Name	Type	Description
pattern	ByteVector	ByteVector to look for at the end of this byte vector

Returns

boolean

---

endsWithPartialMatch

▸ endsWithPartialMatch(pattern): number

Determines whether this byte vector ends with a part of the pattern. NOTE: if this instance ends with pattern perfectly, it must end with n-1 or fewer bytes.

Parameters

Name	Type	Description
pattern	ByteVector	ByteVector to look for at the end of this byte vector

Returns

number

---

equals

▸ equals(other): boolean

Determines if this instance has identical contents to the other instance.

Parameters

Name	Type	Description
other	ByteVector	Other instance to compare against the current instance.

Returns

boolean

---

find

▸ find(pattern, byteAlign?): number

Searches this instance for the pattern. Returns the index of the first instance of the pattern, or -1 if it was not found. Providing a byteAlign requires the pattern to appear at an index that is a multiple of the byteAlign parameter. Example: searching "abcd" for "ab" with byteAlign 1 will return 0. Searching "abcd" for "ab" with byteAlign 2 will return 1. Searching "00ab" for "ab" with byteAlign 2 will return 2. Searching "0abc" with byteAlign 2 will return -1.

Parameters

Name	Type	Default value	Description
pattern	ByteVector	undefined	Pattern of bytes to search this instance for
byteAlign	number	1	Optional, byte alignment the pattern much align to

Returns

number

---

get

▸ get(index): number

Gets the byte at the given index.

Parameters

Name	Type	Description
index	number	Element index to return

Returns

number

---

indexOf

▸ indexOf(item): number

Gets the index of the first occurrence of the specified value.

Parameters

Name	Type	Description
item	number	A byte to find within the current instance.

Returns

number

An integer containing the first index at which the value was found, or -1 if it was not found

---

makeReadOnly

▸ makeReadOnly(): ByteVector

Makes the current instance read-only, causing any call that would modify it or allow it to be modified to throw.

Returns

ByteVector

---

offsetFind

▸ offsetFind(pattern, offset, byteAlign?): number

Searches this instance for the pattern occurring after a given offset. Returns the index of the first instance of the pattern, relative to the start of the array, or -1 if it was not found. Providing a byteAlign requires the pattern to appear at an index that is a multiple of the byteAlign parameter. Example: searching "abcd" for "ab" with byteAlign 1 will return 0. Searching "abcd" for "ab" with byteAlign 2 will return 1. Searching "00ab" for "ab" with byteAlign 2 will return 2. Searching "0abc" with byteAlign 2 will return -1.

Parameters

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

Returns

number

---

rFind

▸ rFind(pattern, byteAlign?): number

Finds a byte vector by searching from the end of this instance and working towards the beginning of this instance. Returns the index of the first instance of the pattern, or -1 if it was not found. Providing a byteAlign requires the pattern to appear at an index that is a multiple of the byteAlign parameter. Example: searching "abcd" for "ab" with byteAlign 1 will return 0. Searching "abcd" for "ab" with byteAlign 2 will return 1. Searching "00ab" for "ab" with byteAlign 2 will return 2. Searching "0abc" with byteAlign 2 will return -1.

Parameters

Name	Type	Default value	Description
pattern	ByteVector	undefined	Pattern of bytes to search this instance for
byteAlign	number	1	Optional, byte alignment the pattern must align to

Returns

number

---

resize

▸ resize(size, padding?): void

Resizes this instance to the length specified in size. If the desired size is longer than the current length, it will be filled with the byte value in padding. If the desired size is shorter than the current length, bytes will be removed.

Parameters

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

Returns

void

---

set

▸ set(index, value): void

Sets the value at a specified index

Parameters

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

Returns

void

---

splice

▸ splice(start, deleteCount, items?): void

Changes the contents of the current instance by removing or replacing existing elements and/or adding new elements.

Parameters

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.

Returns

void

---

split

▸ split(separator, byteAlign?, max?): ByteVector[]

Splits this byte vector into a list of byte vectors using a separator

Parameters

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.

Returns

ByteVector[]

ByteVector[] The split contents of the current instance

---

startsWith

▸ startsWith(pattern): boolean

Checks whether a pattern appears at the beginning of the current instance.

Parameters

Name	Type	Description
pattern	ByteVector	ByteVector containing the pattern to check for in the current instance.

Returns

boolean

true if the pattern was found at the beginning of the current instance, false otherwise.

---

subarray

▸ subarray(startIndex, length?): ByteVector

Returns a window over the current instance.

Parameters

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

Returns

ByteVector

---

toBase64String

▸ toBase64String(): string

Returns the current instance as a base64 encoded string.

Returns

string

---

toByteVector

▸ toByteVector(): ByteVector

Returns a writable copy of the bytes represented by this instance.

Remarks

This is a copy of the data. Use sparingly.

Returns

ByteVector

---

toDouble

▸ toDouble(mostSignificantByteFirst?): number

Converts the first eight bytes of the current instance to a double-precision floating-point value.

Throws

Error If there are less than eight bytes in the current instance.

Parameters

Name	Type	Default value	Description
mostSignificantByteFirst	boolean	true	If true the most significant byte appears first (big endian format).

Returns

number

A double value containing the value read from the current instance.

---

toFloat

▸ toFloat(mostSignificantByteFirst?): number

Converts the first four bytes of the current instance to a single-precision floating-point value.

Throws

Error If there are less than four bytes in the current instance

Parameters

Name	Type	Default value	Description
mostSignificantByteFirst	boolean	true	If true the most significant byte appears first (big endian format).

Returns

number

A float value containing the value read from the current instance.

---

toInt

▸ toInt(mostSignificantByteFirst?): number

Converts the first four bytes of the current instance to a signed integer. If the current instance is less than four bytes, the most significant bytes will be filled with 0x00.

Parameters

Name	Type	Default value	Description
mostSignificantByteFirst	boolean	true	If true the most significant byte appears first (big endian format)

Returns

number

A signed integer value containing the value read from the current instance

---

toLong

▸ toLong(mostSignificantByteFirst?): bigint

Converts the first eight bytes of the current instance to a signed long. If the current instance is less than eight bytes, the most significant bytes will be filled with 0x00.

Parameters

Name	Type	Default value	Description
mostSignificantByteFirst	boolean	true	If true the most significant byte appears first (big endian format)

Returns

bigint

A signed long value containing the value read from the current instance, represented as a BigInt due to JavaScript's 52-bit integer limitation.

---

toShort

▸ toShort(mostSignificantByteFirst?): number

Converts the first two bytes of the current instance to a signed short. If the current instance is less than two bytes, the most significant bytes will be filled with 0x00.

Parameters

Name	Type	Default value	Description
mostSignificantByteFirst	boolean	true	If true the most significant byte appears first (big endian format)

Returns

number

A signed short value containing the value read from the current instance

---

toString

▸ toString(type): string

Converts a portion of the current instance to a string using a specified encoding

Parameters

Name	Type	Description
type	StringType	Value indicating the encoding to use when converting to a string.

Returns

string

String containing the converted bytes

---

toStrings

▸ toStrings(type, count?): string[]

Converts the current instance into an array of strings starting at the specified offset and using the specified encoding, assuming the values are null separated and limiting it to a specified number of items.

Parameters

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

Returns

string[]

Array of strings containing the converted text.

---

toUint

▸ toUint(mostSignificantByteFirst?): number

Converts the first four bytes of the current instance to an unsigned integer. If the current instance is less than four bytes, the most significant bytes will be filled with 0x00.

Parameters

Name	Type	Default value	Description
mostSignificantByteFirst	boolean	true	If true the most significant byte appears first (big endian format)

Returns

number

An unsigned integer value containing the value read from the current instance

---

toUlong

▸ toUlong(mostSignificantByteFirst?): bigint

Converts the first eight bytes of the current instance to an unsigned long. If the current instance is less than eight bytes, the most significant bytes will be filled with 0x00.

Parameters

Name	Type	Default value	Description
mostSignificantByteFirst	boolean	true	If true the most significant byte appears first (big endian format)

Returns

bigint

An unsigned short value containing the value read from the current instance, represented as a BigInt due to JavaScript's 32-bit integer limitation

---

toUshort

▸ toUshort(mostSignificantByteFirst?): number

Converts the first two bytes of the current instance to an unsigned short. If the current instance is less than two bytes, the most significant bytes will be filled with 0x00.

Parameters

Name	Type	Default value	Description
mostSignificantByteFirst	boolean	true	If true the most significant byte appears first (big endian format)

Returns

number

An unsigned short value containing the value read from the current instance

---

compare

▸ Static compare(a, b): number

Compares two byte vectors. Returns a numeric value

Parameters

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

Returns

number

0 if the two vectors are the same. Any other value indicates the two are different. If the two vectors differ by length, this will be the length of a minus the length of b. If the lengths are the same it will be the difference between the first element that differs.

---

concatenate

▸ Static concatenate(...vectors): ByteVector

Creates a ByteVector from a collection of bytes, byte arrays, and byte vectors. This method is better to use when a known quantity of byte vectors will be concatenated together, since doing multiple calls to addByteVector results in the entire byte vector being copied for each call.

Parameters

Name	Type	Description
...vectors	(number | ByteVector | Uint8Array)[]	ByteVectors, byte arrays, or straight bytes to concatenate together into a new ByteVector

Returns

ByteVector

Single byte vector with the contents of the byte vectors in vectors concatenated together

---

empty

▸ Static empty(): ByteVector

Creates an empty ByteVector

Returns

ByteVector

---

equals

▸ Static equals(first, second): boolean

Returns true if the contents of the two ByteVectors are identical, returns false otherwise

Parameters

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

Returns

boolean

---

fromBase64String

▸ Static fromBase64String(str): ByteVector

Creates a ByteVector from a base64 string.

Parameters

Name	Type	Description
str	string	Base64 string to convert into a byte vector

Returns

ByteVector

---

fromByte

▸ Static fromByte(value): ByteVector

Creates a 1 byte ByteVector with an unsigned 8-bit integer as the data

Parameters

Name	Type	Description
value	number	Unsigned 8-bit integer to use as the data.

Returns

ByteVector

---

fromByteArray

▸ Static fromByteArray(bytes, length?): ByteVector

Creates a ByteVector from a Uint8Array or Buffer

Parameters

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.

Returns

ByteVector

---

fromFileAbstraction

▸ Static fromFileAbstraction(abstraction): ByteVector

Creates a new instance by reading in the contents of a specified file abstraction.

Parameters

Name	Type	Description
abstraction	IFileAbstraction	File abstraction to read

Returns

ByteVector

---

fromInt

▸ Static fromInt(value, isBigEndian?): ByteVector

Creates a 4 byte ByteVector with a signed 32-bit integer as the data

Parameters

Name	Type	Default value	Description
value	number	undefined	Signed 32-bit integer to use as the data.
isBigEndian	boolean	true	If true, value will be stored in big endian format. If false, value will be stored in little endian format

Returns

ByteVector

---

fromInternalStream

▸ Static fromInternalStream(stream): ByteVector

Creates a ByteVector using the contents of an TagLibSharp-node stream as the contents. This method reads from the current offset of the stream, not the beginning of the stream

Parameters

Name	Type	Description
stream	IStream	TagLibSharp-node internal stream object

Returns

ByteVector

---

fromLong

▸ Static fromLong(value, isBigEndian?): ByteVector

Creates an 8 byte ByteVector with a signed 64-bit integer as the data

Parameters

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

Returns

ByteVector

---

fromPath

▸ Static fromPath(path): ByteVector

Creates a ByteVector using the contents of a file as the data

Parameters

Name	Type	Description
path	string	Path to the file to store in the ByteVector

Returns

ByteVector

---

fromShort

▸ Static fromShort(value, isBigEndian?): ByteVector

Creates a 2 byte ByteVector with a signed 16-bit integer as the data

Parameters

Name	Type	Default value	Description
value	number	undefined	Signed 16-bit integer to use as the data.
isBigEndian	boolean	true	If true, value will be stored in big endian format. If false, value will be stored in little endian format

Returns

ByteVector

---

fromSize

▸ Static fromSize(size, fill?): ByteVector

Creates a ByteVector of a given length with a given value for all the elements

Parameters

Name	Type	Default value	Description
size	number	undefined	Length of the ByteVector. Must be a positive safe integer
fill	number	0x0	Byte value to initialize all elements to. Must be a positive 8-bit integer

Returns

ByteVector

---

fromStream

▸ Static fromStream(readStream): Promise<ByteVector>

Creates ByteVector with the contents of a stream as the data. The stream will be read to the end before the ByteVector is returned.

Parameters

Name	Type	Description
readStream	ReadableStream	Readable stream that will be read in entirety.

Returns

Promise<ByteVector>

---

fromString

▸ Static fromString(text, type, length?): ByteVector

Creates ByteVector with the byte representation of a string as the data.

Parameters

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.

Returns

ByteVector

---

fromUint

▸ Static fromUint(value, isBigEndian?): ByteVector

Creates a 4 byte ByteVector with a positive 32-bit integer as the data

Parameters

Name	Type	Default value	Description
value	number	undefined	Positive 32-bit integer to use as the data
isBigEndian	boolean	true	If true, value will be stored in big endian format. If false, value will be stored in little endian format

Returns

ByteVector

---

fromUlong

▸ Static fromUlong(value, isBigEndian?): ByteVector

Creates an 8 byte ByteVector with a positive 64-bit integer as the data

Parameters

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

Returns

ByteVector

---

fromUshort

▸ Static fromUshort(value, isBigEndian?): ByteVector

Creates a 2 byte ByteVector with a positive 16-bit integer as the data

Parameters

Name	Type	Default value	Description
value	number	undefined	Positive 16-bit integer to use as the data.
isBigEndian	boolean	true	If true, value will be stored in big endian format. If false, value will be stored in little endian format

Returns

ByteVector

---

getTextDelimiter

▸ Static getTextDelimiter(type): ByteVector

Gets the appropriate length null-byte text delimiter for the specified type.

Parameters

Name	Type	Description
type	StringType	String type to get delimiter for

Returns

ByteVector