Add string functions

diff --git a/mod.js b/mod.js
index dc8d6fc511a4c9a227594efb171fe08bad8c6268..9dd8fd1192936b735214a3a427cf0fb09cfd740d 100644 (file)
--- a/mod.js
+++ b/mod.js
@@ -12,3 +12,4 @@ export * from "./collection.js";
 export * from "./iri.js";
 export * from "./numeric.js";
 export * from "./object.js";
+export * from "./string.js";

diff --git a/string.js b/string.js
new file mode 100644 (file)
index 0000000..17e8736
--- /dev/null
+++ b/string.js
@@ -0,0 +1,81 @@
+// ♓🌟 Piscēs ∷ string.js
+// ====================================================================
+//
+// Copyright © 2022 Lady [@ Lady’s Computer].
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at <https://mozilla.org/MPL/2.0/>.
+
+/**
+ * Returns the result of converting the provided value to A·S·C·I·I
+ * lowercase.
+ */
+export const asciiLowercase = ($) =>
+  `${$}`.replaceAll(
+    /[A-Z]/gu,
+    Function.prototype.call.bind(String.prototype.toLowerCase),
+  );
+
+/**
+ * Returns the result of converting the provided value to A·S·C·I·I
+ * uppercase.
+ */
+export const asciiUppercase = ($) =>
+  `${$}`.replaceAll(
+    /[a-z]/gu,
+    Function.prototype.call.bind(String.prototype.toUpperCase),
+  );
+
+/**
+ * Returns the result of converting the provided value to a string of
+ * scalar values by replacing (unpaired) surrogate values with U+FFFD.
+ */
+export const scalarValueString = ($) =>
+  String.fromCodePoint(
+    ...function* () {
+      for (const char of `${$}`) {
+        const scalar = char.codePointAt(0);
+        yield scalar >= 0xD800 && scalar <= 0xDFFF ? 0xFFFD : scalar;
+      }
+    }(),
+  );
+
+/**
+ * Returns the result of splitting the provided value on A·S·C·I·I
+ * whitespace.
+ */
+export const splitOnASCIIWhitespace = ($) =>
+  stripAndCollapseASCIIWhitespace($).split(" ");
+
+/**
+ * Returns the result of splitting the provided value on commas,
+ * trimming A·S·C·I·I whitespace from the resulting tokens.
+ */
+export const splitOnCommas = ($) =>
+  stripLeadingAndTrailingASCIIWhitespace(
+    `${$}`.replaceAll(
+      /[\n\r\t\f ]*,[\n\r\t\f ]*/gu,
+      ",",
+    ),
+  ).split(",");
+
+/**
+ * Returns the result of stripping leading and trailing A·S·C·I·I
+ * whitespace from the provided value.
+ */
+export const stripLeadingAndTrailingASCIIWhitespace = ($) =>
+  /^[\n\r\t\f ]*([^]*?)[\n\r\t\f ]*$/u.exec($)[1];
+
+/**
+ * Returns the result of stripping leading and trailing A·S·C·I·I
+ * whitespace from the provided value and collapsing other A·S·C·I·I
+ * whitespace in the provided value.
+ */
+export const stripAndCollapseASCIIWhitespace = ($) =>
+  stripLeadingAndTrailingASCIIWhitespace(
+    `${$}`.replaceAll(
+      /[\n\r\t\f ]+/gu,
+      " ",
+    ),
+  );