Go Slices

External

• https://go.dev/ref/spec#Slice_types
• https://go.dev/blog/slices
• https://go.dev/wiki/SliceTricks

Internal

• Go Language
• Go Arrays
• Package slices

Overview

A slice is a descriptor, or a header that defines a contiguous segment of an underlying array, stored separately from the slice variable. A slice is not an array, a slice describes a piece of an array, and it is the idiomatic Go way of manipulating sequential, indexed data. Given that declaring a slice will create the backing array if no array is explicitly provided, you can almost always use a slice instead of an array. The slice provides access to a numbered sequence of elements from that array. A slice type denotes the set of all slices of arrays of its element type.

A slice contains a pointer to the underlying array, a length and a capacity. More details are available in the Structure section. A slice, once initialized, is always associated with the underlying array that holds its elements. The slice shares storage with its array, and other slices of the same array. A distinct slice that shares the underlying array with an original slice can be created by slicing the original slice with a slice expression.

Once the slice is initialized and the association with the underlying array is established, the association never changes, and the underlying array never changes, it cannot be grown or shrunk. However, a slice can be grown beyond the limits imposed by the original array, by allocating a new array under the covers, creating a new slice, copying elements across and using the second slice as the first slice. For more details, see append() below.

Slices are passed by value, like an other Go variable, but when that happens, the slice argument of a function and the internal variable copy of the slice still share the underlying array.

The Go documentation used to refer to slices as reference types, but not anymore. The "reference type" terminology was removed from Go documentation. The slices are sometimes referred to as dynamic arrays.

Structure

Under the covers, a slice is a data structure that contains a pointer, the length of the slice and the capacity of the slice. These elements are referred to as contents, fields or components of the slice. You can think of it as being built like this:

type sliceHeader struct {
    fistElement *T // pointer to the underlying array element that is the first element of the slice
    length      int
    capacity    int
}

Pointer

The pointer field contains a pointer to the underlying array element that represents the first element of the slice. The slice indexing is zero-based, so technically this would be slice element with the index 0.

Length

A slice's length represents the number of elements in the slice. The length of a slice is reported by the len() built-in function.

If a slice declares that it has length 3, that means it has three elements accessible as s[0], s[1] and s[2]. Any attempt to access an element with an index lower than 0 or higher then 2 (len - 1), for read or write, results in a panic, even if the slice has sufficient capacity:

panic: runtime error: index out of range [3] with length 3

"Length" and "size" can be used interchangeably.

Changing the Length. Do we ever change the length of a slide, or simply we create another slide, which points to the same underlying array, with a different length? For example, reslicing seems to always create a new slice. append() updates (possibly) the copy of the slice passed as argument and returns that copy, so the original argument is never changed. It probably does not make sense to talk about changing the length of the slice. We're working with disposable copies, so it does not help to think about changing the size "in-place".

Capacity

The capacity is the maximum value the length can reach, and reflects how much space the underlying array actually has. The capacity is equal to the length of the underlying array, minus the index in the array of the first element of the slice. The capacity of a slice is reported by the cap() built-in function.

Note that once an array is instantiated, it cannot change its size.

Trying to grow a slice beyond its capacity will step beyond the limits of the array and will trigger a panic.

Slices and Pass-by-Value

Go uses pass-by-value, so when a slice argument is passed to a function, the internal fields are copied across on the function stack, including the pointer to the underlying array. Therefore, the underlying array data structure is intrinsically shared, even in case of pass-by-value. Both the original slice header and the copy of the header passed to the function describe the same array. If the function changes the underlying array via its copy of the slice, the modified elements can be seen outside the function through the original slice variable.

However, if the function modifies the elements of the slice, like the length, or the pointer to the array element, those changes naturally do not propagate outside of the function. Only the changes to the underlying array do.

The slice variables are small, so their content can be copied fast. The fact that they include a pointer to the underlying array prevents copying the array, which has important performance implications, especially if the underlying array is large.

Note that slices are not reference variables, as Go does not support reference variables, so no two different slice variables may point to the same slice instance.

Pointers to Slices

It is idiomatic to use a pointer receiver for a method that modifies a slice.

nil and Empty Slice

nil Slice

A nil slice is a non-nil slice handle that has both the length and the capacity equal with zero, and the pointer to the first slice element, stored in the underlying array, equal to nil (so there is no underlying array).

A nil slice can be obtained with the new() built-in function.

A slice can be tested that it is nil with:

s == nil

which will return true.

Declaration and Initialization

Initialization with make()

make() allocates a new underlying array, and creates a new slice header to describe it, all at once. There are two forms, one that specifies the length and the capacity of the slice, on a simpler one, that specifies the length, with the implication that the underlying array will be created to accommodate the required length, and not more. In other words, the length will be equal with the capacity.

The elements of the slice are initialized with the zero value for the slice type.

// Create a slice with length 3 and capacity 5.
// All elements are initialized with the zero value for the slice type.
ii := make([]int, 3, 5)

// Create a slice with length equal to its capacity.
// All elements are initialized with the zero value for the slice type.
ii := make([]int, 3)

Initialization by Slicing the Underlying Array

Given an array variable, a slice of it can be declared by using the slice expression.

var aa [100]int // zero-value array declaration
var ss = aa[10:20] // slice declaration with slice expression

Operators

Indexing Operator []

Negative indexes are not supported, attempting to access a slice with a negative index generates a runtime panic.

Slice Expressions

Slice Expressions

Slice Functions

len()

Reports the slice length.

cap()

Reports the slice capacity.

copy()

copy() accepts two arguments, both slices. It copies the data from the right-hand argument into the left-hand argument. While copying, it pays attention the the length of both arguments, and it only copies what it can without panicking, which is the minimum of the lengths of those two slices.

src := []int{10, 20, 30, 40, 50}
dest := make([]int, 3)
copy(dest, src) // no panic, only the first three elements will be copied across

copy() can be used to copy elements around within the same slice, even if the ranges overlap. It can be used for shifting sections of the slice left or right:

s := make([]int, 5, 10)
for i := 0; i < 5; i++ {
	s[i] = i + 1
}
// s is [1 2 3 4 5]

// shift elements starting with 2 right one position
copy(s[3:], s[2:])
// s is [1 2 3 3 4]

append()

The append() built-in function appends elements to the end of a slice. If it has sufficient capacity, the destination just updates its length to accommodate the new elements. If it does not, a new underlying array is allocated. Append returns the updated slice. Since the argument of the append() function is passed by value, the changes occur on a copy of the original slice, so to make the original slice reflect the changes, it is necessary to store the result of the append(), often in the variable holding the original slice itself, with this idiomatic pattern:

ii := []int{1, 2}
ii = append(ii, 3)

In fact, the compiler won't let you call append without saving the result.

Appending an Entire Slice

To append a slice of the same type, use this syntax:

ii := []int{1, 2}
ii2 := []int{3, 4} 
ii = append(ii, ii2...)

Appending an String to a Byte Slice

As a special case, it is legal to append a string to a byte slice (notice the ellipsis):

s := []byte("hello ")
s = append(s, "world"...)

make()

See Initialization with make() above.

new()

new() will initialize a nil Slice, but it will return the pointer to the slice, instead of the value.

The slices Package

The slices Package

Iterating over a Slice

Iterating over a nil Slice

range applied to a nil slice does not panic and iterates zero times.

TODEPLETE

Go Slices TODPLETE

Deplete https://go.dev/wiki/SliceTricks into this page.