Source file src/builtin/builtin.go

     1  // Copyright 2011 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  /*
     6  Package builtin provides documentation for Go's predeclared identifiers.
     7  The items documented here are not actually in package builtin
     8  but their descriptions here allow godoc to present documentation
     9  for the language's special identifiers.
    10  */
    11  package builtin
    12  
    13  import "cmp"
    14  
    15  // bool is the set of boolean values, true and false.
    16  type bool bool
    17  
    18  // true and false are the two untyped boolean values.
    19  const (
    20  	true  = 0 == 0 // Untyped bool.
    21  	false = 0 != 0 // Untyped bool.
    22  )
    23  
    24  // uint8 is the set of all unsigned 8-bit integers.
    25  // Range: 0 through 255.
    26  type uint8 uint8
    27  
    28  // uint16 is the set of all unsigned 16-bit integers.
    29  // Range: 0 through 65535.
    30  type uint16 uint16
    31  
    32  // uint32 is the set of all unsigned 32-bit integers.
    33  // Range: 0 through 4294967295.
    34  type uint32 uint32
    35  
    36  // uint64 is the set of all unsigned 64-bit integers.
    37  // Range: 0 through 18446744073709551615.
    38  type uint64 uint64
    39  
    40  // int8 is the set of all signed 8-bit integers.
    41  // Range: -128 through 127.
    42  type int8 int8
    43  
    44  // int16 is the set of all signed 16-bit integers.
    45  // Range: -32768 through 32767.
    46  type int16 int16
    47  
    48  // int32 is the set of all signed 32-bit integers.
    49  // Range: -2147483648 through 2147483647.
    50  type int32 int32
    51  
    52  // int64 is the set of all signed 64-bit integers.
    53  // Range: -9223372036854775808 through 9223372036854775807.
    54  type int64 int64
    55  
    56  // float32 is the set of all IEEE-754 32-bit floating-point numbers.
    57  type float32 float32
    58  
    59  // float64 is the set of all IEEE-754 64-bit floating-point numbers.
    60  type float64 float64
    61  
    62  // complex64 is the set of all complex numbers with float32 real and
    63  // imaginary parts.
    64  type complex64 complex64
    65  
    66  // complex128 is the set of all complex numbers with float64 real and
    67  // imaginary parts.
    68  type complex128 complex128
    69  
    70  // string is the set of all strings of 8-bit bytes, conventionally but not
    71  // necessarily representing UTF-8-encoded text. A string may be empty, but
    72  // not nil. Values of string type are immutable.
    73  type string string
    74  
    75  // int is a signed integer type that is at least 32 bits in size. It is a
    76  // distinct type, however, and not an alias for, say, int32.
    77  type int int
    78  
    79  // uint is an unsigned integer type that is at least 32 bits in size. It is a
    80  // distinct type, however, and not an alias for, say, uint32.
    81  type uint uint
    82  
    83  // uintptr is an integer type that is large enough to hold the bit pattern of
    84  // any pointer.
    85  type uintptr uintptr
    86  
    87  // byte is an alias for uint8 and is equivalent to uint8 in all ways. It is
    88  // used, by convention, to distinguish byte values from 8-bit unsigned
    89  // integer values.
    90  type byte = uint8
    91  
    92  // rune is an alias for int32 and is equivalent to int32 in all ways. It is
    93  // used, by convention, to distinguish character values from integer values.
    94  type rune = int32
    95  
    96  // any is an alias for interface{} and is equivalent to interface{} in all ways.
    97  type any = interface{}
    98  
    99  // comparable is an interface that is implemented by all comparable types
   100  // (booleans, numbers, strings, pointers, channels, arrays of comparable types,
   101  // structs whose fields are all comparable types).
   102  // The comparable interface may only be used as a type parameter constraint,
   103  // not as the type of a variable.
   104  type comparable interface{ comparable }
   105  
   106  // iota is a predeclared identifier representing the untyped integer ordinal
   107  // number of the current const specification in a (usually parenthesized)
   108  // const declaration. It is zero-indexed.
   109  const iota = 0 // Untyped int.
   110  
   111  // nil is a predeclared identifier representing the zero value for a
   112  // pointer, channel, func, interface, map, or slice type.
   113  var nil Type // Type must be a pointer, channel, func, interface, map, or slice type
   114  
   115  // Type is here for the purposes of documentation only. It is a stand-in
   116  // for any Go type, but represents the same type for any given function
   117  // invocation.
   118  type Type int
   119  
   120  // Type1 is here for the purposes of documentation only. It is a stand-in
   121  // for any Go type, but represents the same type for any given function
   122  // invocation.
   123  type Type1 int
   124  
   125  // IntegerType is here for the purposes of documentation only. It is a stand-in
   126  // for any integer type: int, uint, int8 etc.
   127  type IntegerType int
   128  
   129  // FloatType is here for the purposes of documentation only. It is a stand-in
   130  // for either float type: float32 or float64.
   131  type FloatType float32
   132  
   133  // ComplexType is here for the purposes of documentation only. It is a
   134  // stand-in for either complex type: complex64 or complex128.
   135  type ComplexType complex64
   136  
   137  // The append built-in function appends elements to the end of a slice. If
   138  // it has sufficient capacity, the destination is resliced to accommodate the
   139  // new elements. If it does not, a new underlying array will be allocated.
   140  // Append returns the updated slice. It is therefore necessary to store the
   141  // result of append, often in the variable holding the slice itself:
   142  //
   143  //	slice = append(slice, elem1, elem2)
   144  //	slice = append(slice, anotherSlice...)
   145  //
   146  // As a special case, it is legal to append a string to a byte slice, like this:
   147  //
   148  //	slice = append([]byte("hello "), "world"...)
   149  func append(slice []Type, elems ...Type) []Type
   150  
   151  // The copy built-in function copies elements from a source slice into a
   152  // destination slice. (As a special case, it also will copy bytes from a
   153  // string to a slice of bytes.) The source and destination may overlap. Copy
   154  // returns the number of elements copied, which will be the minimum of
   155  // len(src) and len(dst).
   156  func copy(dst, src []Type) int
   157  
   158  // The delete built-in function deletes the element with the specified key
   159  // (m[key]) from the map. If m is nil or there is no such element, delete
   160  // is a no-op.
   161  func delete(m map[Type]Type1, key Type)
   162  
   163  // The len built-in function returns the length of v, according to its type:
   164  //
   165  //	Array: the number of elements in v.
   166  //	Pointer to array: the number of elements in *v (even if v is nil).
   167  //	Slice, or map: the number of elements in v; if v is nil, len(v) is zero.
   168  //	String: the number of bytes in v.
   169  //	Channel: the number of elements queued (unread) in the channel buffer;
   170  //	         if v is nil, len(v) is zero.
   171  //
   172  // For some arguments, such as a string literal or a simple array expression, the
   173  // result can be a constant. See the Go language specification's "Length and
   174  // capacity" section for details.
   175  func len(v Type) int
   176  
   177  // The cap built-in function returns the capacity of v, according to its type:
   178  //
   179  //	Array: the number of elements in v (same as len(v)).
   180  //	Pointer to array: the number of elements in *v (same as len(v)).
   181  //	Slice: the maximum length the slice can reach when resliced;
   182  //	if v is nil, cap(v) is zero.
   183  //	Channel: the channel buffer capacity, in units of elements;
   184  //	if v is nil, cap(v) is zero.
   185  //
   186  // For some arguments, such as a simple array expression, the result can be a
   187  // constant. See the Go language specification's "Length and capacity" section for
   188  // details.
   189  func cap(v Type) int
   190  
   191  // The make built-in function allocates and initializes an object of type
   192  // slice, map, or chan (only). Like new, the first argument is a type, not a
   193  // value. Unlike new, make's return type is the same as the type of its
   194  // argument, not a pointer to it. The specification of the result depends on
   195  // the type:
   196  //
   197  //	Slice: The size specifies the length. The capacity of the slice is
   198  //	equal to its length. A second integer argument may be provided to
   199  //	specify a different capacity; it must be no smaller than the
   200  //	length. For example, make([]int, 0, 10) allocates an underlying array
   201  //	of size 10 and returns a slice of length 0 and capacity 10 that is
   202  //	backed by this underlying array.
   203  //	Map: An empty map is allocated with enough space to hold the
   204  //	specified number of elements. The size may be omitted, in which case
   205  //	a small starting size is allocated.
   206  //	Channel: The channel's buffer is initialized with the specified
   207  //	buffer capacity. If zero, or the size is omitted, the channel is
   208  //	unbuffered.
   209  func make(t Type, size ...IntegerType) Type
   210  
   211  // The max built-in function returns the largest value of a fixed number of
   212  // arguments of [cmp.Ordered] types. There must be at least one argument.
   213  // If T is a floating-point type and any of the arguments are NaNs,
   214  // max will return NaN.
   215  func max[T cmp.Ordered](x T, y ...T) T
   216  
   217  // The min built-in function returns the smallest value of a fixed number of
   218  // arguments of [cmp.Ordered] types. There must be at least one argument.
   219  // If T is a floating-point type and any of the arguments are NaNs,
   220  // min will return NaN.
   221  func min[T cmp.Ordered](x T, y ...T) T
   222  
   223  // The new built-in function allocates memory. The first argument is a type,
   224  // not a value, and the value returned is a pointer to a newly
   225  // allocated zero value of that type.
   226  func new(Type) *Type
   227  
   228  // The complex built-in function constructs a complex value from two
   229  // floating-point values. The real and imaginary parts must be of the same
   230  // size, either float32 or float64 (or assignable to them), and the return
   231  // value will be the corresponding complex type (complex64 for float32,
   232  // complex128 for float64).
   233  func complex(r, i FloatType) ComplexType
   234  
   235  // The real built-in function returns the real part of the complex number c.
   236  // The return value will be floating point type corresponding to the type of c.
   237  func real(c ComplexType) FloatType
   238  
   239  // The imag built-in function returns the imaginary part of the complex
   240  // number c. The return value will be floating point type corresponding to
   241  // the type of c.
   242  func imag(c ComplexType) FloatType
   243  
   244  // The clear built-in function clears maps and slices.
   245  // For maps, clear deletes all entries, resulting in an empty map.
   246  // For slices, clear sets all elements up to the length of the slice
   247  // to the zero value of the respective element type. If the argument
   248  // type is a type parameter, the type parameter's type set must
   249  // contain only map or slice types, and clear performs the operation
   250  // implied by the type argument.
   251  func clear[T ~[]Type | ~map[Type]Type1](t T)
   252  
   253  // The close built-in function closes a channel, which must be either
   254  // bidirectional or send-only. It should be executed only by the sender,
   255  // never the receiver, and has the effect of shutting down the channel after
   256  // the last sent value is received. After the last value has been received
   257  // from a closed channel c, any receive from c will succeed without
   258  // blocking, returning the zero value for the channel element. The form
   259  //
   260  //	x, ok := <-c
   261  //
   262  // will also set ok to false for a closed and empty channel.
   263  func close(c chan<- Type)
   264  
   265  // The panic built-in function stops normal execution of the current
   266  // goroutine. When a function F calls panic, normal execution of F stops
   267  // immediately. Any functions whose execution was deferred by F are run in
   268  // the usual way, and then F returns to its caller. To the caller G, the
   269  // invocation of F then behaves like a call to panic, terminating G's
   270  // execution and running any deferred functions. This continues until all
   271  // functions in the executing goroutine have stopped, in reverse order. At
   272  // that point, the program is terminated with a non-zero exit code. This
   273  // termination sequence is called panicking and can be controlled by the
   274  // built-in function recover.
   275  //
   276  // Starting in Go 1.21, calling panic with a nil interface value or an
   277  // untyped nil causes a run-time error (a different panic).
   278  // The GODEBUG setting panicnil=1 disables the run-time error.
   279  func panic(v any)
   280  
   281  // The recover built-in function allows a program to manage behavior of a
   282  // panicking goroutine. Executing a call to recover inside a deferred
   283  // function (but not any function called by it) stops the panicking sequence
   284  // by restoring normal execution and retrieves the error value passed to the
   285  // call of panic. If recover is called outside the deferred function it will
   286  // not stop a panicking sequence. In this case, or when the goroutine is not
   287  // panicking, recover returns nil.
   288  //
   289  // Prior to Go 1.21, recover would also return nil if panic is called with
   290  // a nil argument. See [panic] for details.
   291  func recover() any
   292  
   293  // The print built-in function formats its arguments in an
   294  // implementation-specific way and writes the result to standard error.
   295  // Print is useful for bootstrapping and debugging; it is not guaranteed
   296  // to stay in the language.
   297  func print(args ...Type)
   298  
   299  // The println built-in function formats its arguments in an
   300  // implementation-specific way and writes the result to standard error.
   301  // Spaces are always added between arguments and a newline is appended.
   302  // Println is useful for bootstrapping and debugging; it is not guaranteed
   303  // to stay in the language.
   304  func println(args ...Type)
   305  
   306  // The error built-in interface type is the conventional interface for
   307  // representing an error condition, with the nil value representing no error.
   308  type error interface {
   309  	Error() string
   310  }
   311  

View as plain text