path: root/devdocs/go/go%2Fconstant%2Findex.html

<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] &lt;= 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 &lt; 0, x == 0, or x &gt; 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> &gt;= 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> (&lt;&lt; or &gt;&gt;). 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 &gt; 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">
    &copy; 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>