feat(collections): add joinToString

collections/README.md

@@ -379,6 +379,36 @@ const commonInterests = intersect(lisaInterests, kimInterests);
 assertEquals(commonInterests, ["Cooking", "Music"]);
 ```
 
+### joinToString
+
+Transforms the elements in the given array to strings using the given selector.
+Joins the produced strings into one using the given `separator` and applying the
+given `prefix` and `suffix` to the whole string afterwards. If the array could
+be huge, you can specify a non-negative value of `limit`, in which case only the
+first `limit` elements will be appended, followed by the `truncated` string.
+Returns the resulting string.
+
+```ts
+import { joinToString } from "https://deno.land/std@$STD_VERSION/collections/mod.ts";
+import { assertEquals } from "https://deno.land/std@$STD_VERSION/testing/asserts.ts";
+
+const users = [
+  { name: "Kim" },
+  { name: "Anna" },
+  { name: "Tim" },
+];
+
+const message = joinToString(users, (it) => it.name, {
+  suffix: " are winners",
+  prefix: "result: ",
+  separator: " and ",
+  limit: 1,
+  truncated: "others",
+});
+
+assertEquals(message, "result: Kim and others are winners");
+```
+
 ### mapEntries
 
 Applies the given transformer to all entries in the given record and returns a

collections/join_to_string.ts

@@ -0,0 +1,75 @@
+// Copyright 2018-2021 the Deno authors. All rights reserved. MIT license.
+
+/**
+ * Options for joinToString
+ */
+export type JoinToStringOptions = {
+  separator?: string;
+  prefix?: string;
+  suffix?: string;
+  limit?: number;
+  truncated?: string;
+};
+
+/**
+ * Transforms the elements in the given array to strings using the given selector.
+ * Joins the produced strings into one using the given `separator` and applying the given `prefix` and `suffix` to the whole string afterwards.
+ * If the array could be huge, you can specify a non-negative value of `limit`, in which case only the first `limit` elements will be appended, followed by the `truncated` string.
+ * Returns the resulting string.
+ *
+ * Example:
+ *
+ * ```ts
+ * import { joinToString } from "https://deno.land/std@$STD_VERSION/collections/mod.ts";
+ * import { assertEquals } from "https://deno.land/std@$STD_VERSION/testing/asserts.ts";
+ *
+ * const users = [
+ *   { name: "Kim" },
+ *   { name: "Anna" },
+ *   { name: "Tim" },
+ * ];
+ *
+ *  const message = joinToString(users, (it) => it.name, {
+ *   suffix: " are winners",
+ *   prefix: "result: ",
+ *   separator: " and ",
+ *   limit: 1,
+ *   truncated: "others",
+ * });
+ *
+ * assertEquals(message, "result: Kim and others are winners");
+ * ```
+ */
+export function joinToString<T>(
+  array: readonly T[],
+  selector: (el: T) => string,
+  {
+    separator = ",",
+    prefix = "",
+    suffix = "",
+    limit = -1,
+    truncated = "...",
+  }: Readonly<JoinToStringOptions> = {},
+): string {
+  let result = "";
+
+  let index = -1;
+  while (++index < array.length) {
+    const el = array[index];
+
+    if (index > 0) {
+      result += separator;
+    }
+
+    if (limit > -1 && index >= limit) {
+      result += truncated;
+      break;
+    }
+
+    result += selector(el);
+  }
+
+  result = prefix + result + suffix;
+
+  return result;
+}

collections/join_to_string_test.ts

@@ -0,0 +1,146 @@
+// Copyright 2018-2021 the Deno authors. All rights reserved. MIT license.
+
+import { assertEquals } from "../testing/asserts.ts";
+import { joinToString } from "./join_to_string.ts";
+
+Deno.test({
+  name: "[collections/joinToString] no mutation",
+  fn() {
+    const arr = [
+      { name: "Kim", age: 22 },
+      { name: "Anna", age: 31 },
+      { name: "Tim", age: 58 },
+    ];
+    joinToString(arr, (it) => it.name);
+
+    assertEquals(arr, [
+      { name: "Kim", age: 22 },
+      { name: "Anna", age: 31 },
+      { name: "Tim", age: 58 },
+    ]);
+  },
+});
+
+Deno.test({
+  name: "[collections/joinToString] identity",
+  fn() {
+    const arr = ["Kim", "Anna", "Tim"];
+
+    const out = joinToString(arr, (it) => it);
+
+    assertEquals(out, "Kim,Anna,Tim");
+  },
+});
+
+Deno.test({
+  name: "[collections/joinToString] normal mapppers",
+  fn() {
+    const arr = [
+      { name: "Kim", age: 22 },
+      { name: "Anna", age: 31 },
+      { name: "Tim", age: 58 },
+    ];
+    const out = joinToString(arr, (it) => it.name);
+
+    assertEquals(out, "Kim,Anna,Tim");
+  },
+});
+
+Deno.test({
+  name: "[collections/joinToString] separator",
+  fn() {
+    const arr = [
+      { name: "Kim", age: 22 },
+      { name: "Anna", age: 31 },
+      { name: "Tim", age: 58 },
+    ];
+    const out = joinToString(arr, (it) => it.name, { separator: " and " });
+
+    assertEquals(out, "Kim and Anna and Tim");
+  },
+});
+
+Deno.test({
+  name: "[collections/joinToString] prefix",
+  fn() {
+    const arr = [
+      { name: "Kim", age: 22 },
+      { name: "Anna", age: 31 },
+      { name: "Tim", age: 58 },
+    ];
+    const out = joinToString(arr, (it) => it.name, {
+      prefix: "winners are: ",
+    });
+
+    assertEquals(out, "winners are: Kim,Anna,Tim");
+  },
+});
+
+Deno.test({
+  name: "[collections/joinToString] suffix",
+  fn() {
+    const arr = [
+      { name: "Kim", age: 22 },
+      { name: "Anna", age: 31 },
+      { name: "Tim", age: 58 },
+    ];
+    const out = joinToString(arr, (it) => it.name, {
+      suffix: " are winners",
+    });
+
+    assertEquals(out, "Kim,Anna,Tim are winners");
+  },
+});
+
+Deno.test({
+  name: "[collections/joinToString] limit",
+  fn() {
+    const arr = [
+      { name: "Kim", age: 22 },
+      { name: "Anna", age: 31 },
+      { name: "Tim", age: 58 },
+    ];
+    const out = joinToString(arr, (it) => it.name, {
+      limit: 2,
+    });
+
+    assertEquals(out, "Kim,Anna,...");
+  },
+});
+
+Deno.test({
+  name: "[collections/joinToString] truncated",
+  fn() {
+    const arr = [
+      { name: "Kim", age: 22 },
+      { name: "Anna", age: 31 },
+      { name: "Tim", age: 58 },
+    ];
+    const out = joinToString(arr, (it) => it.name, {
+      limit: 2,
+      truncated: "...!",
+    });
+
+    assertEquals(out, "Kim,Anna,...!");
+  },
+});
+
+Deno.test({
+  name: "[collections/joinToString] all options",
+  fn() {
+    const arr = [
+      { name: "Kim", age: 22 },
+      { name: "Anna", age: 31 },
+      { name: "Tim", age: 58 },
+    ];
+    const out = joinToString(arr, (it) => it.name, {
+      suffix: " are winners",
+      prefix: "result: ",
+      separator: " and ",
+      limit: 1,
+      truncated: "others",
+    });
+
+    assertEquals(out, "result: Kim and others are winners");
+  },
+});

collections/mod.ts

@@ -32,6 +32,7 @@ export * from "./union.ts";
 export * from "./without_all.ts";
 export * from "./unzip.ts";
 export * from "./zip.ts";
+export * from "./join_to_string.ts";
 export * from "./max_with.ts";
 export * from "./min_with.ts";
 export * from "./includes_value.ts";