@thi.ng/hex 2.3.85 → 2.4.0

package/README.md

@@ -20,6 +20,7 @@
 - [Installation](#installation)
 - [Dependencies](#dependencies)
 - [API](#api)
+  - [Creating hexdumps](#creating-hexdumps)
 - [Authors](#authors)
 - [License](#license)
 
@@ -63,7 +64,7 @@ For Node.js REPL:
 const hex = await import("@thi.ng/hex");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 631 bytes
+Package sizes (brotli'd, pre-treeshake): ESM: 616 bytes
 
 ## Dependencies
 
@@ -73,7 +74,7 @@ None
 
 [Generated API docs](https://docs.thi.ng/umbrella/hex/)
 
-```ts
+```ts tangle:export/readme.ts
 import * as h from "@thi.ng/hex";
 
 const cssColor = (x: number) => "#" + h.U24(x);
@@ -113,6 +114,32 @@ h.U32LE(BUF, 4)
 // "40302010"
 ```
 
+### Creating hexdumps
+
+The following functions are provided to create customizable hexdumps:
+
+- [hexdump()](https://docs.thi.ng/umbrella/hex/functions/hexdump.html)
+- [hexdumpLines()](https://docs.thi.ng/umbrella/hex/functions/hexdumpLines.html)
+- [printHexdump()](https://docs.thi.ng/umbrella/hex/functions/printHexdump.html)
+
+```ts tangle:export/readme-hexdump.ts
+import { printHexdump } from "@thi.ng/hex";
+import { readFileSync } from "node:fs";
+
+const bytes = readFileSync("README.md");
+
+// hexdump of the first 100 bytes
+printHexdump(bytes, 0, 100);
+
+// 00000000 21 5b 74 68 69 2e 6e 67 2f 75 6d 62 72 65 6c 6c ![thi.ng/umbrell
+// 00000010 61 5d 28 68 74 74 70 73 3a 2f 2f 72 61 77 2e 67 a](https://raw.g
+// 00000020 69 74 68 75 62 75 73 65 72 63 6f 6e 74 65 6e 74 ithubusercontent
+// 00000030 2e 63 6f 6d 2f 74 68 69 2d 6e 67 2f 75 6d 62 72 .com/thi-ng/umbr
+// 00000040 65 6c 6c 61 2f 64 65 76 65 6c 6f 70 2f 61 73 73 ella/develop/ass
+// 00000050 65 74 73 2f 62 61 6e 6e 65 72 73 2f 74 68 69 6e ets/banners/thin
+// 00000060 67 2d 75 6d                                     g-um
+```
+
 ## Authors
 
 - [Karsten Schmidt](https://thi.ng)

package/index.d.ts

@@ -166,6 +166,58 @@ export declare const U64LE: (x: ArrayLike<number>, i: number) => string;
  * @param i -
  */
 export declare const uuid: (id: ArrayLike<number>, i?: number) => string;
-export declare const hexdump: (bytes: Uint8Array | Uint8ClampedArray, addr: number, len: number, width?: number, ascii?: boolean) => string;
-export declare const hexdumpLines: (bytes: Uint8Array | Uint8ClampedArray, addr: number, len: number, width?: number, ascii?: boolean) => string[];
+/**
+ * Takes a byte array, and optional start address, length and other opts.
+ * Produces a hexdump as string.
+ *
+ * @remarks
+ * Also see {@link printHexdump}, {@link hexdumpLines}.
+ *
+ * @example
+ * ```ts tangle:../export/hexdump.ts
+ * import { printHexdump } from "@thi.ng/hex";
+ *
+ * const bytes = new TextEncoder().encode("Hellö Wørld! 👋🤝🫶 ...so long!");
+ * printHexdump(bytes);
+ *
+ * // 00000000 48 65 6c 6c c3 b6 20 57 c3 b8 72 6c 64 21 20 f0 Hell.. W..rld! .
+ * // 00000010 9f 91 8b f0 9f a4 9d f0 9f ab b6 20 2e 2e 2e 73 ........... ...s
+ * // 00000020 6f 20 6c 6f 6e 67 21                            o long!
+ * ```
+ *
+ * @param bytes
+ * @param addr
+ * @param len
+ * @param width
+ * @param ascii
+ */
+export declare const hexdump: (bytes: Uint8Array | Uint8ClampedArray, addr?: number, len?: number, width?: number, ascii?: boolean) => string;
+/**
+ * Syntax sugar for `console.log(hexdump(...))`.
+ *
+ * @param bytes
+ * @param addr
+ * @param len
+ * @param width
+ * @param ascii
+ */
+export declare const printHexdump: (bytes: Uint8Array | Uint8ClampedArray, addr?: number, len?: number, width?: number, ascii?: boolean) => void;
+/**
+ * Takes a byte array, and optional start address, length and other opts.
+ * Produces a hexdump as string array.
+ *
+ * @remarks
+ * The `width` arg specifies the number of bytes per line. The `ascii` flag
+ * indicates if the bytes of each row should also be formatted as ASCII in an
+ * additional column (non-printable ASCII values are represented as `.`).
+ *
+ * Also see {@link printHexdump}, {@link hexdumpLines}.
+ *
+ * @param bytes
+ * @param addr
+ * @param len
+ * @param width
+ * @param ascii
+ */
+export declare const hexdumpLines: (bytes: Uint8Array | Uint8ClampedArray, addr?: number, len?: number, width?: number, ascii?: boolean) => string[];
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -26,7 +26,8 @@ const uuid = (id, i = 0) => (
   `${U32BE(id, i)}-${U16BE(id, i + 4)}-${U16BE(id, i + 6)}-${U16BE(id, i + 8)}-${U48BE(id, i + 10)}`
 );
 const hexdump = (bytes, addr, len, width, ascii) => hexdumpLines(bytes, addr, len, width, ascii).join("\n");
-const hexdumpLines = (bytes, addr, len, width = 16, ascii = true) => {
+const printHexdump = (bytes, addr, len, width, ascii) => console.log(hexdump(bytes, addr, len, width, ascii));
+const hexdumpLines = (bytes, addr = 0, len = bytes.length - addr, width = 16, ascii = true) => {
   len = Math.min(len, bytes.length - addr);
   let res = [];
   while (len > 0) {
@@ -72,5 +73,6 @@ export {
   U8A,
   hexdump,
   hexdumpLines,
+  printHexdump,
   uuid
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@thi.ng/hex",
-	"version": "2.3.85",
+	"version": "2.4.0",
 	"description": "Hex string formatters for 4/8/16/24/32/48/64bit words, hexdump formatting of binary data",
 	"type": "module",
 	"module": "./index.js",
@@ -73,5 +73,5 @@
 		],
 		"year": 2020
 	},
-	"gitHead": "d977f819bcafdcb2b24c45f8d01a167fe29fc85a\n"
+	"gitHead": "74b6f319d8f52c9266d97f616be5298a6a5b96e4\n"
 }