Golang slices: Equal should call out handling of nil

Go version

go1.22.0

What did you do?

Read the docs for slices.Equal

What did you see happen?

Saw:

Equal reports whether two slices are equal: the same length and all elements equal. If the lengths are different, Equal returns false. Otherwise, the elements are compared in increasing index order, and the comparison stops at the first unequal pair. Floating point NaNs are not considered equal.

What did you expect to see?

Something like:

Nil and empty slices are considered equal.

Nilness of slices is a more common occurance than NaNs, yet NaNs get called out, but nilness does not. In both cases, the current behavior is implicit with the previous prose, but it's helpful to call out edge cases.

Comment From: gabyhelp

Related Issues and Documentation

• [Package slices > func Equal ¶

      ](https://go.dev/pkg/slices/?m=old#Equal) <!-- score=0.87194 -->
  

  • Nil/empty slice discrepancy with bytes.Equal and reflect.DeepEqual #4027 (closed)
  • proposal: Go 2: define slice equality #23725 (closed)
  • [Package slices > func EqualFunc ¶

    ](https://go.dev/pkg/slices/?m=old#EqualFunc) <!-- score=0.82283 -->
    

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

Comment From: ianlancetaylor

The doc does explain how nil slices are handled, because it says exactly what the function does. But we can add another sentence if you like.

Comment From: dsnet

I agree the current wording is correct, but my point is that a little more information (even if strictly redundant) is helpful. After all, we called out the behavior of NaNs, which is technically covered by "all elements equal".

Comment From: apparentlymart

FWIW, when I read the current text my immediate thought was: that sure sounds like it's implying that empty and nil are treated as equal, but since it doesn't say so explicitly I will read the implementation to check.

I think mentioning it explicitly (rather than just implying it) would be worthwhile given that other parts of the language, and also various third-party libraries, are not consistent in how they handle this difference.

Comment From: gopherbot

Change https://go.dev/cl/599816 mentions this issue: slices: explicitly document nil and empty slice equality