perf(array): pre-size Ap and Flatten results (#190)

* perf(array): pre-size Ap and Flatten results

array.Ap and array.Flatten both routed through MonadChain, which grows the
result from nil and (for Ap) allocates an intermediate slice per function.
Their output lengths are known up front -- len(fab)*len(fa) for the
applicative cartesian product and the sum of inner lengths for flatten -- so
build the result in a single pre-sized allocation.

Benchmarks (added):

  BenchmarkAp        6 -> 1 allocs/op (-83%), 155 -> 66 ns/op
  BenchmarkFlatten   3 -> 1 allocs/op (-67%),  51 -> 24 ns/op

Signed-off-by: Nishant Mehta <nishantmehta.n@gmail.com>

* perf(array): use slices.Concat and slices.Grow for Flatten and Ap

Address review feedback by replacing the hand-rolled pre-sizing with the
idiomatic standard library helpers (Go 1.21+, compatible with the module's
1.24 requirement):

- Flatten delegates to slices.Concat, which sizes the result in a single
  allocation.
- MonadAp allocates its result once via slices.Grow, the same idiom
  slices.Concat uses internally.

Both return a nil slice for an empty result, which is a valid representation
of the empty array. The doc comments now state this, and the TestNilSlice_*
assertions are relaxed to check only that the result is empty.

Benchmarks are unchanged at a single allocation per call:

  BenchmarkAp        240 B/op, 1 allocs/op
  BenchmarkFlatten   128 B/op, 1 allocs/op

Signed-off-by: Nishant Mehta <nishantmehta.n@gmail.com>

---------

Signed-off-by: Nishant Mehta <nishantmehta.n@gmail.com>

Author: nishantmehta

v2/array/ap_bench_test.go

@@ -0,0 +1,38 @@
+// Copyright (c) 2023 - 2025 IBM Corp.
+// All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package array
+
+import (
+	"testing"
+)
+
+var apSink []int
+
+// BenchmarkAp exercises the array applicative (cartesian product of a slice of
+// functions over a slice of values).
+func BenchmarkAp(b *testing.B) {
+	fab := []func(int) int{
+		func(x int) int { return x + 1 },
+		func(x int) int { return x * 2 },
+		func(x int) int { return x - 1 },
+	}
+	fa := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		apSink = MonadAp[int, int](fab, fa)
+	}
+}

v2/array/array_nil_test.go

@@ -265,22 +265,22 @@ func TestNilSlice_MonadAp(t *testing.T) {
 	var nilFuncs []func(int) string
 	var nilValues []int
 
+	// nil is a valid representation of the empty array, so these cases only
+	// assert that an empty result is produced.
+
 	// nil functions, nil values
 	result1 := MonadAp(nilFuncs, nilValues)
-	assert.NotNil(t, result1, "MonadAp should return non-nil slice")
-	assert.Equal(t, 0, len(result1), "MonadAp should return empty slice for nil inputs")
+	assert.Empty(t, result1, "MonadAp should return an empty slice for nil inputs")
 
 	// nil functions, non-nil values
 	nonNilValues := []int{1, 2, 3}
 	result2 := MonadAp(nilFuncs, nonNilValues)
-	assert.NotNil(t, result2, "MonadAp should return non-nil slice")
-	assert.Equal(t, 0, len(result2), "MonadAp should return empty slice when functions are nil")
+	assert.Empty(t, result2, "MonadAp should return an empty slice when functions are nil")
 
 	// non-nil functions, nil values
 	nonNilFuncs := []func(int) string{func(v int) string { return fmt.Sprintf("%d", v) }}
 	result3 := MonadAp(nonNilFuncs, nilValues)
-	assert.NotNil(t, result3, "MonadAp should return non-nil slice")
-	assert.Equal(t, 0, len(result3), "MonadAp should return empty slice when values are nil")
+	assert.Empty(t, result3, "MonadAp should return an empty slice when values are nil")
 }
 
 // TestNilSlice_Ap verifies that Ap handles nil slices correctly
@@ -290,8 +290,8 @@ func TestNilSlice_Ap(t *testing.T) {
 
 	var nilFuncs []func(int) string
 	result := ap(nilFuncs)
-	assert.NotNil(t, result, "Ap should return non-nil slice")
-	assert.Equal(t, 0, len(result), "Ap should return empty slice for nil inputs")
+	// nil is a valid representation of the empty array.
+	assert.Empty(t, result, "Ap should return an empty slice for nil inputs")
 }
 
 // TestNilSlice_Head verifies that Head handles nil slices correctly
@@ -326,8 +326,9 @@ func TestNilSlice_Tail(t *testing.T) {
 func TestNilSlice_Flatten(t *testing.T) {
 	var nilSlice [][]int
 	result := Flatten(nilSlice)
-	assert.NotNil(t, result, "Flatten should return non-nil slice")
-	assert.Equal(t, 0, len(result), "Flatten should return empty slice for nil input")
+	// nil is a valid representation of the empty array, so only the emptiness
+	// of the result is asserted.
+	assert.Empty(t, result, "Flatten should return an empty slice for nil input")
 }
 
 // TestNilSlice_Lookup verifies that Lookup handles nil slices correctly

v2/array/flatten_bench_test.go

@@ -0,0 +1,38 @@
+// Copyright (c) 2023 - 2025 IBM Corp.
+// All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package array
+
+import (
+	"testing"
+)
+
+var flattenSink []int
+
+// BenchmarkFlatten exercises flattening a slice of slices into one slice.
+func BenchmarkFlatten(b *testing.B) {
+	mma := [][]int{
+		{1, 2, 3},
+		{4, 5, 6, 7},
+		{8, 9},
+		{10, 11, 12, 13, 14},
+		{15},
+	}
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		flattenSink = Flatten(mma)
+	}
+}

v2/array/generic/array.go

@@ -16,6 +16,8 @@
 package generic
 
 import (
+	"slices"
+
 	F "github.com/IBM/fp-go/v2/function"
 	"github.com/IBM/fp-go/v2/internal/array"
 	FC "github.com/IBM/fp-go/v2/internal/functor"
@@ -222,8 +224,12 @@ func ChainOptionK[GA ~[]A, GB ~[]B, A, B any](f func(a A) O.Option[GB]) func(GA)
 	)
 }
 
+// Flatten concatenates the inner slices into a single slice. It uses the
+// idiomatic [slices.Concat], which sizes the result in one allocation instead
+// of growing it via append. For an empty or nil input a nil slice is returned,
+// which is a valid representation of the empty array.
 func Flatten[GAA ~[]GA, GA ~[]A, A any](mma GAA) GA {
-	return MonadChain(mma, F.Identity[GA])
+	return slices.Concat(mma...)
 }
 
 func FilterMap[GA ~[]A, GB ~[]B, A, B any](f func(A) O.Option[B]) func(GA) GB {
@@ -263,8 +269,20 @@ func Chain[AS ~[]A, BS ~[]B, A, B any](f func(A) BS) func(AS) BS {
 	return F.Bind2nd(MonadChain[AS, BS, A, B], f)
 }
 
+// MonadAp computes the applicative product: f(a) for each f in fab and each a
+// in fa. Its length is known up front (len(fab)*len(fa)), so the result is
+// allocated once via [slices.Grow] - the same idiom used by [slices.Concat] -
+// instead of reallocating as it grows. For an empty result a nil slice is
+// returned, which is a valid representation of the empty array.
 func MonadAp[BS ~[]B, ABS ~[]func(A) B, AS ~[]A, B, A any](fab ABS, fa AS) BS {
-	return MonadChain(fab, F.Bind1st(MonadMap[AS, BS, A, B], fa))
+	var result BS
+	result = slices.Grow(result, len(fab)*len(fa))
+	for _, f := range fab {
+		for _, a := range fa {
+			result = append(result, f(a))
+		}
+	}
+	return result
 }
 
 func Ap[BS ~[]B, ABS ~[]func(A) B, AS ~[]A, B, A any](fa AS) func(ABS) BS {