...
Run Format

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	// bool is the set of boolean values, true and false.
    14	type bool bool
    15	
    16	// true and false are the two untyped boolean values.
    17	const (
    18		true  = 0 == 0 // Untyped bool.
    19		false = 0 != 0 // Untyped bool.
    20	)
    21	
    22	// uint8 is the set of all unsigned 8-bit integers.
    23	// Range: 0 through 255.
    24	type uint8 uint8
    25	
    26	// uint16 is the set of all unsigned 16-bit integers.
    27	// Range: 0 through 65535.
    28	type uint16 uint16
    29	
    30	// uint32 is the set of all unsigned 32-bit integers.
    31	// Range: 0 through 4294967295.
    32	type uint32 uint32
    33	
    34	// uint64 is the set of all unsigned 64-bit integers.
    35	// Range: 0 through 18446744073709551615.
    36	type uint64 uint64
    37	
    38	// int8 is the set of all signed 8-bit integers.
    39	// Range: -128 through 127.
    40	type int8 int8
    41	
    42	// int16 is the set of all signed 16-bit integers.
    43	// Range: -32768 through 32767.
    44	type int16 int16
    45	
    46	// int32 is the set of all signed 32-bit integers.
    47	// Range: -2147483648 through 2147483647.
    48	type int32 int32
    49	
    50	// int64 is the set of all signed 64-bit integers.
    51	// Range: -9223372036854775808 through 9223372036854775807.
    52	type int64 int64
    53	
    54	// float32 is the set of all IEEE-754 32-bit floating-point numbers.
    55	type float32 float32
    56	
    57	// float64 is the set of all IEEE-754 64-bit floating-point numbers.
    58	type float64 float64
    59	
    60	// complex64 is the set of all complex numbers with float32 real and
    61	// imaginary parts.
    62	type complex64 complex64
    63	
    64	// complex128 is the set of all complex numbers with float64 real and
    65	// imaginary parts.
    66	type complex128 complex128
    67	
    68	// string is the set of all strings of 8-bit bytes, conventionally but not
    69	// necessarily representing UTF-8-encoded text. A string may be empty, but
    70	// not nil. Values of string type are immutable.
    71	type string string
    72	
    73	// int is a signed integer type that is at least 32 bits in size. It is a
    74	// distinct type, however, and not an alias for, say, int32.
    75	type int int
    76	
    77	// uint is an unsigned integer type that is at least 32 bits in size. It is a
    78	// distinct type, however, and not an alias for, say, uint32.
    79	type uint uint
    80	
    81	// uintptr is an integer type that is large enough to hold the bit pattern of
    82	// any pointer.
    83	type uintptr uintptr
    84	
    85	// byte is an alias for uint8 and is equivalent to uint8 in all ways. It is
    86	// used, by convention, to distinguish byte values from 8-bit unsigned
    87	// integer values.
    88	type byte byte
    89	
    90	// rune is an alias for int32 and is equivalent to int32 in all ways. It is
    91	// used, by convention, to distinguish character values from integer values.
    92	type rune rune
    93	
    94	// iota is a predeclared identifier representing the untyped integer ordinal
    95	// number of the current const specification in a (usually parenthesized)
    96	// const declaration. It is zero-indexed.
    97	const iota = 0 // Untyped int.
    98	
    99	// nil is a predeclared identifier representing the zero value for a
   100	// pointer, channel, func, interface, map, or slice type.
   101	var nil Type // Type must be a pointer, channel, func, interface, map, or slice type
   102	
   103	// Type is here for the purposes of documentation only. It is a stand-in
   104	// for any Go type, but represents the same type for any given function
   105	// invocation.
   106	type Type int
   107	
   108	// Type1 is here for the purposes of documentation only. It is a stand-in
   109	// for any Go type, but represents the same type for any given function
   110	// invocation.
   111	type Type1 int
   112	
   113	// IntegerType is here for the purposes of documentation only. It is a stand-in
   114	// for any integer type: int, uint, int8 etc.
   115	type IntegerType int
   116	
   117	// FloatType is here for the purposes of documentation only. It is a stand-in
   118	// for either float type: float32 or float64.
   119	type FloatType float32
   120	
   121	// ComplexType is here for the purposes of documentation only. It is a
   122	// stand-in for either complex type: complex64 or complex128.
   123	type ComplexType complex64
   124	
   125	// The append built-in function appends elements to the end of a slice. If
   126	// it has sufficient capacity, the destination is resliced to accommodate the
   127	// new elements. If it does not, a new underlying array will be allocated.
   128	// Append returns the updated slice. It is therefore necessary to store the
   129	// result of append, often in the variable holding the slice itself:
   130	//	slice = append(slice, elem1, elem2)
   131	//	slice = append(slice, anotherSlice...)
   132	// As a special case, it is legal to append a string to a byte slice, like this:
   133	//	slice = append([]byte("hello "), "world"...)
   134	func append(slice []Type, elems ...Type) []Type
   135	
   136	// The copy built-in function copies elements from a source slice into a
   137	// destination slice. (As a special case, it also will copy bytes from a
   138	// string to a slice of bytes.) The source and destination may overlap. Copy
   139	// returns the number of elements copied, which will be the minimum of
   140	// len(src) and len(dst).
   141	func copy(dst, src []Type) int
   142	
   143	// The delete built-in function deletes the element with the specified key
   144	// (m[key]) from the map. If m is nil or there is no such element, delete
   145	// is a no-op.
   146	func delete(m map[Type]Type1, key Type)
   147	
   148	// The len built-in function returns the length of v, according to its type:
   149	//	Array: the number of elements in v.
   150	//	Pointer to array: the number of elements in *v (even if v is nil).
   151	//	Slice, or map: the number of elements in v; if v is nil, len(v) is zero.
   152	//	String: the number of bytes in v.
   153	//	Channel: the number of elements queued (unread) in the channel buffer;
   154	//	if v is nil, len(v) is zero.
   155	func len(v Type) int
   156	
   157	// The cap built-in function returns the capacity of v, according to its type:
   158	//	Array: the number of elements in v (same as len(v)).
   159	//	Pointer to array: the number of elements in *v (same as len(v)).
   160	//	Slice: the maximum length the slice can reach when resliced;
   161	//	if v is nil, cap(v) is zero.
   162	//	Channel: the channel buffer capacity, in units of elements;
   163	//	if v is nil, cap(v) is zero.
   164	func cap(v Type) int
   165	
   166	// The make built-in function allocates and initializes an object of type
   167	// slice, map, or chan (only). Like new, the first argument is a type, not a
   168	// value. Unlike new, make's return type is the same as the type of its
   169	// argument, not a pointer to it. The specification of the result depends on
   170	// the type:
   171	//	Slice: The size specifies the length. The capacity of the slice is
   172	//	equal to its length. A second integer argument may be provided to
   173	//	specify a different capacity; it must be no smaller than the
   174	//	length, so make([]int, 0, 10) allocates a slice of length 0 and
   175	//	capacity 10.
   176	//	Map: An empty map is allocated with enough space to hold the
   177	//	specified number of elements. The size may be omitted, in which case
   178	//	a small starting size is allocated.
   179	//	Channel: The channel's buffer is initialized with the specified
   180	//	buffer capacity. If zero, or the size is omitted, the channel is
   181	//	unbuffered.
   182	func make(Type, size IntegerType) Type
   183	
   184	// The new built-in function allocates memory. The first argument is a type,
   185	// not a value, and the value returned is a pointer to a newly
   186	// allocated zero value of that type.
   187	func new(Type) *Type
   188	
   189	// The complex built-in function constructs a complex value from two
   190	// floating-point values. The real and imaginary parts must be of the same
   191	// size, either float32 or float64 (or assignable to them), and the return
   192	// value will be the corresponding complex type (complex64 for float32,
   193	// complex128 for float64).
   194	func complex(r, i FloatType) ComplexType
   195	
   196	// The real built-in function returns the real part of the complex number c.
   197	// The return value will be floating point type corresponding to the type of c.
   198	func real(c ComplexType) FloatType
   199	
   200	// The imag built-in function returns the imaginary part of the complex
   201	// number c. The return value will be floating point type corresponding to
   202	// the type of c.
   203	func imag(c ComplexType) FloatType
   204	
   205	// The close built-in function closes a channel, which must be either
   206	// bidirectional or send-only. It should be executed only by the sender,
   207	// never the receiver, and has the effect of shutting down the channel after
   208	// the last sent value is received. After the last value has been received
   209	// from a closed channel c, any receive from c will succeed without
   210	// blocking, returning the zero value for the channel element. The form
   211	//	x, ok := <-c
   212	// will also set ok to false for a closed channel.
   213	func close(c chan<- Type)
   214	
   215	// The panic built-in function stops normal execution of the current
   216	// goroutine. When a function F calls panic, normal execution of F stops
   217	// immediately. Any functions whose execution was deferred by F are run in
   218	// the usual way, and then F returns to its caller. To the caller G, the
   219	// invocation of F then behaves like a call to panic, terminating G's
   220	// execution and running any deferred functions. This continues until all
   221	// functions in the executing goroutine have stopped, in reverse order. At
   222	// that point, the program is terminated and the error condition is reported,
   223	// including the value of the argument to panic. This termination sequence
   224	// is called panicking and can be controlled by the built-in function
   225	// recover.
   226	func panic(v interface{})
   227	
   228	// The recover built-in function allows a program to manage behavior of a
   229	// panicking goroutine. Executing a call to recover inside a deferred
   230	// function (but not any function called by it) stops the panicking sequence
   231	// by restoring normal execution and retrieves the error value passed to the
   232	// call of panic. If recover is called outside the deferred function it will
   233	// not stop a panicking sequence. In this case, or when the goroutine is not
   234	// panicking, or if the argument supplied to panic was nil, recover returns
   235	// nil. Thus the return value from recover reports whether the goroutine is
   236	// panicking.
   237	func recover() interface{}
   238	
   239	// The print built-in function formats its arguments in an
   240	// implementation-specific way and writes the result to standard error.
   241	// Print is useful for bootstrapping and debugging; it is not guaranteed
   242	// to stay in the language.
   243	func print(args ...Type)
   244	
   245	// The println built-in function formats its arguments in an
   246	// implementation-specific way and writes the result to standard error.
   247	// Spaces are always added between arguments and a newline is appended.
   248	// Println is useful for bootstrapping and debugging; it is not guaranteed
   249	// to stay in the language.
   250	func println(args ...Type)
   251	
   252	// The error built-in interface type is the conventional interface for
   253	// representing an error condition, with the nil value representing no error.
   254	type error interface {
   255		Error() string
   256	}
   257	

View as plain text