slices: unclear documentations #60142
Description
Dissimilar to the corresponding data structures in other languages such as vector in C++ or ArrayList in Java, a Go slice does not own the data it contains but is a mere mutable view over a backing array. As a result, slices can share a common backing array and changes made to the data through one can be observable by the others. This requires operations mutating the data of a slice expressing their behaviour clearly and covering all cases, which seems to be absent from the slices package.
Suggestions:
// Insert inserts the values v... into s at index i,
// returning the modified slice.
// The elements at s[i:] are shifted up to make room.
// In the returned slice r, r[i] == v[0],
// and r[i+len(v)] == value originally at r[i].
+ // Insert operates as if it reads all data from s and v before doing
+ // any modification.
+ // Insert creates a new backing array and leaves
+ // the existing ones unchanged if len(s) + len(v) > cap(s)
+ // Otherwise, it modifies the backing array of s and the
+ // returned slice has the same backing array as s
// Insert panics if i is out of range.
// This function is O(len(s) + len(v)).
func Insert[S ~[]E, E any](s S, i int, v ...E) S
// Delete removes the elements s[i:j] from s, returning the modified slice.
// Delete panics if s[i:j] is not a valid slice of s.
- // Delete modifies the contents of the slice s; it does not create a new slice.
+ // Delete modifies the contents of the backing array of s, it does not create
+ // a new backing array, the returned slice has the same backing array as s.
+ // Delete operates as if it reads all data from s before doing any modification.
// Delete is O(len(s)-j), so if many items must be deleted, it is better to
// make a single call deleting them all together than to delete one at a time.
- // Delete might not modify the elements s[len(s)-(j-i):len(s)]. If those
+ // Delete does not modify the elements s[len(s)-(j-i):len(s)]. If those
// elements contain pointers you might consider zeroing those elements so that
// objects they reference can be garbage collected.
func Delete[S ~[]E, E any](s S, i, j int) S
// DeleteFunc removes any elements from s for which del returns true,
// returning the modified slice.
- // DeleteFunc modifies the contents of the slice s;
- // it does not create a new slice.
- // When DeleteFunc removes m elements, it might not modify the elements
+ // DeleteFunc operates as if it reads all data from s before doing any modification
+ // DeleteFunc modifies the contents of the backing array of s, it does not create
+ // a new backing array, the returned slice has the same backing array as s.
+ // When DeleteFunc removes m elements, it does not modify the elements
// s[len(s)-m:len(s)]. If those elements contain pointers you might consider
// zeroing those elements so that objects they reference can be garbage
// collected.
func DeleteFunc[S ~[]E, E any](s S, del func(E) bool) S
// Replace replaces the elements s[i:j] by the given v, and returns the
- // modified slice. Replace panics if s[i:j] is not a valid slice of s.
+ // Replace operates as if it reads all data from s and v before doing
+ // any modification.
+ // Replace creates a new backing array and leaves the existing ones
+ // unchanged if len(s) - (j-i) + len(v) > cap(s),
+ // Otherwise, it modifies the backing array of s and the
+ // returned slice has the same backing array as s.
+ // Replace panics if s[i:j] is not a valid slice of s.
func Replace[S ~[]E, E any](s S, i, j int, v ...E) S
- // Clone returns a copy of the slice.
+ // Clone returns a new slice with the same elements as those of s
+ // with a newly created backing array.
// The elements are copied using assignment, so this is a shallow clone.
func Clone[S ~[]E, E any](s S) S
// Compact replaces consecutive runs of equal elements with a single copy.
// This is like the uniq command found on Unix.
- // Compact modifies the contents of the slice s; it does not create a new slice.
- // When Compact discards m elements in total, it might not modify the elements
+ // Compact operates as if it reads all data from s and v before doing
+ // any modification.
+ // Compact modifies the contents of the backing array of s, it does not create a
+ // new backing array, the returned slice has the same backing array as s.
+ // When Compact discards m elements in total, it does not modify the elements
// s[len(s)-m:len(s)]. If those elements contain pointers you might consider
// zeroing those elements so that objects they reference can be garbage collected.
func Compact[S ~[]E, E comparable](s S) S
// Grow increases the slice's capacity, if necessary, to guarantee space for
// another n elements. After Grow(n), at least n elements can be appended
- // to the slice without another allocation. If n is negative or too large to
- // allocate the memory, Grow panics.
+ // Grows creates a new backing array if len(s) + n > cap(s), in which case
+ // the returned slice has a different backing array from s.
+ // Otherwise, Grows returns s unchanged.
+ // If n is negative or too large to allocate the memory, Grow panics.
func Grow[S ~[]E, E any](s S, n int) S
// Clip removes unused capacity from the slice, returning s[:len(s):len(s)].
+ // Clip does not modify the backing array of s.
func Clip[S ~[]E, E any](s S) S