Deno/std
1
0
Fork 0
mirror of https://github.com/denoland/std.git synced 2024-11-22 04:59:05 +00:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

BREAKING(encoding): remove deprecated binary APIs (#3763)

Browse Source
This commit is contained in:
Asher Gomez 2023-11-10 14:28:20 +11:00 committed by GitHub
parent 7e6a91f012
commit 19957e5f49
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 0 additions and 576 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

340
encoding/binary.ts
View File

@ -1,340 +0,0 @@
// Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
/**
* @deprecated (will be removed after 0.205.0) Use ReadableStream and WritableStream instead of Reader and Writer.
*
* Functions for encoding binary data in array buffers.
*
* @module
*/
import type { Reader, Writer } from "../types.d.ts";
type RawBaseType = "int8" | "int16" | "int32" | "uint8" | "uint16" | "uint32";
type RawNumberType = RawBaseType | "float32" | "float64";
type RawBigType = RawBaseType | "int64" | "uint64";
/** @deprecated (will be removed after 0.205.0) */
export type DataType = RawNumberType | RawBigType;
/**
* @deprecated (will be removed after 0.205.0)
* How encoded binary data is ordered.
*/
export type Endianness = "little" | "big";
/**
* @deprecated (will be removed after 0.205.0)
* Options for working with the `number` type.
*/
export interface VarnumOptions {
/** The binary format used. */
dataType?: RawNumberType;
/** The binary encoding order used. */
endian?: Endianness;
}
/**
* @deprecated (will be removed after 0.205.0)
* Options for working with the `bigint` type.
*/
export interface VarbigOptions {
/** The binary format used. */
dataType?: RawBigType;
/** The binary encoding order used. */
endian?: Endianness;
}
const rawTypeSizes: Record<DataType, number> = {
int8: 1,
uint8: 1,
int16: 2,
uint16: 2,
int32: 4,
uint32: 4,
int64: 8,
uint64: 8,
float32: 4,
float64: 8,
} as const;
/**
* @deprecated (will be removed after 0.205.0)
* Number of bytes required to store `dataType`.
*/
export function sizeof(dataType: DataType): number {
return rawTypeSizes[dataType];
}
/**
* @deprecated (will be removed after 0.205.0) Use ReadableStreamBYOBReader to read exact number of bytes.
*
* Reads the exact number of bytes from `r` required to fill `b`.
*
* Throws `Deno.errors.UnexpectedEof` if `n` bytes cannot be read. */
export async function readExact(
r: Reader,
b: Uint8Array,
) {
let totalRead = 0;
do {
const tmp = new Uint8Array(b.length - totalRead);
const nRead = await r.read(tmp);
if (nRead === null) throw new Deno.errors.UnexpectedEof();
b.set(tmp, totalRead);
totalRead += nRead;
} while (totalRead < b.length);
}
/**
* @deprecated (will be removed after 0.205.0) Use ReadableStreamBYOBReader to read exact number of bytes.
*
* Reads exactly `n` bytes from `r`.
*
* Resolves it in a `Uint8Array`, or throws `Deno.errors.UnexpectedEof` if `n` bytes cannot be read. */
export async function getNBytes(
r: Reader,
n: number,
): Promise<Uint8Array> {
const scratch = new Uint8Array(n);
await readExact(r, scratch);
return scratch;
}
/**
* @deprecated (will be removed after 0.205.0) Use DataView instead.
*
* Decodes a number from `b`. If `o.bytes` is shorter than `sizeof(o.dataType)`, returns `null`.
*
* `o.dataType` defaults to `"int32"`. */
export function varnum(b: Uint8Array, o: VarnumOptions = {}): number | null {
o.dataType = o.dataType ?? "int32";
const littleEndian = (o.endian ?? "big") === "little" ? true : false;
if (b.length < sizeof(o.dataType)) return null;
const view = new DataView(b.buffer);
switch (o.dataType) {
case "int8":
return view.getInt8(b.byteOffset);
case "uint8":
return view.getUint8(b.byteOffset);
case "int16":
return view.getInt16(b.byteOffset, littleEndian);
case "uint16":
return view.getUint16(b.byteOffset, littleEndian);
case "int32":
return view.getInt32(b.byteOffset, littleEndian);
case "uint32":
return view.getUint32(b.byteOffset, littleEndian);
case "float32":
return view.getFloat32(b.byteOffset, littleEndian);
case "float64":
return view.getFloat64(b.byteOffset, littleEndian);
}
}
/**
* @deprecated (will be removed after 0.205.0) use DataView instead.
*
* Decodes a bigint from `b`. If `o.bytes` is shorter than `sizeof(o.dataType)`, returns `null`.
*
* `o.dataType` defaults to `"int64"`. */
export function varbig(b: Uint8Array, o: VarbigOptions = {}): bigint | null {
o.dataType = o.dataType ?? "int64";
const littleEndian = (o.endian ?? "big") === "little" ? true : false;
if (b.length < sizeof(o.dataType)) return null;
const view = new DataView(b.buffer);
switch (o.dataType) {
case "int8":
return BigInt(view.getInt8(b.byteOffset));
case "uint8":
return BigInt(view.getUint8(b.byteOffset));
case "int16":
return BigInt(view.getInt16(b.byteOffset, littleEndian));
case "uint16":
return BigInt(view.getUint16(b.byteOffset, littleEndian));
case "int32":
return BigInt(view.getInt32(b.byteOffset, littleEndian));
case "uint32":
return BigInt(view.getUint32(b.byteOffset, littleEndian));
case "int64":
return view.getBigInt64(b.byteOffset, littleEndian);
case "uint64":
return view.getBigUint64(b.byteOffset, littleEndian);
}
}
/**
* @deprecated (will be removed after 0.205.0) Use DataView instead.
*
* Encodes number `x` into `b`. Returns the number of bytes used, or `0` if `b` is shorter than `sizeof(o.dataType)`.
*
* `o.dataType` defaults to `"int32"`. */
export function putVarnum(
b: Uint8Array,
x: number,
o: VarnumOptions = {},
): number {
o.dataType = o.dataType ?? "int32";
const littleEndian = (o.endian ?? "big") === "little" ? true : false;
if (b.length < sizeof(o.dataType)) return 0;
const view = new DataView(b.buffer);
switch (o.dataType) {
case "int8":
view.setInt8(b.byteOffset, x);
break;
case "uint8":
view.setUint8(b.byteOffset, x);
break;
case "int16":
view.setInt16(b.byteOffset, x, littleEndian);
break;
case "uint16":
view.setUint16(b.byteOffset, x, littleEndian);
break;
case "int32":
view.setInt32(b.byteOffset, x, littleEndian);
break;
case "uint32":
view.setUint32(b.byteOffset, x, littleEndian);
break;
case "float32":
view.setFloat32(b.byteOffset, x, littleEndian);
break;
case "float64":
view.setFloat64(b.byteOffset, x, littleEndian);
break;
}
return sizeof(o.dataType);
}
/**
* @deprecated (will be removed after 0.205.0) Use DataView instead.
*
* Encodes bigint `x` into `b`. Returns the number of bytes used, or `0` if `b` is shorter than `sizeof(o.dataType)`.
*
* `o.dataType` defaults to `"int64"`. */
export function putVarbig(
b: Uint8Array,
x: bigint,
o: VarbigOptions = {},
): number {
o.dataType = o.dataType ?? "int64";
const littleEndian = (o.endian ?? "big") === "little" ? true : false;
if (b.length < sizeof(o.dataType)) return 0;
const view = new DataView(b.buffer);
switch (o.dataType) {
case "int8":
view.setInt8(b.byteOffset, Number(x));
break;
case "uint8":
view.setUint8(b.byteOffset, Number(x));
break;
case "int16":
view.setInt16(b.byteOffset, Number(x), littleEndian);
break;
case "uint16":
view.setUint16(b.byteOffset, Number(x), littleEndian);
break;
case "int32":
view.setInt32(b.byteOffset, Number(x), littleEndian);
break;
case "uint32":
view.setUint32(b.byteOffset, Number(x), littleEndian);
break;
case "int64":
view.setBigInt64(b.byteOffset, x, littleEndian);
break;
case "uint64":
view.setBigUint64(b.byteOffset, x, littleEndian);
break;
}
return sizeof(o.dataType);
}
/**
* @deprecated (will be removed after 0.205.0) Use ReadableStreamBYOBReader and DataView instead.
*
* Decodes a number from `r`, consuming `sizeof(o.dataType)` bytes. If less than `sizeof(o.dataType)` bytes were read, throws `Deno.errors.unexpectedEof`.
*
* `o.dataType` defaults to `"int32"`. */
export async function readVarnum(
r: Reader,
o: VarnumOptions = {},
): Promise<number> {
o.dataType = o.dataType ?? "int32";
const scratch = await getNBytes(r, sizeof(o.dataType));
return varnum(scratch, o) as number;
}
/**
* @deprecated (will be removed after 0.205.0) Use ReadableStreamBYOBReader and DataView instead.
*
* Decodes a bigint from `r`, consuming `sizeof(o.dataType)` bytes. If less than `sizeof(o.dataType)` bytes were read, throws `Deno.errors.unexpectedEof`.
*
* `o.dataType` defaults to `"int64"`. */
export async function readVarbig(
r: Reader,
o: VarbigOptions = {},
): Promise<bigint> {
o.dataType = o.dataType ?? "int64";
const scratch = await getNBytes(r, sizeof(o.dataType));
return varbig(scratch, o) as bigint;
}
/**
* @deprecated (will be removed after 0.205.0) Use WritableStream and DataView instead.
*
* Encodes and writes `x` to `w`. Resolves to the number of bytes written.
*
* `o.dataType` defaults to `"int32"`. */
export function writeVarnum(
w: Writer,
x: number,
o: VarnumOptions = {},
): Promise<number> {
o.dataType = o.dataType ?? "int32";
const scratch = new Uint8Array(sizeof(o.dataType));
putVarnum(scratch, x, o);
return w.write(scratch);
}
/**
* @deprecated (will be removed after 0.205.0) Use WritableStream and DataView instead.
*
* Encodes and writes `x` to `w`. Resolves to the number of bytes written.
*
* `o.dataType` defaults to `"int64"`. */
export function writeVarbig(
w: Writer,
x: bigint,
o: VarbigOptions = {},
): Promise<number> {
o.dataType = o.dataType ?? "int64";
const scratch = new Uint8Array(sizeof(o.dataType));
putVarbig(scratch, x, o);
return w.write(scratch);
}
/**
* @deprecated (will be removed after 0.205.0) Use DataView instead.
*
* Encodes `x` into a new `Uint8Array`.
*
* `o.dataType` defaults to `"int32"` */
export function varnumBytes(x: number, o: VarnumOptions = {}): Uint8Array {
o.dataType = o.dataType ?? "int32";
const b = new Uint8Array(sizeof(o.dataType));
putVarnum(b, x, o);
return b;
}
/**
* @deprecated (will be removed after 0.205.0) Use DataView instead.
*
* Encodes `x` into a new `Uint8Array`.
*
* `o.dataType` defaults to `"int64"` */
export function varbigBytes(x: bigint, o: VarbigOptions = {}): Uint8Array {
o.dataType = o.dataType ?? "int64";
const b = new Uint8Array(sizeof(o.dataType));
putVarbig(b, x, o);
return b;
}

236
encoding/binary_test.ts
View File

@ -1,236 +0,0 @@
// Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
import { assertEquals, assertRejects } from "../assert/mod.ts";
import {
getNBytes,
putVarbig,
putVarnum,
readExact,
readVarbig,
readVarnum,
sizeof,
varbig,
varbigBytes,
varnum,
varnumBytes,
writeVarbig,
writeVarnum,
} from "./binary.ts";
import { Buffer } from "../io/buffer.ts";
import { readerFromIterable } from "../streams/reader_from_iterable.ts";
Deno.test("testReadExactMultipleReads", async function () {
const reader = readerFromIterable([
new Uint8Array([1]),
new Uint8Array([2, 3]),
new Uint8Array([4, 5, 6]),
]);
const scratch = new Uint8Array(4);
await readExact(reader, scratch);
assertEquals(scratch, new Uint8Array([1, 2, 3, 4]));
});
Deno.test("testReadExactMultipleReadsDelayed", async function () {
const reader = readerFromIterable((async function* () {
yield new Uint8Array([1]);
await new Promise((r) => setTimeout(r, 1));
yield new Uint8Array([2, 3]);
await new Promise((r) => setTimeout(r, 10));
yield new Uint8Array([4, 5, 6]);
})());
const scratch = new Uint8Array(4);
await readExact(reader, scratch);
assertEquals(scratch, new Uint8Array([1, 2, 3, 4]));
});
Deno.test("testReadExactThrows", async function () {
const reader = readerFromIterable([
new Uint8Array([1]),
new Uint8Array([2, 3]),
]);
const scratch = new Uint8Array(4);
await assertRejects(async () => {
await readExact(reader, scratch);
}, Deno.errors.UnexpectedEof);
});
Deno.test("testGetNBytes", async function () {
const data = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
const buff = new Buffer(data.buffer);
const rslt = await getNBytes(buff, 8);
assertEquals(rslt, data);
});
Deno.test("testGetNBytesThrows", async function () {
const data = new Uint8Array([1, 2, 3, 4]);
const buff = new Buffer(data.buffer);
await assertRejects(async () => {
await getNBytes(buff, 8);
}, Deno.errors.UnexpectedEof);
});
Deno.test("testPutVarbig", function () {
const buff = new Uint8Array(8);
putVarbig(buff, 0xffeeddccbbaa9988n);
assertEquals(
buff,
new Uint8Array([0xff, 0xee, 0xdd, 0xcc, 0xbb, 0xaa, 0x99, 0x88]),
);
});
Deno.test("testPutVarbigLittleEndian", function () {
const buff = new Uint8Array(8);
putVarbig(buff, 0x8899aabbccddeeffn, { endian: "little" });
assertEquals(
buff,
new Uint8Array([0xff, 0xee, 0xdd, 0xcc, 0xbb, 0xaa, 0x99, 0x88]),
);
});
Deno.test("testPutVarnum", function () {
const buff = new Uint8Array(4);
putVarnum(buff, 0xffeeddcc);
assertEquals(buff, new Uint8Array([0xff, 0xee, 0xdd, 0xcc]));
});
Deno.test("testPutVarnumLittleEndian", function () {
const buff = new Uint8Array(4);
putVarnum(buff, 0xccddeeff, { endian: "little" });
assertEquals(buff, new Uint8Array([0xff, 0xee, 0xdd, 0xcc]));
});
Deno.test("testReadVarbig", async function () {
const data = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
const buff = new Buffer(data.buffer);
const rslt = await readVarbig(buff);
assertEquals(rslt, 0x0102030405060708n);
});
Deno.test("testReadVarbigLittleEndian", async function () {
const data = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
const buff = new Buffer(data.buffer);
const rslt = await readVarbig(buff, { endian: "little" });
assertEquals(rslt, 0x0807060504030201n);
});
Deno.test("testReadVarnum", async function () {
const data = new Uint8Array([1, 2, 3, 4]);
const buff = new Buffer(data.buffer);
const rslt = await readVarnum(buff);
assertEquals(rslt, 0x01020304);
});
Deno.test("testReadVarnumLittleEndian", async function () {
const data = new Uint8Array([1, 2, 3, 4]);
const buff = new Buffer(data.buffer);
const rslt = await readVarnum(buff, { endian: "little" });
assertEquals(rslt, 0x04030201);
});
Deno.test("testSizeof", function () {
assertEquals(1, sizeof("int8"));
assertEquals(1, sizeof("uint8"));
assertEquals(2, sizeof("int16"));
assertEquals(2, sizeof("uint16"));
assertEquals(4, sizeof("int32"));
assertEquals(4, sizeof("uint32"));
assertEquals(8, sizeof("int64"));
assertEquals(8, sizeof("uint64"));
assertEquals(4, sizeof("float32"));
assertEquals(8, sizeof("float64"));
});
Deno.test("testVarbig", function () {
const data = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
const rslt = varbig(data);
assertEquals(rslt, 0x0102030405060708n);
});
Deno.test("testVarbigLittleEndian", function () {
const data = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
const rslt = varbig(data, { endian: "little" });
assertEquals(rslt, 0x0807060504030201n);
});
Deno.test("testVarnum", function () {
const data = new Uint8Array([1, 2, 3, 4]);
const rslt = varnum(data);
assertEquals(rslt, 0x01020304);
});
Deno.test("testVarnumLittleEndian", function () {
const data = new Uint8Array([1, 2, 3, 4]);
const rslt = varnum(data, { endian: "little" });
assertEquals(rslt, 0x04030201);
});
Deno.test("testWriteVarbig", async function () {
const data = new Uint8Array(8);
const buff = new Buffer();
await writeVarbig(buff, 0x0102030405060708n);
await buff.read(data);
assertEquals(
data,
new Uint8Array([0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08]),
);
});
Deno.test("testWriteVarbigLittleEndian", async function () {
const data = new Uint8Array(8);
const buff = new Buffer();
await writeVarbig(buff, 0x0807060504030201n, { endian: "little" });
await buff.read(data);
assertEquals(
data,
new Uint8Array([0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08]),
);
});
Deno.test("testWriteVarnum", async function () {
const data = new Uint8Array(4);
const buff = new Buffer();
await writeVarnum(buff, 0x01020304);
await buff.read(data);
assertEquals(data, new Uint8Array([0x01, 0x02, 0x03, 0x04]));
});
Deno.test("testWriteVarnumLittleEndian", async function () {
const data = new Uint8Array(4);
const buff = new Buffer();
await writeVarnum(buff, 0x04030201, { endian: "little" });
await buff.read(data);
assertEquals(data, new Uint8Array([0x01, 0x02, 0x03, 0x04]));
});
Deno.test("testVarbigBytes", function () {
const rslt = varbigBytes(0x0102030405060708n);
assertEquals(
rslt,
new Uint8Array([0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08]),
);
});
Deno.test("testVarbigBytesLittleEndian", function () {
const rslt = varbigBytes(0x0807060504030201n, { endian: "little" });
assertEquals(
rslt,
new Uint8Array([0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08]),
);
});
Deno.test("testVarnumBytes", function () {
const rslt = varnumBytes(0x01020304);
assertEquals(rslt, new Uint8Array([0x01, 0x02, 0x03, 0x04]));
});
Deno.test("testVarnumBytesLittleEndian", function () {
const rslt = varnumBytes(0x04030201, { endian: "little" });
assertEquals(rslt, new Uint8Array([0x01, 0x02, 0x03, 0x04]));
});
Deno.test("testVarnumSubarray", function () {
const data = new Uint8Array([0x01, 0x02, 0x03, 0x04]);
const sub = data.subarray(2, 4);
const rslt = varnum(sub, { dataType: "uint8" });
assertEquals(rslt, 3);
});