libgo/go/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 built-in functions.
   7         The functions documented here are not actually in package builtin
   8         but their descriptions here allow godoc to present documentation
   9         for the language's special functions.
  10 */
  11 package builtin
  12
  13 // Type is here for the purposes of documentation only. It is a stand-in
  14 // for any Go type, but represents the same type for any given function
  15 // invocation.
  16 type Type int
  17
  18 // IntegerType is here for the purposes of documentation only. It is a stand-in
  19 // for any integer type: int, uint, int8 etc.
  20 type IntegerType int
  21
  22 // FloatType is here for the purposes of documentation only. It is a stand-in
  23 // for either float type: float32 or float64.
  24 type FloatType int
  25
  26 // ComplexType is here for the purposes of documentation only. It is a
  27 // stand-in for either complex type: complex64 or complex128.
  28 type ComplexType int
  29
  30 // The append built-in function appends elements to the end of a slice. If
  31 // it has sufficient capacity, the destination is resliced to accommodate the
  32 // new elements. If it does not, a new underlying array will be allocated.
  33 // Append returns the updated slice. It is therefore necessary to store the
  34 // result of append, often in the variable holding the slice itself:
  35 //      slice = append(slice, elem1, elem2)
  36 //      slice = append(slice, anotherSlice...)
  37 func append(slice []Type, elems ...Type) []Type
  38
  39 // The copy built-in function copies elements from a source slice into a
  40 // destination slice. (As a special case, it also will copy bytes from a
  41 // string to a slice of bytes.) The source and destination may overlap. Copy
  42 // returns the number of elements copied, which will be the minimum of
  43 // len(src) and len(dst).
  44 func copy(dst, src []Type) int
  45
  46 // The len built-in function returns the length of v, according to its type:
  47 //      Array: the number of elements in v.
  48 //      Pointer to array: the number of elements in *v (even if v is nil).
  49 //      Slice, or map: the number of elements in v; if v is nil, len(v) is zero.
  50 //      String: the number of bytes in v.
  51 //      Channel: the number of elements queued (unread) in the channel buffer;
  52 //      if v is nil, len(v) is zero.
  53 func len(v Type) int
  54
  55 // The cap built-in function returns the capacity of v, according to its type:
  56 //      Array: the number of elements in v (same as len(v)).
  57 //      Pointer to array: the number of elements in *v (same as len(v)).
  58 //      Slice: the maximum length the slice can reach when resliced;
  59 //      if v is nil, cap(v) is zero.
  60 //      Channel: the channel buffer capacity, in units of elements;
  61 //      if v is nil, cap(v) is zero.
  62 func cap(v Type) int
  63
  64 // The make built-in function allocates and initializes an object of type
  65 // slice, map, or chan (only). Like new, the first argument is a type, not a
  66 // value. Unlike new, make's return type is the same as the type of its
  67 // argument, not a pointer to it. The specification of the result depends on
  68 // the type:
  69 //      Slice: The size specifies the length. The capacity of the slice is
  70 //      equal to its length. A second integer argument may be provided to
  71 //      specify a different capacity; it must be no smaller than the
  72 //      length, so make([]int, 0, 10) allocates a slice of length 0 and
  73 //      capacity 10.
  74 //      Map: An initial allocation is made according to the size but the
  75 //      resulting map has length 0. The size may be omitted, in which case
  76 //      a small starting size is allocated.
  77 //      Channel: The channel's buffer is initialized with the specified
  78 //      buffer capacity. If zero, or the size is omitted, the channel is
  79 //      unbuffered.
  80 func make(Type, size IntegerType) Type
  81
  82 // The new built-in function allocates memory. The first argument is a type,
  83 // not a value, and the value returned is a pointer to a newly
  84 // allocated zero value of that type.
  85 func new(Type) *Type
  86
  87 // The complex built-in function constructs a complex value from two
  88 // floating-point values. The real and imaginary parts must be of the same
  89 // size, either float32 or float64 (or assignable to them), and the return
  90 // value will be the corresponding complex type (complex64 for float32,
  91 // complex128 for float64).
  92 func complex(r, i FloatType) ComplexType
  93
  94 // The real built-in function returns the real part of the complex number c.
  95 // The return value will be floating point type corresponding to the type of c.
  96 func real(c ComplexType) FloatType
  97
  98 // The imaginary built-in function returns the imaginary part of the complex
  99 // number c. The return value will be floating point type corresponding to
 100 // the type of c.
 101 func imag(c ComplexType) FloatType
 102
 103 // The close built-in function closes a channel, which must be either
 104 // bidirectional or send-only. It should be executed only by the sender,
 105 // never the receiver, and has the effect of shutting down the channel after
 106 // the last sent value is received. After the last value has been received
 107 // from a closed channel c, any receive from c will succeed without
 108 // blocking, returning the zero value for the channel element. The form
 109 //      x, ok := <-c
 110 // will also set ok to false for a closed channel.
 111 func close(c chan<- Type)
 112
 113 // The panic built-in function stops normal execution of the current
 114 // goroutine. When a function F calls panic, normal execution of F stops
 115 // immediately. Any functions whose execution was deferred by F are run in
 116 // the usual way, and then F returns to its caller. To the caller G, the
 117 // invocation of F then behaves like a call to panic, terminating G's
 118 // execution and running any deferred functions. This continues until all
 119 // functions in the executing goroutine have stopped, in reverse order. At
 120 // that point, the program is terminated and the error condition is reported,
 121 // including the value of the argument to panic. This termination sequence
 122 // is called panicking and can be controlled by the built-in function
 123 // recover.
 124 func panic(v interface{})
 125
 126 // The recover built-in function allows a program to manage behavior of a
 127 // panicking goroutine. Executing a call to recover inside a deferred
 128 // function (but not any function called by it) stops the panicking sequence
 129 // by restoring normal execution and retrieves the error value passed to the
 130 // call of panic. If recover is called outside the deferred function it will
 131 // not stop a panicking sequence. In this case, or when the goroutine is not
 132 // panicking, or if the argument supplied to panic was nil, recover returns
 133 // nil. Thus the return value from recover reports whether the goroutine is
 134 // panicking.
 135 func recover() interface{}