From 8465c21c020db3dbf05e7424d04a6b1b07eab192 Mon Sep 17 00:00:00 2001
From: Michael McLoughlin <mmcloughlin@gmail.com>
Date: Tue, 1 Jan 2019 15:56:17 -0800
Subject: [PATCH] doc: README for complex example

Updates #14
---
 examples/README.md         |  1 +
 examples/complex/README.md | 36 ++++++++++++++++++++++++++++++++++++
 2 files changed, 37 insertions(+)
 create mode 100644 examples/complex/README.md

diff --git a/examples/README.md b/examples/README.md
index 1d9251d..36d720b 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -4,3 +4,4 @@ Feature demonstrations:
 
 * **[add](add):** Add two numbers. The "Hello World!" of `avo`.
 * **[args](args):** Loading function arguments.
+* **[complex](complex):** Working with `complex{64,128}` types.
diff --git a/examples/complex/README.md b/examples/complex/README.md
new file mode 100644
index 0000000..a594455
--- /dev/null
+++ b/examples/complex/README.md
@@ -0,0 +1,36 @@
+# complex
+
+Demonstrates how to access complex types in `avo`.
+
+The `Real()` and `Imag()` parameter methods may be used to load the sub-components of complex arguments. The following function uses these to implement the [complex norm](http://mathworld.wolfram.com/ComplexModulus.html).
+
+[embedmd]:# (asm.go go /.*TEXT.*Norm/ /RET.*/)
+```go
+	TEXT("Norm", "func(z complex128) float64")
+	Doc("Norm returns the complex norm of z.")
+	r = Load(Param("z").Real(), Xv())
+	i = Load(Param("z").Imag(), Xv())
+	MULSD(r, r)
+	MULSD(i, i)
+	ADDSD(i, r)
+	n := Xv()
+	SQRTSD(r, n)
+	Store(n, ReturnIndex(0))
+	RET()
+```
+
+Generated assembly:
+
+[embedmd]:# (complex.s s /.*func Norm/ /RET/)
+```s
+// func Norm(z complex128) float64
+TEXT ·Norm(SB), $0-24
+	MOVSD	z_real(FP), X0
+	MOVSD	z_imag+8(FP), X1
+	MULSD	X0, X0
+	MULSD	X1, X1
+	ADDSD	X1, X0
+	SQRTSD	X0, X2
+	MOVSD	X2, ret+16(FP)
+	RET
+```