// Copyright 2011 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

/*
Package builtin provides documentation for Go's predeclared identifiers.
The items documented here are not actually in package builtin
but their descriptions here allow godoc to present documentation
for the language's special identifiers.
*/
/*
builtin包内置提供了Go预定义标识符的文档。
这里记录的项目实际上不是包内置的，但它们的描述允许godoc为语言的特殊标识符提供文档。
 */
package builtin

// bool is the set of boolean values, true and false.
// bool是bool值的集合，true和false
type bool bool

// true and false are the two untyped boolean values.
// true和false是2个非类型化的布尔值
const (
    true  = 0 == 0 // Untyped bool.
    false = 0 != 0 // Untyped bool.
)

// uint8 is the set of all unsigned 8-bit integers.
// Range: 0 through 255.
// uint8是所有无符号8位整数的集合
// 范围: 0~255
type uint8 uint8

// uint16 is the set of all unsigned 16-bit integers.
// Range: 0 through 65535.
// uint16是所有无符号16位整数的集合
// 范围: 0~65535
type uint16 uint16

// uint32 is the set of all unsigned 32-bit integers.
// Range: 0 through 4294967295.
// uint32是所有无符号32位整数的集合
// 范围: 0~4294967295
type uint32 uint32

// uint64 is the set of all unsigned 64-bit integers.
// Range: 0 through 18446744073709551615.
// uint64是所有无符号64位整数的集合
// 范围: 0~18446744073709551615
type uint64 uint64

// int8 is the set of all signed 8-bit integers.
// Range: -128 through 127.
// int8是所有有符号8位整数的集合
// 范围: -128~127
type int8 int8

// int16 is the set of all signed 16-bit integers.
// Range: -32768 through 32767.
// int16是所有有符号16位整数的集合
// 范围: -32768~32767
type int16 int16

// int32 is the set of all signed 32-bit integers.
// Range: -2147483648 through 2147483647.
// int32是所有有符号32位整数的集合
// 范围: -2147483648~2147483647
type int32 int32

// int64 is the set of all signed 64-bit integers.
// Range: -9223372036854775808 through 9223372036854775807.
// int64是所有有符号64位整数的集合
// 范围: -9223372036854775808~9223372036854775807
type int64 int64

// float32 is the set of all IEEE-754 32-bit floating-point numbers.
// float32是所有IEEE-754（IEEE二进位浮点数算术标准）32位浮点数的集合
type float32 float32

// float64 is the set of all IEEE-754 64-bit floating-point numbers.
// float64是所有IEEE-754（IEEE二进位浮点数算术标准）64位浮点数及集合
type float64 float64

// complex64 is the set of all complex numbers with float32 real and
// imaginary parts.
// complex64是具有float32实部和虚部的所有复数集合
type complex64 complex64

// complex128 is the set of all complex numbers with float64 real and
// imaginary parts.
// complex128是具有float64实部和虚部的所有复数集合
type complex128 complex128

// string is the set of all strings of 8-bit bytes, conventionally but not
// necessarily representing UTF-8-encoded text. A string may be empty, but
// not nil. Values of string type are immutable.
// 字符串是8位字节的所有字符串的集合，通常但不一定表示UTF-8文本。一个字符串可能是空的但不是nil。字符串类型的值是不可变的
type string string

// int is a signed integer type that is at least 32 bits in size. It is a
// distinct type, however, and not an alias for, say, int32.
// int是大小至少为32位的有符号整数类型。然而它是一种独特的类型，而不是int32的别名
type int int

// uint is an unsigned integer type that is at least 32 bits in size. It is a
// distinct type, however, and not an alias for, say, uint32.
// uint是大小至少为32位的无符号整型，然而它是一种独特的类型，而不是uint21的别名
type uint uint

// uintptr is an integer type that is large enough to hold the bit pattern of
// any pointer.
// uintptr是一种整数类型，其大小足以容纳任何指针的位模式
type uintptr uintptr

// byte is an alias for uint8 and is equivalent to uint8 in all ways. It is
// used, by convention, to distinguish byte values from 8-bit unsigned
// integer values.
// byte是uint8的别名，而且在所有方面都等同于uint8。按照惯例，用于区分字节值和8位无符号。
type byte = uint8

// rune is an alias for int32 and is equivalent to int32 in all ways. It is
// used, by convention, to distinguish character values from integer values.
// rune是int32的别名而且在所有方面等同于int32。按照惯例用于区分字符值和整数值。
type rune = int32

// any is an alias for interface{} and is equivalent to interface{} in all ways.
// any是interface{}的别名，所有方面等同于interface{}
type any = interface{}

// comparable is an interface that is implemented by all comparable types
// (booleans, numbers, strings, pointers, channels, arrays of comparable types,
// structs whose fields are all comparable types).
// The comparable interface may only be used as a type parameter constraint,
// not as the type of a variable.
// comparable是所有可比较类型实现的接口（布尔值、数字、字符串、指针、通道、可比较类型的数组、其字段都是可比较的类型的结构）。
// 可比较接口只能用作类型参数约束，而不能用作变量的类型
type comparable interface{ comparable }

// iota is a predeclared identifier representing the untyped integer ordinal
// number of the current const specification in a (usually parenthesized)
// const declaration. It is zero-indexed.
// iota是一个预先声明的标识符，表示（通常带括号）常量声明中当前常量规范的非类型的整数序号。它是零索引的。
const iota = 0 // Untyped int.

// nil is a predeclared identifier representing the zero value for a
// pointer, channel, func, interface, map, or slice type.
// nil是一个预先声明的标识符，表示指针、通道、函数、接口、映射或切片类型的零值。
var nil Type // Type must be a pointer, channel, func, interface, map, or slice type

// Type is here for the purposes of documentation only. It is a stand-in
// for any Go type, but represents the same type for any given function
// invocation.
// 此处的Type仅用于文档目的。它是任何Go类型的替代品，但表示任何给定函数调用的相同类型。
type Type int

// Type1 is here for the purposes of documentation only. It is a stand-in
// for any Go type, but represents the same type for any given function
// invocation.
// 此处的Type1仅仅用于文档目的。它是任何Go类型的替代品，但表示任何给定函数调用的相同类型。
type Type1 int

// IntegerType is here for the purposes of documentation only. It is a stand-in
// for any integer type: int, uint, int8 etc.
// 此处的IntegerType仅用于文档目的。它是任何整数类型的替代品：int、uint、int8等。
type IntegerType int

// FloatType is here for the purposes of documentation only. It is a stand-in
// for either float type: float32 or float64.
// 此处的IntegerType仅用于文档目的。它是float32或float64两种类型的替代品。
type FloatType float32

// ComplexType is here for the purposes of documentation only. It is a
// stand-in for either complex type: complex64 or complex128.
// 此处的ComplexType仅用于文档目的。它是复杂类型complex64或complex128的替代品。
type ComplexType complex64

// The append built-in function appends elements to the end of a slice. If
// it has sufficient capacity, the destination is resliced to accommodate the
// new elements. If it does not, a new underlying array will be allocated.
// Append returns the updated slice. It is therefore necessary to store the
// result of append, often in the variable holding the slice itself:
// append内置函数将元素追加到切片末尾。如果它有足够的容量，被允许重新分配新的元素。没有没有，将分配一个新的基础数组。
// append返回更新后的切片。因此，有必要将append的结果存储在保存切片本身的变量中。
//    slice = append(slice, elem1, elem2)
//    slice = append(slice, anotherSlice...)
//
// As a special case, it is legal to append a string to a byte slice, like this:
// 作为一种特殊情况，将字符串追加到字节切片是合法的，如下所示
//    slice = append([]byte("hello "), "world"...)
func append(slice []Type, elems ...Type) []Type

// The copy built-in function copies elements from a source slice into a
// destination slice. (As a special case, it also will copy bytes from a
// string to a slice of bytes.) The source and destination may overlap. Copy
// returns the number of elements copied, which will be the minimum of
// len(src) and len(dst).
// 内置copy函数将元素从源切片复制到目标切片。（作为一种特殊情况，它也会将字节从字符串复制到字节切片中）
// 源和目标可能会重叠。copy返回复制的元素数，它将是len(src)和len(dst)中的最小值
func copy(dst, src []Type) int

// The delete built-in function deletes the element with the specified key
// (m[key]) from the map. If m is nil or there is no such element, delete
// is a no-op.
// delete内置函数从映射中删除指定键(m[key])的元素。如果m是nil或者没有这样的元素，delte是不会操作的
func delete(m map[Type]Type1, key Type)

// The len built-in function returns the length of v, according to its type:
// len内置函数根据类型返回v的长度：
//    Array: the number of elements in v.
// 数组：v中元素的数量
//    Pointer to array: the number of elements in *v (even if v is nil).
// 指向数组的指针：*v中的元素数（即使v是nil）
//    Slice, or map: the number of elements in v; if v is nil, len(v) is zero.
// 切片或映射：v中元素的数量，如果v为nil，则len(v)等于0
//    String: the number of bytes in v.
// 字符串：v中的字节数
//    Channel: the number of elements queued (unread) in the channel buffer;
//             if v is nil, len(v) is zero.
// 通道：通道缓冲区中排队的（未读）元素数；如果v为nil，则len(v)等于0
// For some arguments, such as a string literal or a simple array expression, the
// result can be a constant. See the Go language specification's "Length and
// capacity" section for details.
// 对于某些参数，例如字符串文字或简单数组表达式,结果可以是常数。有关详细信息，请参阅Go语言规范的“长度和容量”部分。
func len(v Type) int

// The cap built-in function returns the capacity of v, according to its type:
// cap内置函数根据类型返回v的容量：
//    Array: the number of elements in v (same as len(v)).
//  数组：v中元素的数量（与len（v）相同）。
//    Pointer to array: the number of elements in *v (same as len(v)).
//  指向数组的指针：*v中的元素数（与len（v）相同）。
//    Slice: the maximum length the slice can reach when resliced;
//  切片：重新切片时切片可以达到的最大长度；
//    if v is nil, cap(v) is zero.
//  如果v是nil, cap(v)等于0
//    Channel: the channel buffer capacity, in units of elements;
//  通道：通道缓冲容量，在元素单元中；
//    if v is nil, cap(v) is zero.
//  如果v是nil, cap(v)等于0
// For some arguments, such as a simple array expression, the result can be a
// constant. See the Go language specification's "Length and capacity" section for
// details.
// 对于某些参数，例如字符串文字或简单数组表达式,结果可以是常数。有关详细信息，请参阅Go语言规范的“长度和容量”部分。
func cap(v Type) int

// The make built-in function allocates and initializes an object of type
// slice, map, or chan (only). Like new, the first argument is a type, not a
// value. Unlike new, make's return type is the same as the type of its
// argument, not a pointer to it. The specification of the result depends on
// the type:
//  make内置函数分配并初始化slice、map或chan（仅限）类型的对象。与new一样，第一个参数是类型，而不是值。与new不同，make的返回类型与其参数的类型相同，而不是指向它的指针。结果的规格取决于类型：
//    Slice: The size specifies the length. The capacity of the slice is
//    equal to its length. A second integer argument may be provided to
//    specify a different capacity; it must be no smaller than the
//    length. For example, make([]int, 0, 10) allocates an underlying array
//    of size 10 and returns a slice of length 0 and capacity 10 that is
//    backed by this underlying array.
//  切片：大小指定长度。切片的容量等于其长度。可以提供第二整数参数以指定不同的容量；它必须不小于长度。例如，make（[]int，0，10）分配大小为10的基础数组，并返回长度为0、容量为10的切片，该切片由该基础数组支持。
//    Map: An empty map is allocated with enough space to hold the
//    specified number of elements. The size may be omitted, in which case
//    a small starting size is allocated.
//  映射：为空映射分配足够的空间以容纳指定数量的元素。可以省略该大小，在这种情况下，分配较小的起始大小。
//    Channel: The channel's buffer is initialized with the specified
//    buffer capacity. If zero, or the size is omitted, the channel is
//    unbuffered.
//  通道：使用指定的缓冲区容量初始化通道的缓冲区。如果为零，或忽略了大小，则通道未缓冲。
func make(t Type, size ...IntegerType) Type

// The new built-in function allocates memory. The first argument is a type,
// not a value, and the value returned is a pointer to a newly
// allocated zero value of that type.
// new内置函数分配内存。第一个参数是类型，而不是值，返回的值是指向该类型新分配的零值的指针。
func new(Type) *Type

// The complex built-in function constructs a complex value from two
// floating-point values. The real and imaginary parts must be of the same
// size, either float32 or float64 (or assignable to them), and the return
// value will be the corresponding complex type (complex64 for float32,
// complex128 for float64).
// complex内置函数从两个浮点值构造一个复杂值。实部和虚部的大小必须相同，float32或float64（或可分配给它们），
// 返回值将是相应的复杂类型（float32为complex64，float64为complex128）。
func complex(r, i FloatType) ComplexType

// The real built-in function returns the real part of the complex number c.
// The return value will be floating point type corresponding to the type of c.
// real内置函数返回复数c的实数部分。返回值将是对应于c类型的浮点类型。
func real(c ComplexType) FloatType

// The imag built-in function returns the imaginary part of the complex
// number c. The return value will be floating point type corresponding to
// the type of c.
// imag内置函数返回复数c的虚部。返回值将是对应于c类型的浮点类型。
func imag(c ComplexType) FloatType

// The close built-in function closes a channel, which must be either
// bidirectional or send-only. It should be executed only by the sender,
// never the receiver, and has the effect of shutting down the channel after
// the last sent value is received. After the last value has been received
// from a closed channel c, any receive from c will succeed without
// blocking, returning the zero value for the channel element. The form

// close内置函数关闭通道，通道必须是双向的或仅发送的。它只能由发送方执行，而不能由接收方执行，并且在接收到最后发送的值后会关闭通道。
// 在从封闭通道c接收到最后一个值之后，来自c的任何接收都将成功而不会阻塞，返回通道元素的零值。 形如：

//    x, ok := <-c
//
// will also set ok to false for a closed and empty channel.
// 对于关闭的空通道，也会将ok设置为false

func close(c chan<- Type)

// The panic built-in function stops normal execution of the current
// goroutine. When a function F calls panic, normal execution of F stops
// immediately. Any functions whose execution was deferred by F are run in
// the usual way, and then F returns to its caller. To the caller G, the
// invocation of F then behaves like a call to panic, terminating G's
// execution and running any deferred functions. This continues until all
// functions in the executing goroutine have stopped, in reverse order. At
// that point, the program is terminated with a non-zero exit code. This
// termination sequence is called panicking and can be controlled by the
// built-in function recover.
// panic内置函数阻止当前goroutine的正常执行。当函数F调用panic时，F的正常执行立即停止。
// 任何被F延迟执行的函数都以通常的方式运行，然后F返回其调用方。对调用方G来说，
// F的调用就像一次紧急调用，终止G的执行并运行任何延迟的函数。
// 这将一直持续到正在执行的goroutine中的所有函数都停止为止，顺序相反。
// 此时，程序以非零退出代码终止。这种终止序列称为恐慌，可以由内置函数recover控制。
func panic(v any)

// The recover built-in function allows a program to manage behavior of a
// panicking goroutine. Executing a call to recover inside a deferred
// function (but not any function called by it) stops the panicking sequence
// by restoring normal execution and retrieves the error value passed to the
// call of panic. If recover is called outside the deferred function it will
// not stop a panicking sequence. In this case, or when the goroutine is not
// panicking, or if the argument supplied to panic was nil, recover returns
// nil. Thus the return value from recover reports whether the goroutine is
// panicking.
// recover内置函数允许程序管理惊慌失措的goroutine的行为。在延迟函数（而不是它调用的任何函数）内执行恢复调用，
// 通过恢复正常执行来停止恐慌序列，并检索传递给恐慌调用的错误值。如果在延迟函数之外调用recover，则不会停止恐慌序列。
// 在这种情况下，或者当goroutine没有恐慌时，或者如果提供给恐慌的参数为零，recover返回零。
// 因此，recover的返回值报告goroutine是否处于恐慌状态。
func recover() any

// The print built-in function formats its arguments in an
// implementation-specific way and writes the result to standard error.
// Print is useful for bootstrapping and debugging; it is not guaranteed
// to stay in the language.
// print内置函数一特定的实现方式格式化参数，并将结果写入标准错误。
// 始终在参数之间添加空格，并追加新的一行。prinln对于引导和调试有用，它不能保证停留在语言中。
func print(args ...Type)

// The println built-in function formats its arguments in an
// implementation-specific way and writes the result to standard error.
// Spaces are always added between arguments and a newline is appended.
// Println is useful for bootstrapping and debugging; it is not guaranteed
// to stay in the language.
// println内置函数一特定的实现方式格式化参数，并将结果写入标准错误。
// 始终在参数之间添加空格，并追加新的一行。prinln对于引导和调试有用，它不能保证停留在语言中。
func println(args ...Type)

// The error built-in interface type is the conventional interface for
// representing an error condition, with the nil value representing no error.
// error内置接口是一种表示错误情形的常见接口，nil值表示没有错误
type error interface {
    Error() string
}