@thi.ng/strings 3.6.6 → 3.7.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-11-09T10:28:19Z
+- **Last updated**: 2023-11-24T09:35:46Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,13 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [3.7.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/strings@3.7.0) (2023-11-24)
+
+#### 🚀 Features
+
+- add/migrate utf8 encode/decode/length fns ([a8955f2](https://github.com/thi-ng/umbrella/commit/a8955f2))
+  - migrate & update from [@thi.ng/transducers-binary](https://github.com/thi-ng/umbrella/tree/main/packages/transducers-binary)
+
 ### [3.6.5](https://github.com/thi-ng/umbrella/tree/@thi.ng/strings@3.6.5) (2023-11-09)
 
 #### ♻️ Refactoring

package/index.d.ts

@@ -31,6 +31,7 @@ export * from "./trim.js";
 export * from "./truncate.js";
 export * from "./truncate-left.js";
 export * from "./units.js";
+export * from "./utf8.js";
 export * from "./uuid.js";
 export * from "./vector.js";
 export * from "./wrap.js";

package/index.js

@@ -31,6 +31,7 @@ export * from "./trim.js";
 export * from "./truncate.js";
 export * from "./truncate-left.js";
 export * from "./units.js";
+export * from "./utf8.js";
 export * from "./uuid.js";
 export * from "./vector.js";
 export * from "./wrap.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/strings",
-  "version": "3.6.6",
+  "version": "3.7.0",
   "description": "Various string formatting & utility functions",
   "type": "module",
   "module": "./index.js",
@@ -33,18 +33,18 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.9.8",
-    "@thi.ng/errors": "^2.4.2",
-    "@thi.ng/hex": "^2.3.20",
-    "@thi.ng/memoize": "^3.1.42"
+    "@thi.ng/api": "^8.9.9",
+    "@thi.ng/errors": "^2.4.3",
+    "@thi.ng/hex": "^2.3.21",
+    "@thi.ng/memoize": "^3.1.43"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.38.2",
-    "@thi.ng/testament": "^0.4.1",
+    "@microsoft/api-extractor": "^7.38.3",
+    "@thi.ng/testament": "^0.4.2",
     "rimraf": "^5.0.5",
     "tools": "^0.0.1",
     "typedoc": "^0.25.3",
-    "typescript": "^5.2.2"
+    "typescript": "^5.3.2"
   },
   "keywords": [
     "ansi",
@@ -183,6 +183,9 @@
     "./units": {
       "default": "./units.js"
     },
+    "./utf8": {
+      "default": "./utf8.js"
+    },
     "./uuid": {
       "default": "./uuid.js"
     },
@@ -199,5 +202,5 @@
   "thi.ng": {
     "year": 2015
   },
-  "gitHead": "669a3151e4302480244fe3e60eff5e732ea5b7a7\n"
+  "gitHead": "f6de41f4991704fdbbb2899bb430ed4f4f6efab0\n"
 }

package/utf8.d.ts

@@ -0,0 +1,54 @@
+/// <reference types="node" />
+/**
+ * Returns the number of bytes required to encode the given string as UTF-8.
+ *
+ * @param str
+ */
+export declare const utf8Length: (str: string) => number;
+/**
+ * Non-transducer version of
+ * [`utf8Decode()`](https://docs.thi.ng/umbrella/transducers-binary/functions/utf8Decode.html).
+ * Decodes `num` bytes from `start` index in given byte buffer. In Firefox this
+ * is much faster than using the `TextDecoder` API.
+ *
+ * @param buf
+ * @param start
+ * @param num
+ */
+export declare const utf8Decode: (buf: Uint8Array, start: number, num: number) => string;
+/**
+ * Non-transducer version of
+ * [`utf8Encode()`](https://docs.thi.ng/umbrella/transducers-binary/functions/utf8Encode.html).
+ *
+ * @remarks
+ * If `capacity` is given, initializes the byte array to that size (and assumes
+ * that it is sufficient to store the entire string, e.g. by using
+ * {@link utf8Length} to pre-determine the number of bytes required for a given
+ * string). If `capacity` is _not_ provided, the buffer will be initialized to
+ * `4 * src.length`.
+ *
+ * Based on:
+ * - https://github.com/thi-ng/umbrella/blob/main/packages/transducers-binary/src/utf8.ts
+ * - https://gist.github.com/pascaldekloe/62546103a1576803dade9269ccf76330
+ *
+ * @param buf
+ */
+export declare const utf8Encode: (src: string, capacity?: number) => Uint8Array;
+/**
+ * Returns character string for given UTF-8 codepoint.
+ *
+ * @param x
+ */
+export declare const fromUtf8CodePoint: (x: number) => string;
+export declare const UTF8Error: {
+    new (msg?: string | undefined): {
+        name: string;
+        message: string;
+        stack?: string | undefined;
+        cause?: unknown;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function | undefined): void;
+    prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined;
+    stackTraceLimit: number;
+};
+//# sourceMappingURL=utf8.d.ts.map

package/utf8.js

@@ -0,0 +1,140 @@
+import { defError } from "@thi.ng/errors/deferror";
+/**
+ * Returns the number of bytes required to encode the given string as UTF-8.
+ *
+ * @param str
+ */
+export const utf8Length = (str) => {
+    const n = str.length;
+    let len = 0;
+    for (let i = 0; i < n; ++i) {
+        let u = str.charCodeAt(i);
+        if (u >= 0xd800 && u < 0xe0000) {
+            u = (0x10000 + ((u & 0x3ff) << 10)) | (str.charCodeAt(++i) & 0x3ff);
+        }
+        len +=
+            u < 0x80
+                ? 1
+                : u < 0x800
+                    ? 2
+                    : u < 0x10000
+                        ? 3
+                        : u < 0x200000
+                            ? 4
+                            : u < 0x4000000
+                                ? 5
+                                : 6;
+    }
+    return len;
+};
+/**
+ * Non-transducer version of
+ * [`utf8Decode()`](https://docs.thi.ng/umbrella/transducers-binary/functions/utf8Decode.html).
+ * Decodes `num` bytes from `start` index in given byte buffer. In Firefox this
+ * is much faster than using the `TextDecoder` API.
+ *
+ * @param buf
+ * @param start
+ * @param num
+ */
+export const utf8Decode = (buf, start, num) => {
+    const end = start + num;
+    let i = start;
+    let result = "";
+    let c;
+    while (i < end) {
+        c = buf[i++];
+        if (c < 0x80) {
+            result += String.fromCharCode(c);
+        }
+        else {
+            if (c >= 0xc0 && c < 0xe0) {
+                c = ((c & 0x1f) << 6) | (buf[i++] & 0x3f);
+            }
+            else if (c >= 0xe0 && c < 0xf0) {
+                c =
+                    ((c & 0x0f) << 12) |
+                        ((buf[i++] & 0x3f) << 6) |
+                        (buf[i++] & 0x3f);
+            }
+            else if (c >= 0xf0 && c < 0xf8) {
+                c =
+                    ((c & 7) << 18) |
+                        ((buf[i++] & 0x3f) << 12) |
+                        ((buf[i++] & 0x3f) << 6) |
+                        (buf[i++] & 0x3f);
+            }
+            else
+                utf8Error();
+            result += fromUtf8CodePoint(c);
+        }
+    }
+    return result;
+};
+/**
+ * Non-transducer version of
+ * [`utf8Encode()`](https://docs.thi.ng/umbrella/transducers-binary/functions/utf8Encode.html).
+ *
+ * @remarks
+ * If `capacity` is given, initializes the byte array to that size (and assumes
+ * that it is sufficient to store the entire string, e.g. by using
+ * {@link utf8Length} to pre-determine the number of bytes required for a given
+ * string). If `capacity` is _not_ provided, the buffer will be initialized to
+ * `4 * src.length`.
+ *
+ * Based on:
+ * - https://github.com/thi-ng/umbrella/blob/main/packages/transducers-binary/src/utf8.ts
+ * - https://gist.github.com/pascaldekloe/62546103a1576803dade9269ccf76330
+ *
+ * @param buf
+ */
+export const utf8Encode = (src, capacity) => {
+    const n = src.length;
+    const buf = new Uint8Array(capacity || n << 2);
+    let pos = 0;
+    let c;
+    for (let i = 0; i < n; i++) {
+        c = src.charCodeAt(i);
+        if (c < 0x80) {
+            buf[pos++] = c;
+        }
+        else {
+            if (c < 0x800) {
+                buf[pos++] = 0xc0 | (c >> 6);
+            }
+            else {
+                if (c >= 0xd800 && c < 0xdc00) {
+                    c =
+                        0x10000 +
+                            ((c & 0x03ff) << 10) +
+                            (src.charCodeAt(++i) & 0x3ff);
+                    buf[pos++] = 0xf0 | (c >> 18);
+                    buf[pos++] = 0x80 | ((c >> 12) & 0x3f);
+                }
+                else
+                    buf[pos++] = 0xe0 | (c >> 12);
+                buf[pos++] = 0x80 | ((c >> 6) & 0x3f);
+            }
+            buf[pos++] = 0x80 | (c & 0x3f);
+        }
+    }
+    return buf.subarray(0, pos);
+};
+/**
+ * Returns character string for given UTF-8 codepoint.
+ *
+ * @param x
+ */
+export const fromUtf8CodePoint = (x) => {
+    if (x < 0x10000)
+        return String.fromCharCode(x);
+    if (x < 0x110000) {
+        x -= 0x10000;
+        return String.fromCharCode(0xd800 | (x >>> 10), 0xdc00 | (x & 0x3ff));
+    }
+    return utf8Error(`invalid codepoint 0x${x.toString(16)}`);
+};
+export const UTF8Error = defError(() => "UTF-8 error");
+const utf8Error = (msg) => {
+    throw new UTF8Error(msg);
+};