diff options
Diffstat (limited to 'devdocs/go/go%2Fconstant%2Findex.html')
| -rw-r--r-- | devdocs/go/go%2Fconstant%2Findex.html | 290 |
1 files changed, 290 insertions, 0 deletions
diff --git a/devdocs/go/go%2Fconstant%2Findex.html b/devdocs/go/go%2Fconstant%2Findex.html new file mode 100644 index 00000000..817a4dcc --- /dev/null +++ b/devdocs/go/go%2Fconstant%2Findex.html @@ -0,0 +1,290 @@ +<h1> Package constant </h1> <ul id="short-nav"> +<li><code>import "go/constant"</code></li> +<li><a href="#pkg-overview" class="overviewLink">Overview</a></li> +<li><a href="#pkg-index" class="indexLink">Index</a></li> +<li><a href="#pkg-examples" class="examplesLink">Examples</a></li> +</ul> <h2 id="pkg-overview">Overview </h2> <p>Package constant implements Values representing untyped Go constants and their corresponding operations. </p> +<p>A special Unknown value may be used when a value is unknown due to an error. Operations on unknown values produce unknown values unless specified otherwise. </p> <h4 id="example__complexNumbers"> <span class="text">Example (ComplexNumbers)</span> +</h4> <p>Code:</p> <pre class="code" data-language="go">// Create the complex number 2.3 + 5i. +ar := constant.MakeFloat64(2.3) +ai := constant.MakeImag(constant.MakeInt64(5)) +a := constant.BinaryOp(ar, token.ADD, ai) + +// Compute (2.3 + 5i) * 11. +b := constant.MakeUint64(11) +c := constant.BinaryOp(a, token.MUL, b) + +// Convert c into a complex128. +Ar, exact := constant.Float64Val(constant.Real(c)) +if !exact { + fmt.Printf("Could not represent real part %s exactly as float64\n", constant.Real(c)) +} +Ai, exact := constant.Float64Val(constant.Imag(c)) +if !exact { + fmt.Printf("Could not represent imaginary part %s as exactly as float64\n", constant.Imag(c)) +} +C := complex(Ar, Ai) + +fmt.Println("literal", 25.3+55i) +fmt.Println("go/constant", c) +fmt.Println("complex128", C) + +</pre> <p>Output:</p> <pre class="output" data-language="go"> +Could not represent real part 25.3 exactly as float64 +literal (25.3+55i) +go/constant (25.3 + 55i) +complex128 (25.299999999999997+55i) +</pre> <h2 id="pkg-index">Index </h2> <ul id="manual-nav"> +<li><a href="#BitLen">func BitLen(x Value) int</a></li> +<li><a href="#BoolVal">func BoolVal(x Value) bool</a></li> +<li><a href="#Bytes">func Bytes(x Value) []byte</a></li> +<li><a href="#Compare">func Compare(x_ Value, op token.Token, y_ Value) bool</a></li> +<li><a href="#Float32Val">func Float32Val(x Value) (float32, bool)</a></li> +<li><a href="#Float64Val">func Float64Val(x Value) (float64, bool)</a></li> +<li><a href="#Int64Val">func Int64Val(x Value) (int64, bool)</a></li> +<li><a href="#Sign">func Sign(x Value) int</a></li> +<li><a href="#StringVal">func StringVal(x Value) string</a></li> +<li><a href="#Uint64Val">func Uint64Val(x Value) (uint64, bool)</a></li> +<li><a href="#Val">func Val(x Value) any</a></li> +<li><a href="#Kind">type Kind</a></li> +<li> <a href="#Kind.String">func (i Kind) String() string</a> +</li> +<li><a href="#Value">type Value</a></li> +<li> <a href="#BinaryOp">func BinaryOp(x_ Value, op token.Token, y_ Value) Value</a> +</li> +<li> <a href="#Denom">func Denom(x Value) Value</a> +</li> +<li> <a href="#Imag">func Imag(x Value) Value</a> +</li> +<li> <a href="#Make">func Make(x any) Value</a> +</li> +<li> <a href="#MakeBool">func MakeBool(b bool) Value</a> +</li> +<li> <a href="#MakeFloat64">func MakeFloat64(x float64) Value</a> +</li> +<li> <a href="#MakeFromBytes">func MakeFromBytes(bytes []byte) Value</a> +</li> +<li> <a href="#MakeFromLiteral">func MakeFromLiteral(lit string, tok token.Token, zero uint) Value</a> +</li> +<li> <a href="#MakeImag">func MakeImag(x Value) Value</a> +</li> +<li> <a href="#MakeInt64">func MakeInt64(x int64) Value</a> +</li> +<li> <a href="#MakeString">func MakeString(s string) Value</a> +</li> +<li> <a href="#MakeUint64">func MakeUint64(x uint64) Value</a> +</li> +<li> <a href="#MakeUnknown">func MakeUnknown() Value</a> +</li> +<li> <a href="#Num">func Num(x Value) Value</a> +</li> +<li> <a href="#Real">func Real(x Value) Value</a> +</li> +<li> <a href="#Shift">func Shift(x Value, op token.Token, s uint) Value</a> +</li> +<li> <a href="#ToComplex">func ToComplex(x Value) Value</a> +</li> +<li> <a href="#ToFloat">func ToFloat(x Value) Value</a> +</li> +<li> <a href="#ToInt">func ToInt(x Value) Value</a> +</li> +<li> <a href="#UnaryOp">func UnaryOp(op token.Token, y Value, prec uint) Value</a> +</li> +</ul> <div id="pkg-examples"> <h3>Examples</h3> <dl> <dd><a class="exampleLink" href="#example_BinaryOp">BinaryOp</a></dd> <dd><a class="exampleLink" href="#example_Compare">Compare</a></dd> <dd><a class="exampleLink" href="#example_Sign">Sign</a></dd> <dd><a class="exampleLink" href="#example_UnaryOp">UnaryOp</a></dd> <dd><a class="exampleLink" href="#example_Val">Val</a></dd> <dd><a class="exampleLink" href="#example__complexNumbers">Package (ComplexNumbers)</a></dd> </dl> </div> <h3>Package files</h3> <p> <span>kind_string.go</span> <span>value.go</span> </p> <h2 id="BitLen">func <span>BitLen</span> <span title="Added in Go 1.5">1.5</span> </h2> <pre data-language="go">func BitLen(x Value) int</pre> <p>BitLen returns the number of bits required to represent the absolute value x in binary representation; x must be an <a href="#Int">Int</a> or an <a href="#Unknown">Unknown</a>. If x is <a href="#Unknown">Unknown</a>, the result is 0. </p> +<h2 id="BoolVal">func <span>BoolVal</span> <span title="Added in Go 1.5">1.5</span> </h2> <pre data-language="go">func BoolVal(x Value) bool</pre> <p>BoolVal returns the Go boolean value of x, which must be a <a href="#Bool">Bool</a> or an <a href="#Unknown">Unknown</a>. If x is <a href="#Unknown">Unknown</a>, the result is false. </p> +<h2 id="Bytes">func <span>Bytes</span> <span title="Added in Go 1.5">1.5</span> </h2> <pre data-language="go">func Bytes(x Value) []byte</pre> <p>Bytes returns the bytes for the absolute value of x in little- endian binary representation; x must be an <a href="#Int">Int</a>. </p> +<h2 id="Compare">func <span>Compare</span> <span title="Added in Go 1.5">1.5</span> </h2> <pre data-language="go">func Compare(x_ Value, op token.Token, y_ Value) bool</pre> <p>Compare returns the result of the comparison x op y. The comparison must be defined for the operands. If one of the operands is <a href="#Unknown">Unknown</a>, the result is false. </p> <h4 id="example_Compare"> <span class="text">Example</span> +</h4> <p>Code:</p> <pre class="code" data-language="go">vs := []constant.Value{ + constant.MakeString("Z"), + constant.MakeString("bacon"), + constant.MakeString("go"), + constant.MakeString("Frame"), + constant.MakeString("defer"), + constant.MakeFromLiteral(`"a"`, token.STRING, 0), +} + +sort.Slice(vs, func(i, j int) bool { + // Equivalent to vs[i] <= vs[j]. + return constant.Compare(vs[i], token.LEQ, vs[j]) +}) + +for _, v := range vs { + fmt.Println(constant.StringVal(v)) +} + +</pre> <p>Output:</p> <pre class="output" data-language="go"> +Frame +Z +a +bacon +defer +go +</pre> <h2 id="Float32Val">func <span>Float32Val</span> <span title="Added in Go 1.5">1.5</span> </h2> <pre data-language="go">func Float32Val(x Value) (float32, bool)</pre> <p>Float32Val is like <a href="#Float64Val">Float64Val</a> but for float32 instead of float64. </p> +<h2 id="Float64Val">func <span>Float64Val</span> <span title="Added in Go 1.5">1.5</span> </h2> <pre data-language="go">func Float64Val(x Value) (float64, bool)</pre> <p>Float64Val returns the nearest Go float64 value of x and whether the result is exact; x must be numeric or an <a href="#Unknown">Unknown</a>, but not <a href="#Complex">Complex</a>. For values too small (too close to 0) to represent as float64, <a href="#Float64Val">Float64Val</a> silently underflows to 0. The result sign always matches the sign of x, even for 0. If x is <a href="#Unknown">Unknown</a>, the result is (0, false). </p> +<h2 id="Int64Val">func <span>Int64Val</span> <span title="Added in Go 1.5">1.5</span> </h2> <pre data-language="go">func Int64Val(x Value) (int64, bool)</pre> <p>Int64Val returns the Go int64 value of x and whether the result is exact; x must be an <a href="#Int">Int</a> or an <a href="#Unknown">Unknown</a>. If the result is not exact, its value is undefined. If x is <a href="#Unknown">Unknown</a>, the result is (0, false). </p> +<h2 id="Sign">func <span>Sign</span> <span title="Added in Go 1.5">1.5</span> </h2> <pre data-language="go">func Sign(x Value) int</pre> <p>Sign returns -1, 0, or 1 depending on whether x < 0, x == 0, or x > 0; x must be numeric or <a href="#Unknown">Unknown</a>. For complex values x, the sign is 0 if x == 0, otherwise it is != 0. If x is <a href="#Unknown">Unknown</a>, the result is 1. </p> <h4 id="example_Sign"> <span class="text">Example</span> +</h4> <p>Code:</p> <pre class="code" data-language="go">zero := constant.MakeInt64(0) +one := constant.MakeInt64(1) +negOne := constant.MakeInt64(-1) + +mkComplex := func(a, b constant.Value) constant.Value { + b = constant.MakeImag(b) + return constant.BinaryOp(a, token.ADD, b) +} + +vs := []constant.Value{ + negOne, + mkComplex(zero, negOne), + mkComplex(one, negOne), + mkComplex(negOne, one), + mkComplex(negOne, negOne), + zero, + mkComplex(zero, zero), + one, + mkComplex(zero, one), + mkComplex(one, one), +} + +for _, v := range vs { + fmt.Printf("% d %s\n", constant.Sign(v), v) +} + +</pre> <p>Output:</p> <pre class="output" data-language="go"> +-1 -1 +-1 (0 + -1i) +-1 (1 + -1i) +-1 (-1 + 1i) +-1 (-1 + -1i) + 0 0 + 0 (0 + 0i) + 1 1 + 1 (0 + 1i) + 1 (1 + 1i) +</pre> <h2 id="StringVal">func <span>StringVal</span> <span title="Added in Go 1.5">1.5</span> </h2> <pre data-language="go">func StringVal(x Value) string</pre> <p>StringVal returns the Go string value of x, which must be a <a href="#String">String</a> or an <a href="#Unknown">Unknown</a>. If x is <a href="#Unknown">Unknown</a>, the result is "". </p> +<h2 id="Uint64Val">func <span>Uint64Val</span> <span title="Added in Go 1.5">1.5</span> </h2> <pre data-language="go">func Uint64Val(x Value) (uint64, bool)</pre> <p>Uint64Val returns the Go uint64 value of x and whether the result is exact; x must be an <a href="#Int">Int</a> or an <a href="#Unknown">Unknown</a>. If the result is not exact, its value is undefined. If x is <a href="#Unknown">Unknown</a>, the result is (0, false). </p> +<h2 id="Val">func <span>Val</span> <span title="Added in Go 1.13">1.13</span> </h2> <pre data-language="go">func Val(x Value) any</pre> <p>Val returns the underlying value for a given constant. Since it returns an interface, it is up to the caller to type assert the result to the expected type. The possible dynamic return types are: </p> +<pre data-language="go">x Kind type of result +----------------------------------------- +Bool bool +String string +Int int64 or *big.Int +Float *big.Float or *big.Rat +everything else nil +</pre> <h4 id="example_Val"> <span class="text">Example</span> +</h4> <p>Code:</p> <pre class="code" data-language="go">maxint := constant.MakeInt64(math.MaxInt64) +fmt.Printf("%v\n", constant.Val(maxint)) + +e := constant.MakeFloat64(math.E) +fmt.Printf("%v\n", constant.Val(e)) + +b := constant.MakeBool(true) +fmt.Printf("%v\n", constant.Val(b)) + +b = constant.Make(false) +fmt.Printf("%v\n", constant.Val(b)) + +</pre> <p>Output:</p> <pre class="output" data-language="go"> +9223372036854775807 +6121026514868073/2251799813685248 +true +false +</pre> <h2 id="Kind">type <span>Kind</span> <span title="Added in Go 1.5">1.5</span> </h2> <p>Kind specifies the kind of value represented by a <a href="#Value">Value</a>. </p> +<pre data-language="go">type Kind int</pre> <pre data-language="go">const ( + // unknown values + Unknown Kind = iota + + // non-numeric values + Bool + String + + // numeric values + Int + Float + Complex +)</pre> <h3 id="Kind.String">func (Kind) <span>String</span> <span title="Added in Go 1.18">1.18</span> </h3> <pre data-language="go">func (i Kind) String() string</pre> <h2 id="Value">type <span>Value</span> <span title="Added in Go 1.5">1.5</span> </h2> <p>A Value represents the value of a Go constant. </p> +<pre data-language="go">type Value interface { + // Kind returns the value kind. + Kind() Kind + + // String returns a short, quoted (human-readable) form of the value. + // For numeric values, the result may be an approximation; + // for String values the result may be a shortened string. + // Use ExactString for a string representing a value exactly. + String() string + + // ExactString returns an exact, quoted (human-readable) form of the value. + // If the Value is of Kind String, use StringVal to obtain the unquoted string. + ExactString() string + // contains filtered or unexported methods +}</pre> <h3 id="BinaryOp">func <span>BinaryOp</span> <span title="Added in Go 1.5">1.5</span> </h3> <pre data-language="go">func BinaryOp(x_ Value, op token.Token, y_ Value) Value</pre> <p>BinaryOp returns the result of the binary expression x op y. The operation must be defined for the operands. If one of the operands is <a href="#Unknown">Unknown</a>, the result is <a href="#Unknown">Unknown</a>. BinaryOp doesn't handle comparisons or shifts; use <a href="#Compare">Compare</a> or <a href="#Shift">Shift</a> instead. </p> +<p>To force integer division of <a href="#Int">Int</a> operands, use op == <span>token.QUO_ASSIGN</span> instead of <span>token.QUO</span>; the result is guaranteed to be <a href="#Int">Int</a> in this case. Division by zero leads to a run-time panic. </p> <h4 id="example_BinaryOp"> <span class="text">Example</span> +</h4> <p>Code:</p> <pre class="code" data-language="go">// 11 / 0.5 +a := constant.MakeUint64(11) +b := constant.MakeFloat64(0.5) +c := constant.BinaryOp(a, token.QUO, b) +fmt.Println(c) + +</pre> <p>Output:</p> <pre class="output" data-language="go">22 +</pre> <h3 id="Denom">func <span>Denom</span> <span title="Added in Go 1.5">1.5</span> </h3> <pre data-language="go">func Denom(x Value) Value</pre> <p>Denom returns the denominator of x; x must be <a href="#Int">Int</a>, <a href="#Float">Float</a>, or <a href="#Unknown">Unknown</a>. If x is <a href="#Unknown">Unknown</a>, or if it is too large or small to represent as a fraction, the result is <a href="#Unknown">Unknown</a>. Otherwise the result is an <a href="#Int">Int</a> >= 1. </p> +<h3 id="Imag">func <span>Imag</span> <span title="Added in Go 1.5">1.5</span> </h3> <pre data-language="go">func Imag(x Value) Value</pre> <p>Imag returns the imaginary part of x, which must be a numeric or unknown value. If x is <a href="#Unknown">Unknown</a>, the result is <a href="#Unknown">Unknown</a>. </p> +<h3 id="Make">func <span>Make</span> <span title="Added in Go 1.13">1.13</span> </h3> <pre data-language="go">func Make(x any) Value</pre> <p>Make returns the <a href="#Value">Value</a> for x. </p> +<pre data-language="go">type of x result Kind +---------------------------- +bool Bool +string String +int64 Int +*big.Int Int +*big.Float Float +*big.Rat Float +anything else Unknown +</pre> <h3 id="MakeBool">func <span>MakeBool</span> <span title="Added in Go 1.5">1.5</span> </h3> <pre data-language="go">func MakeBool(b bool) Value</pre> <p>MakeBool returns the <a href="#Bool">Bool</a> value for b. </p> +<h3 id="MakeFloat64">func <span>MakeFloat64</span> <span title="Added in Go 1.5">1.5</span> </h3> <pre data-language="go">func MakeFloat64(x float64) Value</pre> <p>MakeFloat64 returns the <a href="#Float">Float</a> value for x. If x is -0.0, the result is 0.0. If x is not finite, the result is an <a href="#Unknown">Unknown</a>. </p> +<h3 id="MakeFromBytes">func <span>MakeFromBytes</span> <span title="Added in Go 1.5">1.5</span> </h3> <pre data-language="go">func MakeFromBytes(bytes []byte) Value</pre> <p>MakeFromBytes returns the <a href="#Int">Int</a> value given the bytes of its little-endian binary representation. An empty byte slice argument represents 0. </p> +<h3 id="MakeFromLiteral">func <span>MakeFromLiteral</span> <span title="Added in Go 1.5">1.5</span> </h3> <pre data-language="go">func MakeFromLiteral(lit string, tok token.Token, zero uint) Value</pre> <p>MakeFromLiteral returns the corresponding integer, floating-point, imaginary, character, or string value for a Go literal string. The tok value must be one of <span>token.INT</span>, <span>token.FLOAT</span>, <span>token.IMAG</span>, <span>token.CHAR</span>, or <span>token.STRING</span>. The final argument must be zero. If the literal string syntax is invalid, the result is an <a href="#Unknown">Unknown</a>. </p> +<h3 id="MakeImag">func <span>MakeImag</span> <span title="Added in Go 1.5">1.5</span> </h3> <pre data-language="go">func MakeImag(x Value) Value</pre> <p>MakeImag returns the <a href="#Complex">Complex</a> value x*i; x must be <a href="#Int">Int</a>, <a href="#Float">Float</a>, or <a href="#Unknown">Unknown</a>. If x is <a href="#Unknown">Unknown</a>, the result is <a href="#Unknown">Unknown</a>. </p> +<h3 id="MakeInt64">func <span>MakeInt64</span> <span title="Added in Go 1.5">1.5</span> </h3> <pre data-language="go">func MakeInt64(x int64) Value</pre> <p>MakeInt64 returns the <a href="#Int">Int</a> value for x. </p> +<h3 id="MakeString">func <span>MakeString</span> <span title="Added in Go 1.5">1.5</span> </h3> <pre data-language="go">func MakeString(s string) Value</pre> <p>MakeString returns the <a href="#String">String</a> value for s. </p> +<h3 id="MakeUint64">func <span>MakeUint64</span> <span title="Added in Go 1.5">1.5</span> </h3> <pre data-language="go">func MakeUint64(x uint64) Value</pre> <p>MakeUint64 returns the <a href="#Int">Int</a> value for x. </p> +<h3 id="MakeUnknown">func <span>MakeUnknown</span> <span title="Added in Go 1.5">1.5</span> </h3> <pre data-language="go">func MakeUnknown() Value</pre> <p>MakeUnknown returns the <a href="#Unknown">Unknown</a> value. </p> +<h3 id="Num">func <span>Num</span> <span title="Added in Go 1.5">1.5</span> </h3> <pre data-language="go">func Num(x Value) Value</pre> <p>Num returns the numerator of x; x must be <a href="#Int">Int</a>, <a href="#Float">Float</a>, or <a href="#Unknown">Unknown</a>. If x is <a href="#Unknown">Unknown</a>, or if it is too large or small to represent as a fraction, the result is <a href="#Unknown">Unknown</a>. Otherwise the result is an <a href="#Int">Int</a> with the same sign as x. </p> +<h3 id="Real">func <span>Real</span> <span title="Added in Go 1.5">1.5</span> </h3> <pre data-language="go">func Real(x Value) Value</pre> <p>Real returns the real part of x, which must be a numeric or unknown value. If x is <a href="#Unknown">Unknown</a>, the result is <a href="#Unknown">Unknown</a>. </p> +<h3 id="Shift">func <span>Shift</span> <span title="Added in Go 1.5">1.5</span> </h3> <pre data-language="go">func Shift(x Value, op token.Token, s uint) Value</pre> <p>Shift returns the result of the shift expression x op s with op == <span>token.SHL</span> or <span>token.SHR</span> (<< or >>). x must be an <a href="#Int">Int</a> or an <a href="#Unknown">Unknown</a>. If x is <a href="#Unknown">Unknown</a>, the result is x. </p> +<h3 id="ToComplex">func <span>ToComplex</span> <span title="Added in Go 1.6">1.6</span> </h3> <pre data-language="go">func ToComplex(x Value) Value</pre> <p>ToComplex converts x to a <a href="#Complex">Complex</a> value if x is representable as a <a href="#Complex">Complex</a>. Otherwise it returns an <a href="#Unknown">Unknown</a>. </p> +<h3 id="ToFloat">func <span>ToFloat</span> <span title="Added in Go 1.6">1.6</span> </h3> <pre data-language="go">func ToFloat(x Value) Value</pre> <p>ToFloat converts x to a <a href="#Float">Float</a> value if x is representable as a <a href="#Float">Float</a>. Otherwise it returns an <a href="#Unknown">Unknown</a>. </p> +<h3 id="ToInt">func <span>ToInt</span> <span title="Added in Go 1.6">1.6</span> </h3> <pre data-language="go">func ToInt(x Value) Value</pre> <p>ToInt converts x to an <a href="#Int">Int</a> value if x is representable as an <a href="#Int">Int</a>. Otherwise it returns an <a href="#Unknown">Unknown</a>. </p> +<h3 id="UnaryOp">func <span>UnaryOp</span> <span title="Added in Go 1.5">1.5</span> </h3> <pre data-language="go">func UnaryOp(op token.Token, y Value, prec uint) Value</pre> <p>UnaryOp returns the result of the unary expression op y. The operation must be defined for the operand. If prec > 0 it specifies the ^ (xor) result size in bits. If y is <a href="#Unknown">Unknown</a>, the result is <a href="#Unknown">Unknown</a>. </p> <h4 id="example_UnaryOp"> <span class="text">Example</span> +</h4> <p>Code:</p> <pre class="code" data-language="go">vs := []constant.Value{ + constant.MakeBool(true), + constant.MakeFloat64(2.7), + constant.MakeUint64(42), +} + +for i, v := range vs { + switch v.Kind() { + case constant.Bool: + vs[i] = constant.UnaryOp(token.NOT, v, 0) + + case constant.Float: + vs[i] = constant.UnaryOp(token.SUB, v, 0) + + case constant.Int: + // Use 16-bit precision. + // This would be equivalent to ^uint16(v). + vs[i] = constant.UnaryOp(token.XOR, v, 16) + } +} + +for _, v := range vs { + fmt.Println(v) +} + +</pre> <p>Output:</p> <pre class="output" data-language="go"> +false +-2.7 +65493 +</pre><div class="_attribution"> + <p class="_attribution-p"> + © Google, Inc.<br>Licensed under the Creative Commons Attribution License 3.0.<br> + <a href="http://golang.org/pkg/go/constant/" class="_attribution-link">http://golang.org/pkg/go/constant/</a> + </p> +</div> |