Add intercalate to arrays

docs/modules/Array.ts.md

@@ -87,6 +87,7 @@ Added in v2.0.0
   - [flatten](#flatten)
   - [fromEitherK](#fromeitherk)
   - [fromOptionK](#fromoptionk)
+  - [intercalate](#intercalate)
   - [intersection](#intersection)
   - [intersperse](#intersperse)
   - [lefts](#lefts)
@@ -1436,6 +1437,28 @@ export declare const fromOptionK: <A extends readonly unknown[], B>(f: (...a: A)
 
 Added in v2.11.0
 
+## intercalate
+
+Creates a new `Array` placing an element in between members of the input `Array`, then folds the results using the
+provided `Monoid`.
+
+**Signature**
+
+```ts
+export declare const intercalate: <A>(M: Monoid<A>) => (sep: A) => (as: A[]) => A
+```
+
+**Example**
+
+```ts
+import * as S from 'fp-ts/string'
+import { intercalate } from 'fp-ts/Array'
+
+assert.deepStrictEqual(intercalate(S.Monoid)('-')(['a', 'b', 'c']), 'a-b-c')
+```
+
+Added in v2.11.9
+
 ## intersection
 
 Creates an array of unique values that are included in all given arrays using a `Eq` for equality

docs/modules/NonEmptyArray.ts.md

@@ -63,6 +63,7 @@ Added in v2.0.0
   - [group](#group)
   - [groupBy](#groupby)
   - [insertAt](#insertat)
+  - [intercalate](#intercalate)
   - [intersperse](#intersperse)
   - [modifyAt](#modifyat)
   - [prependAll](#prependall)
@@ -531,6 +532,27 @@ export declare const insertAt: <A>(i: number, a: A) => (as: A[]) => Option<NonEm
 
 Added in v2.0.0
 
+## intercalate
+
+**Note**. The constraint is relaxed: a `Semigroup` instead of a `Monoid`.
+
+**Signature**
+
+```ts
+export declare const intercalate: <A>(S: Se.Semigroup<A>) => (sep: A) => (as: NonEmptyArray<A>) => A
+```
+
+**Example**
+
+```ts
+import * as S from 'fp-ts/string'
+import { intercalate } from 'fp-ts/NonEmptyArray'
+
+assert.deepStrictEqual(intercalate(S.Semigroup)('-')(['a', 'b', 'c']), 'a-b-c')
+```
+
+Added in v2.11.9
+
 ## intersperse
 
 Places an element in between members of an array

docs/modules/ReadonlyArray.ts.md

@@ -82,6 +82,7 @@ Added in v2.5.0
   - [flatten](#flatten)
   - [fromEitherK](#fromeitherk)
   - [fromOptionK](#fromoptionk)
+  - [intercalate](#intercalate)
   - [intersection](#intersection)
   - [intersperse](#intersperse)
   - [lefts](#lefts)
@@ -970,6 +971,27 @@ export declare const fromOptionK: <A extends readonly unknown[], B>(
 
 Added in v2.11.0
 
+## intercalate
+
+Places an element in between members of an array`, then folds the results using the provided `Monoid`.
+
+**Signature**
+
+```ts
+export declare const intercalate: <A>(M: Monoid<A>) => (sep: A) => (as: readonly A[]) => A
+```
+
+**Example**
+
+```ts
+import * as S from 'fp-ts/string'
+import { intercalate } from 'fp-ts/Array'
+
+assert.deepStrictEqual(intercalate(S.Monoid)('-')(['a', 'b', 'c']), 'a-b-c')
+```
+
+Added in v2.11.9
+
 ## intersection
 
 Creates an array of unique values that are included in all given arrays using a `Eq` for equality
@@ -1901,7 +1923,7 @@ Added in v2.7.0
 **Signature**
 
 ```ts
-export declare const Foldable: Foldable1<'ReadonlyArray'>
+export declare const Foldable: F.Foldable1<'ReadonlyArray'>
 ```
 
 Added in v2.7.0

docs/modules/ReadonlyNonEmptyArray.ts.md

@@ -68,6 +68,7 @@ Added in v2.5.0
   - [getUnionSemigroup](#getunionsemigroup)
   - [group](#group)
   - [groupBy](#groupby)
+  - [intercalate](#intercalate)
   - [intersperse](#intersperse)
   - [modifyAt](#modifyat)
   - [prependAll](#prependall)
@@ -607,6 +608,27 @@ assert.deepStrictEqual(groupBy((s: string) => String(s.length))(['a', 'b', 'ab']
 
 Added in v2.5.0
 
+## intercalate
+
+**Note**. The constraint is relaxed: a `Semigroup` instead of a `Monoid`.
+
+**Signature**
+
+```ts
+export declare const intercalate: <A>(S: Se.Semigroup<A>) => (sep: A) => (as: ReadonlyNonEmptyArray<A>) => A
+```
+
+**Example**
+
+```ts
+import * as S from 'fp-ts/string'
+import { intercalate } from 'fp-ts/ReadonlyNonEmptyArray'
+
+assert.deepStrictEqual(intercalate(S.Semigroup)('-')(['a', 'b', 'c']), 'a-b-c')
+```
+
+Added in v2.11.9
+
 ## intersperse
 
 Places an element in between members of a `ReadonlyNonEmptyArray`.

src/Array.ts

@@ -1124,6 +1124,21 @@ export const intersperse = <A>(middle: A): ((as: Array<A>) => Array<A>) => {
   return (as) => (isNonEmpty(as) ? f(as) : copy(as))
 }
 
+/**
+ * Creates a new `Array` placing an element in between members of the input `Array`, then folds the results using the
+ * provided `Monoid`.
+ *
+ * @example
+ * import * as S from 'fp-ts/string'
+ * import { intercalate } from 'fp-ts/Array'
+ *
+ * assert.deepStrictEqual(intercalate(S.Monoid)('-')(['a', 'b', 'c']), 'a-b-c')
+ *
+ * @category combinators
+ * @since 2.11.9
+ */
+export const intercalate: <A>(M: Monoid<A>) => (sep: A) => (as: Array<A>) => A = RA.intercalate
+
 /**
  * Creates a new `Array` rotating the input `Array` by `n` steps.
  *

src/NonEmptyArray.ts

@@ -551,6 +551,20 @@ export const intersperse = <A>(middle: A) => (as: NonEmptyArray<A>): NonEmptyArr
   return isNonEmpty(rest) ? pipe(rest, prependAll(middle), prepend(head(as))) : copy(as)
 }
 
+/**
+ * **Note**. The constraint is relaxed: a `Semigroup` instead of a `Monoid`.
+ *
+ * @example
+ * import * as S from 'fp-ts/string'
+ * import { intercalate } from 'fp-ts/NonEmptyArray'
+ *
+ * assert.deepStrictEqual(intercalate(S.Semigroup)('-')(['a', 'b', 'c']), 'a-b-c')
+ *
+ * @category combinators
+ * @since 2.11.9
+ */
+export const intercalate: <A>(S: Semigroup<A>) => (sep: A) => (as: NonEmptyArray<A>) => A = RNEA.intercalate
+
 /**
  * @category combinators
  * @since 2.0.0

src/ReadonlyArray.ts

@@ -13,7 +13,7 @@ import { Eq, fromEquals } from './Eq'
 import { Extend1 } from './Extend'
 import { Filterable1 } from './Filterable'
 import { FilterableWithIndex1, PredicateWithIndex, RefinementWithIndex } from './FilterableWithIndex'
-import { Foldable1 } from './Foldable'
+import * as F from './Foldable'
 import { FoldableWithIndex1 } from './FoldableWithIndex'
 import { FromEither1, fromEitherK as fromEitherK_ } from './FromEither'
 import { identity, Lazy, pipe } from './function'
@@ -49,6 +49,7 @@ import {
 } from './Witherable'
 import { Zero1, guard as guard_ } from './Zero'
 
+import Foldable1 = F.Foldable1
 import ReadonlyNonEmptyArray = RNEA.ReadonlyNonEmptyArray
 
 // -------------------------------------------------------------------------------------
@@ -1012,6 +1013,21 @@ export const intersperse = <A>(middle: A): ((as: ReadonlyArray<A>) => ReadonlyAr
   return (as) => (isNonEmpty(as) ? f(as) : as)
 }
 
+/**
+ * Places an element in between members of an array`, then folds the results using the provided `Monoid`.
+ *
+ * @example
+ * import * as S from 'fp-ts/string'
+ * import { intercalate } from 'fp-ts/Array'
+ *
+ * assert.deepStrictEqual(intercalate(S.Monoid)('-')(['a', 'b', 'c']), 'a-b-c')
+ *
+ * @category combinators
+ * @since 2.11.9
+ */
+export const intercalate: <A>(M: Monoid<A>) => (sep: A) => (as: ReadonlyArray<A>) => A = (M) => (sep) => (as) =>
+  F.intercalate(M, Foldable)(sep, as)
+
 /**
  * Rotate a `ReadonlyArray` by `n` steps.
  *

src/ReadonlyNonEmptyArray.ts

@@ -566,6 +566,22 @@ export const intersperse = <A>(middle: A) => (as: ReadonlyNonEmptyArray<A>): Rea
   return isNonEmpty(rest) ? pipe(rest, prependAll(middle), prepend(head(as))) : as
 }
 
+/**
+ * **Note**. The constraint is relaxed: a `Semigroup` instead of a `Monoid`.
+ *
+ * @example
+ * import * as S from 'fp-ts/string'
+ * import { intercalate } from 'fp-ts/ReadonlyNonEmptyArray'
+ *
+ * assert.deepStrictEqual(intercalate(S.Semigroup)('-')(['a', 'b', 'c']), 'a-b-c')
+ *
+ * @category combinators
+ * @since 2.11.9
+ */
+export const intercalate: <A>(S: Semigroup<A>) => (sep: A) => (as: ReadonlyNonEmptyArray<A>) => A = (S) => (sep) => (
+  as
+) => concatAll(S)(intersperse(sep)(as))
+
 /**
  * @category combinators
  * @since 2.10.0

test/Array.ts

@@ -702,6 +702,15 @@ describe('Array', () => {
     U.deepStrictEqual(_.intersperse(0)([1, 2, 3, 4]), [1, 0, 2, 0, 3, 0, 4])
   })
 
+  it('intercalate', () => {
+    U.deepStrictEqual(_.intercalate(S.Monoid)('-')([]), '')
+    U.deepStrictEqual(_.intercalate(S.Monoid)('-')(['a']), 'a')
+    U.deepStrictEqual(_.intercalate(S.Monoid)('-')(['a', 'b', 'c']), 'a-b-c')
+    U.deepStrictEqual(_.intercalate(S.Monoid)('-')(['a', '', 'c']), 'a--c')
+    U.deepStrictEqual(_.intercalate(S.Monoid)('-')(['a', 'b']), 'a-b')
+    U.deepStrictEqual(_.intercalate(S.Monoid)('-')(['a', 'b', 'c', 'd']), 'a-b-c-d')
+  })
+
   it('zipWith', () => {
     U.deepStrictEqual(
       _.zipWith([1, 2, 3], ['a', 'b', 'c', 'd'], (n, s) => s + n),

test/NonEmptyArray.ts

@@ -187,6 +187,14 @@ describe('NonEmptyArray', () => {
     U.deepStrictEqual(_.intersperse(0)([1, 2, 3, 4]), [1, 0, 2, 0, 3, 0, 4])
   })
 
+  it('intercalate', () => {
+    U.deepStrictEqual(_.intercalate(S.Semigroup)('-')(['a']), 'a')
+    U.deepStrictEqual(_.intercalate(S.Semigroup)('-')(['a', 'b', 'c']), 'a-b-c')
+    U.deepStrictEqual(_.intercalate(S.Semigroup)('-')(['a', '', 'c']), 'a--c')
+    U.deepStrictEqual(_.intercalate(S.Semigroup)('-')(['a', 'b']), 'a-b')
+    U.deepStrictEqual(_.intercalate(S.Semigroup)('-')(['a', 'b', 'c', 'd']), 'a-b-c-d')
+  })
+
   it('reverse', () => {
     U.deepStrictEqual(_.reverse([1, 2, 3]), [3, 2, 1])
   })

test/ReadonlyArray.ts

@@ -802,6 +802,15 @@ describe('ReadonlyArray', () => {
     U.deepStrictEqual(_.intersperse(0)([1, 2, 3, 4]), [1, 0, 2, 0, 3, 0, 4])
   })
 
+  it('intercalate', () => {
+    U.deepStrictEqual(_.intercalate(S.Monoid)('-')([]), '')
+    U.deepStrictEqual(_.intercalate(S.Monoid)('-')(['a']), 'a')
+    U.deepStrictEqual(_.intercalate(S.Monoid)('-')(['a', 'b', 'c']), 'a-b-c')
+    U.deepStrictEqual(_.intercalate(S.Monoid)('-')(['a', '', 'c']), 'a--c')
+    U.deepStrictEqual(_.intercalate(S.Monoid)('-')(['a', 'b']), 'a-b')
+    U.deepStrictEqual(_.intercalate(S.Monoid)('-')(['a', 'b', 'c', 'd']), 'a-b-c-d')
+  })
+
   it('rotate', () => {
     U.strictEqual(_.rotate(0)(_.empty), _.empty)
     U.strictEqual(_.rotate(1)(_.empty), _.empty)

test/ReadonlyNonEmptyArray.ts

@@ -198,6 +198,14 @@ describe('ReadonlyNonEmptyArray', () => {
     U.deepStrictEqual(_.intersperse(0)([1, 2, 3, 4]), [1, 0, 2, 0, 3, 0, 4])
   })
 
+  it('intercalate', () => {
+    U.deepStrictEqual(_.intercalate(S.Semigroup)('-')(['a']), 'a')
+    U.deepStrictEqual(_.intercalate(S.Semigroup)('-')(['a', 'b', 'c']), 'a-b-c')
+    U.deepStrictEqual(_.intercalate(S.Semigroup)('-')(['a', '', 'c']), 'a--c')
+    U.deepStrictEqual(_.intercalate(S.Semigroup)('-')(['a', 'b']), 'a-b')
+    U.deepStrictEqual(_.intercalate(S.Semigroup)('-')(['a', 'b', 'c', 'd']), 'a-b-c-d')
+  })
+
   it('reverse', () => {
     const singleton: _.ReadonlyNonEmptyArray<number> = [1]
     U.strictEqual(_.reverse(singleton), singleton)