0001-Initial-documentation-for-CUnion-embedded-structures.patch

From bfd36fe5d307918130677bf7be093c2071d9beb6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?C=C3=A9dric=20Vincent?= <git@6dof.xyz>
Date: Wed, 15 Jul 2015 10:54:03 +0200
Subject: [PATCH] Initial documentation for CUnion + embedded structures.

---
 lib/Language/nativecall.pod | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/lib/Language/nativecall.pod b/lib/Language/nativecall.pod
index f3fca0d..0068b21 100644
--- a/lib/Language/nativecall.pod
+++ b/lib/Language/nativecall.pod
@@ -230,6 +230,40 @@ members: C<$!struct-member := StructObj.new;>
 As you may have predicted by now, a null is represented by the type object of the
 struct type.
 
+=head2 CUnions
+
+Likewise, it is possible to declare a Perl 6 class that stores its
+attributes the same way a C compiler would lay them out in a similar
+C<union> definition; using the C<CUnion> representation:
+
+    class MyUnion is repr('CUnion') {
+        has int32 $.flags32;
+        has int64 $.flags64;
+    }
+
+    say nativesizeof(MyUnion.new);  # 8, ie. max(sizeof(MyUnion.flags32), sizeof(MyUnion.flags64))
+
+=head2 Embedding CStructs and CUnions
+
+CStructs and CUnions can be in turn referenced by -- or embedded into
+-- a surrounding CStruct and CUnion.  To say the former we use C<has>
+as usual, and to do the latter we use use the C<HAS> declarator
+instead:
+
+    class MyStruct is repr('CStruct') {
+        has Point $.point;  # referenced
+        has int32 $.flags;
+    }
+
+    say nativesizeof(MyStruct.new);  # 16, ie. sizeof(struct Point *) + sizeof(int32_t)
+
+    class MyStruct2 is repr('CStruct') {
+        HAS Point $.point;  # embedded
+        has int32 $.flags;
+    }
+
+    say nativesizeof(MyStruct2.new);  # 24, ie. sizeof(struct Point) + sizeof(int32_t)
+
 =head1 Typed Pointers
 
 TBD
-- 
1.8.4