@chickenjdk/byteutils
Version:
Some utilitys for working with binary data
276 lines (275 loc) • 17 kB
TypeScript
import { uint8ArrayLike, cloneFunc, MaybePromise } from "./types";
export declare abstract class writableBufferBase<IsAsync extends boolean = true | false> {
#private;
/**
* Write a array of bytes (numbers 0-255) to the buffer (first byte first written to the end[BE])
* @param value The data to write
*/
abstract writeArray(value: number[]): MaybePromise<void, IsAsync>;
/**
* Write a array of bytes (numbers 0-255) to the buffer backwards (last byte first written to the end[LE])
*/
abstract writeArrayBackwards(value: number[]): MaybePromise<void, IsAsync>;
/**
* Write a Uint8Array to the buffer (first byte first written to the end[BE])
*/
abstract writeUint8Array(value: Uint8Array): MaybePromise<void, IsAsync>;
/**
* Write a Uint8Array to the buffer backward (last byte first written to the end[LE])
*/
abstract writeUint8ArrayBackwards(value: Uint8Array): MaybePromise<void, IsAsync>;
/**
* Push a byte (numbers 0-255) to the buffer's end
* @param value the byte to push
*/
abstract push(value: number): MaybePromise<void, IsAsync>;
/**
* Write a writeable buffer storing data to the buffer
*/
writeWriteableBuffer(value: writableBufferStorage): MaybePromise<void, IsAsync>;
/**
* Write data to the buffer (writes data that was origionaly in BE format to the endianness of the buffer)
* @param value The data to write
*/
writeArrayEndian: cloneFunc<typeof this.writeArray> | cloneFunc<typeof this.writeArrayBackwards>;
/**
* Write data to the buffer backwards (writes data that was origionaly in LE format to the endianness of the buffer, I know that "backwards" is a little opinionated but the class was origionaly BE-only and I did not want to change too mutch)
* @param value The data to write
*/
writeArrayBackwardsEndian: cloneFunc<typeof this.writeArray> | cloneFunc<typeof this.writeArrayBackwards>;
/**
* Write a Uint8Array to the buffer (for the endian)
* Alias for .write because .write can handle Uint8Arrays. This exsists to have the similar naming of methods as readableBuffer's methods
*/
writeUint8ArrayEndian: cloneFunc<typeof this.writeUint8Array> | cloneFunc<typeof this.writeUint8ArrayBackwards>;
/**
* Write a Uint8Array to the buffer backwars (for the endian)
* Alias for .write because .write can handle Uint8Arrays. This exsists to have the similar naming of methods as readableBuffer's methods
*/
writeUint8ArrayBackwardsEndian: cloneFunc<typeof this.writeUint8Array> | cloneFunc<typeof this.writeUint8ArrayBackwards>;
/**
* If the buffer is little endian
*/
get isLe(): boolean;
/**
* If the buffer is little endian
*/
set isLe(isLe: boolean);
/**
* Calculate the minimum length of an unsigned integer in bytes.
* WARNING: No unssigned ints above 4294967295 (2^32 - 1) are supported, so this will not work for those.
* This is due to the limitations of bitwise operators. You can write numbers higher than that via writeUnsignedIntBigint, but this function will not work for them.
* @remarks
* This function calculates the minimum number of bytes needed to represent an unsigned integer in binary format.
* It uses the `Math.clz32` function to count the number of leading zeros in the binary representation of the value.
* The result is rounded up to the nearest byte.
* @param value The value to check
* @returns The calculated minimum length in bytes
*/
minLengthOfUnsignedInt(value: number): number;
/**
* Write an unsigned integer to the buffer
* @param value The unsigned int to write
* @param bytes How many bytes the unsined int is (If not provided, it will write the minimum length)
* @returns How many bytes were written (Same as bytes parameter if provided)
*/
writeUnsignedInt(value: number, bytes: number): MaybePromise<void, IsAsync> extends infer T ? T extends MaybePromise<void, IsAsync> ? T extends Promise<unknown> ? Promise<number> : number : never : never;
/**
* Write an unsigned integer to the buffer
* @param value The unsigned int to write (a bigint)
* @param bytes How many bytes the unsined int is (If not provided, it will write the minimum length)
* @returns How many bytes were written (Same as bytes parameter)
*/
writeUnsignedIntBigint(value: bigint, bytes: number): MaybePromise<void, IsAsync> extends infer T ? T extends MaybePromise<void, IsAsync> ? T extends Promise<unknown> ? Promise<number> : number : never : never;
/**
* Calculate the minimum length of a two's complement in bytes.
* WARNING: No two's complements above 4278190079 or below -4278190079 (2^31 - 1) are supported, so this will not work for those.
* This is due to the limitations of bitwise operators. You can write numbers higher than that via writeTwosComplementBigint, but this function will not work for them.
* @remarks
* This function calculates the minimum number of bytes needed to represent an two's complement in binary format.
* It uses the `Math.clz32` function to count the number of leading zeros in the binary representation of the value.
* It subtracts this from 33 (equivilent to the number of bits in the two's complement +1 to account for the sign) to get the number of bits needed.
* The result is rounded up to the nearest byte.
* @param value The value to check
* @returns The calculated minimum length in bytes
*/
minLengthOfTwosComplement(value: number): number;
/**
* Write a twos complement to the buffer
* @param value The number to encode
* @param bytes How long the twos complement to be written is in bytes
* @returns How many bytes were written (Same as bytes parameter if provided)
*/
writeTwosComplement(value: number, bytes: number): (MaybePromise<void, IsAsync> extends infer T ? T extends MaybePromise<void, IsAsync> ? T extends Promise<unknown> ? Promise<number> : number : never : never) extends infer T_1 ? T_1 extends (MaybePromise<void, IsAsync> extends infer T_2 ? T_2 extends MaybePromise<void, IsAsync> ? T_2 extends Promise<unknown> ? Promise<number> : number : never : never) ? T_1 extends Promise<unknown> ? Promise<number> : number : never : never;
/**
* Write a twos complement to the buffer (From a bigint)
* @param value The number to encode
* @param bytes How long the twos complement to be written is in bytes
* @returns How many bytes were written (Same as bytes parameter)
*/
writeTwosComplementBigint(value: bigint, bytes: number): (MaybePromise<void, IsAsync> extends infer T ? T extends MaybePromise<void, IsAsync> ? T extends Promise<unknown> ? Promise<number> : number : never : never) extends infer T_1 ? T_1 extends (MaybePromise<void, IsAsync> extends infer T_2 ? T_2 extends MaybePromise<void, IsAsync> ? T_2 extends Promise<unknown> ? Promise<number> : number : never : never) ? T_1 extends Promise<unknown> ? Promise<number> : number : never : never;
/**
* Write a twos complement to the buffer (one byte)
* @param value The number to encode
* @returns How many bytes were written (1)
*/
writeTwosComplementByte(value: number): MaybePromise<void, IsAsync>;
/**
* Write twos complements to the buffer (one byte each)
* @param values The numbers to encode
* @returns How many bytes were written (Same as values.length)
*/
writeTwosComplementByteArray(values: number[]): MaybePromise<void, IsAsync> extends Promise<unknown> ? Promise<number> : number;
/**
* Write a float to the buffer
* @param value The float to write
* @returns How many bytes were written (4)
*/
writeFloat(value: number): MaybePromise<void, IsAsync>;
/**
* Write a double float to the buffer
* @param value The double float to write
* @returns How many bytes were written (8)
*/
writeDouble(value: number): MaybePromise<void, IsAsync>;
/**
* Write a utf8 string to the buffer
* @param value
* @param mutf8 If true, write in java's mutf8 format instead. This was build for parsing java's .class files, so no complaining about it being a java-specific format.
* @returns How many bytes were written
*/
writeString(value: string, mutf8?: boolean): MaybePromise<void, IsAsync> extends infer T ? T extends MaybePromise<void, IsAsync> ? T extends Promise<unknown> ? Promise<number> : number : never : never;
/**
* Calculate the minimum length of a signed ones's complement in bytes.
* WARNING: No signed two's complements above 4278190079 or below -4278190079 (2^31 - 1) are supported, so this will not work for those.
* This is due to the limitations of bitwise operators. You can write numbers higher than that via writeSignedOnesComplementBigint, but this function will not work for them.
* @remarks
* This function calculates the minimum number of bytes needed to represent an signed one's in binary format.
* It uses the `Math.clz32` function to count the number of leading zeros in the binary representation of the value.
* It subtracts this from 33 (equivilent to the number of bits in the signed one's complement +1 to account for the sign) to get the number of bits needed.
* The result is rounded up to the nearest byte.
* @param value The value to check
* @returns The calculated minimum length in bytes
*/
minLengthOfSignedOnesComplement(value: number): number;
/**
* Encode and write a signed one's complement
* @param value The number to encode
* @param bytes How many bytes to make the encoded value
* @returns How many bytes were written (Same as bytes parameter if provided)
*/
writeSignedOnesComplement(value: number, bytes: number): (MaybePromise<void, IsAsync> extends infer T ? T extends MaybePromise<void, IsAsync> ? T extends Promise<unknown> ? Promise<number> : number : never : never) extends infer T_1 ? T_1 extends (MaybePromise<void, IsAsync> extends infer T_2 ? T_2 extends MaybePromise<void, IsAsync> ? T_2 extends Promise<unknown> ? Promise<number> : number : never : never) ? T_1 extends Promise<unknown> ? Promise<number> : number : never : never;
/**
* Encode and write a signed ones complement (from a bigint)
* @param value The number to encode
* @param bytes How many bytes to make the encoded value
* @returns How many bytes were written (Same as bytes parameter)
*/
writeSignedOnesComplementBigint(value: bigint, bytes: number): (MaybePromise<void, IsAsync> extends infer T ? T extends MaybePromise<void, IsAsync> ? T extends Promise<unknown> ? Promise<number> : number : never : never) extends infer T_1 ? T_1 extends (MaybePromise<void, IsAsync> extends infer T_2 ? T_2 extends MaybePromise<void, IsAsync> ? T_2 extends Promise<unknown> ? Promise<number> : number : never : never) ? T_1 extends Promise<unknown> ? Promise<number> : number : never : never;
/**
* Encode and write a signed ones complement (one byte)
* @param value The number to encode
* @returns How many bytes were written (1)
*/
writeSignedOnesComplementByte(value: number): MaybePromise<void, IsAsync> extends infer T ? T extends MaybePromise<void, IsAsync> ? T extends Promise<unknown> ? Promise<1> : 1 : never : never;
/**
* Encode and write a signed ones complements
* @param values The numbers to encode
* @returns How many bytes were written (Same as values.length)
*/
writeSignedOnesComplementByteArray(values: number[]): (MaybePromise<void, IsAsync> extends infer T ? T extends MaybePromise<void, IsAsync> ? T extends Promise<unknown> ? Promise<1> : 1 : never : never) extends Promise<unknown> ? Promise<number> : number;
/**
* Calculate the minimum length of a signed integer in bytes.
* WARNING: No signed integers above 4278190079 or below -4278190079 (2^31 - 1) are supported, so this will not work for those.
* This is due to the limitations of bitwise operators. You can write numbers higher than that via writeSignedIntegerBigint, but this function will not work for them.
* @remarks
* This function calculates the minimum number of bytes needed to represent a signed integer in binary format.
* It uses the `Math.clz32` function to count the number of leading zeros in the binary representation of the value.
* It subtracts this from 33 (equivilent to the number of bits in the signed integer +1 to account for the sign) to get the number of bits needed.
* The result is rounded up to the nearest byte.
* @param value The value to check
* @returns The calculated minimum length in bytes
*/
minLengthOfSignedInteger(value: number): number;
/**
* Encode and write a signed integer
* @param value The number to encode
* @param bytes How many bytes to make the encoded value
* @returns How many bytes were written (Same as bytes parameter if provided)
*/
writeSignedInteger(value: number, bytes: number): (MaybePromise<void, IsAsync> extends infer T ? T extends MaybePromise<void, IsAsync> ? T extends Promise<unknown> ? Promise<number> : number : never : never) extends infer T_1 ? T_1 extends (MaybePromise<void, IsAsync> extends infer T_2 ? T_2 extends MaybePromise<void, IsAsync> ? T_2 extends Promise<unknown> ? Promise<number> : number : never : never) ? T_1 extends Promise<unknown> ? Promise<number> : number : never : never;
/**
* Encode and write a signed integer (from a bigint)
* @param value The number to encode
* @param bytes How many bytes to make the encoded value
* @returns How many bytes were written (Same as bytes parameter)
*/
writeSignedIntegerBigint(value: bigint, bytes: number): (MaybePromise<void, IsAsync> extends infer T ? T extends MaybePromise<void, IsAsync> ? T extends Promise<unknown> ? Promise<number> : number : never : never) extends infer T_1 ? T_1 extends (MaybePromise<void, IsAsync> extends infer T_2 ? T_2 extends MaybePromise<void, IsAsync> ? T_2 extends Promise<unknown> ? Promise<number> : number : never : never) ? T_1 extends Promise<unknown> ? Promise<number> : number : never : never;
/**
* Encode and write a signed integer (one byte)
* @param value The number to encode
* @returns How many bytes were written (1)
*/
writeSignedIntegerByte(value: number): MaybePromise<void, IsAsync> extends infer T ? T extends MaybePromise<void, IsAsync> ? T extends Promise<unknown> ? Promise<1> : 1 : never : never;
/**
* Encode and write signed integers (one byte)
* @param values The numbers to encode
* @returns How many bytes were written (Same as values.length)
*/
writeSignedIntegerByteArray(values: number[]): (MaybePromise<void, IsAsync> extends infer T ? T extends MaybePromise<void, IsAsync> ? T extends Promise<unknown> ? Promise<1> : 1 : never : never) extends Promise<unknown> ? Promise<number> : number;
}
export declare abstract class writableBufferStorage extends writableBufferBase {
/**
* The data in the storage
*/
abstract get buffer(): Uint8Array;
/**
* Change the contents of the buffer
*/
abstract set buffer(newValue: uint8ArrayLike | writableBufferStorage);
/**
* The length of the storage
*/
abstract get length(): number;
}
export declare class writableBuffer extends writableBufferBase<false> implements writableBufferStorage {
#private;
get buffer(): Uint8Array;
set buffer(value: uint8ArrayLike | writableBufferStorage);
get length(): number;
constructor(chunkSize?: number);
push(value: number): void;
writeUint8Array(value: Uint8Array): void;
writeUint8ArrayBackwards(value: Uint8Array): void;
writeArray(value: number[]): void;
writeArrayBackwards(value: number[]): void;
}
export declare const writableBufferLE: {
new (...args: any[]): {
[x: string]: any;
};
} & typeof writableBuffer;
export declare class writableBufferFixedSize extends writableBufferBase<false> implements writableBufferStorage {
#private;
get buffer(): Uint8Array;
set buffer(value: uint8ArrayLike | writableBufferStorage);
get length(): number;
get maxLength(): number;
set maxLength(value: number);
constructor(maxLength?: number);
/**
* Reset the buffer
*/
reset(): void;
push(value: number): void;
writeUint8Array(value: Uint8Array): void;
writeUint8ArrayBackwards(value: Uint8Array): void;
writeArray(value: number[]): void;
writeArrayBackwards(value: number[]): void;
writeWriteableBuffer(value: writableBufferStorage): void;
}
export declare const writableBufferFixedSizeLE: {
new (...args: any[]): {
[x: string]: any;
};
} & typeof writableBufferFixedSize;