diff --git a/examples/README.md b/examples/README.md index 9f48cff..37085cd 100644 --- a/examples/README.md +++ b/examples/README.md @@ -8,4 +8,5 @@ Simple functions: Features: * **[args](args):** Loading function arguments. +* **[returns](returns):** Building return values. * **[complex](complex):** Working with `complex{64,128}` types. diff --git a/examples/returns/README.md b/examples/returns/README.md new file mode 100644 index 0000000..c78e53e --- /dev/null +++ b/examples/returns/README.md @@ -0,0 +1,103 @@ +# returns + +Demonstrates working with function return values. + +## Multiple Unnamed Return Values + +Use `ReturnIndex` to reference unnamed return values. For example, the following function returns `start, start + size`. + +[embedmd]:# (asm.go go /.*TEXT.*Interval/ /RET.*/) +```go + TEXT("Interval", "func(start, size uint64) (uint64, uint64)") + Doc( + "Interval returns the (start, end) of an interval with the given start and size.", + "Demonstrates multiple unnamed return values.", + ) + start := Load(Param("start"), GP64v()) + size := Load(Param("size"), GP64v()) + end := size + ADDQ(start, end) + Store(start, ReturnIndex(0)) + Store(end, ReturnIndex(1)) + RET() +``` + +## Multiple Named Return Values + +Named return values are referenced much the same as arguments. For example, the following computes `(x0+x1, x0-x1)`. + +[embedmd]:# (asm.go go /.*TEXT.*Butterfly/ /RET.*/) +```go + TEXT("Butterfly", "func(x0, x1 float64) (y0, y1 float64)") + Doc( + "Butterfly performs a 2-dimensional butterfly operation: computes (x0+x1, x0-x1).", + "Demonstrates multiple named return values.", + ) + x0 := Load(Param("x0"), Xv()) + x1 := Load(Param("x1"), Xv()) + y0, y1 := Xv(), Xv() + MOVSD(x0, y0) + ADDSD(x1, y0) + MOVSD(x0, y1) + SUBSD(x1, y1) + Store(y0, Return("y0")) + Store(y1, Return("y1")) + RET() +``` + +## Returning Data Structures + +Again just like function arguments, sub-components of return values can be referenced. This enables you to return data structures from your assembly functions. + +The following code returns an array type. + +[embedmd]:# (asm.go go /.*TEXT.*Septuple/ /RET.*/) +```go + TEXT("Septuple", "func(byte) [7]byte") + Doc( + "Septuple returns an array of seven of the given byte.", + "Demonstrates returning array values.", + ) + b := Load(ParamIndex(0), GP8v()) + for i := 0; i < 7; i++ { + Store(b, ReturnIndex(0).Index(i)) + } + RET() +``` + +Or a complex type: + +[embedmd]:# (asm.go go /.*TEXT.*CriticalLine/ /RET.*/) +```go + TEXT("CriticalLine", "func(t float64) complex128") + Doc( + "CriticalLine returns the complex value 0.5 + it on Riemann's critical line.", + "Demonstrates returning complex values.", + ) + t := Load(Param("t"), Xv()) + half := Xv() + MOVSD(ConstData("half", F64(0.5)), half) + Store(half, ReturnIndex(0).Real()) + Store(t, ReturnIndex(0).Imag()) + RET() +``` + +You can even build a struct: + +[embedmd]:# (asm.go go /.*TEXT.*NewStruct/ /RET.*/) +```go + TEXT("NewStruct", "func(w uint16, p [2]float64, q uint64) Struct") + Doc( + "NewStruct initializes a Struct value.", + "Demonstrates returning struct values.", + ) + w := Load(Param("w"), GP16v()) + x := Load(Param("p").Index(0), Xv()) + y := Load(Param("p").Index(1), Xv()) + q := Load(Param("q"), GP64v()) + Store(w, ReturnIndex(0).Field("Word")) + Store(x, ReturnIndex(0).Field("Point").Index(0)) + Store(y, ReturnIndex(0).Field("Point").Index(1)) + Store(q, ReturnIndex(0).Field("Quad")) + RET() +```