proposal: reflect: add reflect.Value.Elems for slices, arrays, and strings

[mvdan]

Background

#66056 gave us iterator APIs on reflect.Value, which are great. I went ahead and started using them in our code, which led to simpler code.

What I didn't notice at the time is that I actually added a number of allocations per iteration: https://review.gerrithub.io/c/cue-lang/cue/+/1226673

Below is a set of benchmarks which shows this problem:

package p

import (
	"reflect"
	"testing"
)

var slice = []string{"a", "b", "c", "d", "e", "f", "g"}

func foreachSlice(i int, elem reflect.Value) {
	// we need an integer index here
}

func BenchmarkSliceValueIndex(b *testing.B) {
	for b.Loop() {
		val := reflect.ValueOf(slice)
		for i := range val.Len() {
			elem := val.Index(i)
			foreachSlice(i, elem)
		}
	}
}

func BenchmarkSliceValueSeq2WithIndex(b *testing.B) {
	for b.Loop() {
		val := reflect.ValueOf(slice)
		i := 0
		for _, elem := range val.Seq2() {
			foreachSlice(i, elem)
			i++
		}
	}
}

func BenchmarkSliceValueSeq2(b *testing.B) {
	for b.Loop() {
		val := reflect.ValueOf(slice)
		for ival, elem := range val.Seq2() {
			i := int(ival.Int())
			foreachSlice(i, elem)
		}
	}
}

As of go version go1.26-devel_d55ecea9e5 2025-11-14 15:13:00 -0800 linux/amd64, I see:

goos: linux
goarch: amd64
pkg: test
cpu: AMD Ryzen AI 9 HX 370 w/ Radeon 890M           
BenchmarkSliceValueIndex-24            	66029337	        18.00 ns/op	       0 B/op	       0 allocs/op
BenchmarkSliceValueSeq2WithIndex-24    	13339879	        86.85 ns/op	     104 B/op	       5 allocs/op
BenchmarkSliceValueSeq2-24             	14808429	        76.92 ns/op	      88 B/op	       5 allocs/op

In other words, the classic integer iteration doesn't allocate and is pretty fast, but both of the two reasonable ways to use Seq2 to iterate over the slice values seem to allocate and are significantly slower.

I also cannot use Seq here, as it iterates over the slice indices, not the elements, much like for i := range slice {...}.

When dealing with reflect.Slice, but also similar "indexed sequence" containers like reflect.Array, and reflect.String, it's common to want to iterate over their elements via iter.Seq2[int, Value], much like for i, v := range slice {...} gives you (int, T). Seq2 is fine, but its iter.Seq2[Value, Value] seems most appropriate for cases where the key can be of any type, such as a map or an iterator func.

Proposal

I propose that we add this new API:

// Elems returns an iter.Seq2[int, Value] that loops over the elements of v.
// v's kind must be Array, Slice, or String
func (v Value) Elems() iter.Seq2[int, Value]

The advantages of this API are two-fold:

1. Performance; see above how trying to use Seq2 is slower and allocates more.
2. Usability; the code sample below is shorter and simpler than the three existing ones above. Or one could even imagine that foreachSlice could take the iter.Seq2[int, reflect.Value] directly, as no wrapping is necessary anymore.

func BenchmarkSliceValueSeq2(b *testing.B) {
	for b.Loop() {
		val := reflect.ValueOf(slice)
		for i, elem := range val.Elems() {
			foreachSlice(i, elem)
		}
	}
}

Alternatives

If we improved reflect.Value.Seq2 such that the original benchmarks were all roughly equivalent, then point 1 (performance) would be largely moot. I'm not sure if that is possible. However, I'd argue that point 2 (usability) is still valid; I don't find any of the existing three approaches particularly nice.

[gabyhelp]

Related Issues

• reflect: add Type.CanSeq/CanSeq2 and Value.Seq/Seq2 methods #66056 (closed)
• reflect: Add Type.Fields() iter.Seq[StructField] and Type.Methods() iter.Seq[Method] #66631
• reflect: add a range like interface for Value #11104 (closed)
• proposal: slices: add CollectKeys and CollectValues to collect from an iter.Seq2 #69706 (closed)
• proposal: reflect: add direct MapIter accessors #66125 (closed)
• proposal: slices: add AllPointer #69345 (closed)
• proposal: slices, maps: add Pointer iteration functions #69916 (closed)
• proposal: slices: MutableValues iterator #70813
• reflect package Array/SliceValues should provide access to PtrValues of elements #1031 (closed)
• proposal: iter: Enumerate, Keys and Values functions #68887 (closed)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[mvdan]

Tangentially, the allocations in the second and third original benchmarks are a little suspect.

• The use of an iterator seems to make val escape to the heap, presumably because it is captured by the iterator callback function. This seems like an area where the compiler could do a better job.
• For the same reason, it looks like the i variable in the second benchmark escapes to the heap.
• It seems like reflect.Value.Seq2 itself also allocates in both cases, which it doesn't need to.

[jub0bs]

@mvdan

• The use of an iterator seems to make val escape to the heap, presumably because it is captured by the iterator callback function. This seems like an area where the compiler could do a better job.

Relevant (I think): #73524 (comment)

[earthboundkid]

In #66056 (comment), I said yielding the index to a slice was "logical but unhelpful." Elems() seems like a more useful API.

[earthboundkid]

For strings, does it yield runes and skip clusters? E.g.

for i, c := range "Hello, 世界" {
	fmt.Println(i, string(c))
}

0 H
1 e
2 l
3 l
4 o
5 ,
6  
7 世
10 界

[mvdan]

@jub0bs I haven't thought hard about exactly why the allocations currently happen, I'm only observing that from the user's PoV, none of the original three benchmarks really need to allocate - there is no pointer that escapes the benchmark loop body. If this proposal is accepted, I don't care too much if they do, but it's still puzzling. I guess that's what #73524 is tracking.

@earthboundkid For strings, it would yield the same element values that Seq2 currently does. I actually only need this API to handle slices and arrays, but for the sake of the "range values" table at https://go.dev/ref/spec#For_range, strings also use an int index as the first value. And I think including strings keeps the reflect API more consistent.

[mvdan]

I should also mention that I don't feel strongly about the name. If we want to avoid confusion with Seq, which is documented as "loops over the elements of v", then perhaps we could choose a name like IndexedElems, IndexElems, or IndexedSeq, to clarify that this is for sequence types where a range operation would use an (int, T) pair.