.GO File Format – Built-ins

Summary

“Statement” says whether the call may be used on its own as an expression statement. Where an argument is of type parameter type, each function requires the operation to be valid for every type in the type set.

append

append(s S, x ...E) S  // E is the element type of S

Appends zero or more values to a slice and returns the resulting slice, of the same type. If the capacity is not enough, append allocates a new, large enough array, so the result may not share storage with the argument. As a special case it also accepts a slice assignable to []byte with a string argument followed by ..., which appends the bytes of the string. The result does not depend on whether the arguments overlap.

s0 := []int{0, 0}
s1 := append(s0, 2)              // s1 is []int{0, 0, 2}
s2 := append(s1, 3, 5, 7)        // s2 is []int{0, 0, 2, 3, 5, 7}
s3 := append(s2, s0...)          // s3 is []int{0, 0, 2, 3, 5, 7, 0, 0}

var b []byte
b = append(b, "bar"...)          // b is []byte{'b', 'a', 'r'}

copy

copy(dst, src []T) int
copy(dst []byte, src string) int

Copies slice elements from source to destination and returns the number copied, which is the minimum of the two lengths. Both arguments must have identical element types. A string source is allowed with a []byte destination. Overlapping memory is handled correctly.

clear

Takes a map, slice or type parameter (Go 1.21). For a map it deletes all entries, leaving len(m) == 0. For a slice it sets every element up to the length to the zero value. With a nil map or slice it does nothing.

close

Records that no more values will be sent on a channel. Sending to or closing a closed channel panics, and so does closing a nil channel. Using it on a receive-only channel is an error. See Concurrency.

complex, real, imag

complex(realPart, imaginaryPart floatT) complexT
real(complexT) floatT
imag(complexT) floatT

complex builds a complex value from two floats of the same type: complex64 from float32, and complex128 from float64. real and imag extract the parts. Arguments of type parameter type are not permitted. If all operands are constants, the result is a constant, untyped when the operands are untyped.

delete

delete(m, k)  // remove element m[k] from map m

k must be assignable to the key type. If the map is nil or has no such element, delete does nothing.

len and cap

• The result has type int. At any time 0 <= len(s) <= cap(s). A nil slice, map or channel has length 0; a nil slice or channel has capacity 0.
• len(s) is constant if s is a string constant. len(s) and cap(s) are constant if s is an array or pointer to array and contains no channel receives or non-constant function calls; then s is not evaluated.

make

Returns a value of type T, not *T. Size arguments must be of integer type, have a type set containing only integer types, or be untyped constants; a constant must be non-negative and representable by int. For slices and channels, a negative n, or n larger than m, panics at run time.

min and max

Compute the smallest or largest of a fixed number of arguments of ordered types (Go 1.21). There must be at least one, and slices cannot be spread with .... The type rules are those of x + y. If all arguments are constant, the result is constant.

With strings, the result is the first argument with the smallest (or largest) value, compared lexically byte-wise.

new

new creates a new, initialised variable and returns a pointer to it. Its single argument is a type or, since Go 1.26, an expression (spec: Allocation).

• new(T) allocates a variable of type T set to its zero value.
• new(x) allocates a variable of the type of x, set to the value of x. An untyped constant takes its default type first. nil cannot be the argument.

p := new(int)   // *int pointing to 0
q := new(123)   // *int pointing to 123 (Go 1.26)

type Person struct {
	Age *int
}
_ = Person{Age: new(yearsSince(born))} // pointer to an optional value (Go 1.26)

panic and recover

Described on the Functions and methods page.

print and println

Implementations provide these for bootstrapping. They are documented for completeness and are not guaranteed to stay in the language. They write to the standard error stream in the gc toolchain. Programs should use fmt.

Package unsafe

The built-in package unsafe provides low-level operations that violate the type system (spec: Package unsafe). A package that uses it must be vetted manually for type safety and may not be portable.

package unsafe

type ArbitraryType int  // shorthand for an arbitrary Go type; it is not a real type
type Pointer *ArbitraryType

func Alignof(variable ArbitraryType) uintptr
func Offsetof(selector ArbitraryType) uintptr
func Sizeof(variable ArbitraryType) uintptr

type IntegerType int  // shorthand for an integer type; it is not a real type
func Add(ptr Pointer, len IntegerType) Pointer
func Slice(ptr *ArbitraryType, len IntegerType) []ArbitraryType
func SliceData(slice []ArbitraryType) *ArbitraryType
func String(ptr *byte, len IntegerType) string
func StringData(str string) *byte

Alignof, Offsetof and Sizeof are compile-time constants of type uintptr when their arguments have constant size. Bytes passed to String, or returned by StringData, must not be modified.