From cb7c5d58d9ed01b9078e5c6632692120292ef598 Mon Sep 17 00:00:00 2001
From: Ben-Fields <33070053+Ben-Fields@users.noreply.github.com>
Date: Sun, 21 Feb 2021 03:51:34 -0600
Subject: [PATCH] docs: add a unions section (#8873)

---
 doc/docs.md | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/doc/docs.md b/doc/docs.md
index 0a2b610081..b35669f58d 100644
--- a/doc/docs.md
+++ b/doc/docs.md
@@ -86,6 +86,7 @@ For more details and troubleshooting, please visit the [vab GitHub repository](h
 
 </td><td width=33% valign=top>
 
+* [Unions](#unions)
 * [Functions 2](#functions-2)
     * [Pure functions by default](#pure-functions-by-default)
     * [Mutable arguments](#mutable-arguments)
@@ -1587,6 +1588,45 @@ In this example, the `can_register` method has a receiver of type `User` named `
 The convention is not to use receiver names like `self` or `this`,
 but a short, preferably one letter long, name.
 
+## Unions
+
+Just like structs, unions support embedding.
+
+```v
+struct Rgba32_Component {
+	r byte
+	g byte
+	b byte
+	a byte
+}
+
+union Rgba32 {
+	Rgba32_Component
+	value u32
+}
+
+clr1 := Rgba32{
+	value: 0x008811FF
+}
+
+clr2 := Rgba32{
+	Rgba32_Component: {
+		a: 128
+	}
+}
+
+sz := sizeof(Rgba32)
+unsafe {
+	println('Size: ${sz}B,clr1.b: $clr1.b,clr2.b: $clr2.b')
+}
+```
+
+Output: `Size: 4B, clr1.b: 136, clr2.b: 0`
+
+Union member access must be performed in an `unsafe` block.
+
+Note that the embedded struct arguments are not necessarily stored in the order listed.
+
 ## Functions 2
 
 ### Pure functions by default