From 02a5270c5a5fa454f4992592c8324342b4adc49c Mon Sep 17 00:00:00 2001
From: Josh Ring <joshringuk@gmail.com>
Date: Tue, 23 Dec 2025 10:38:04 +0000
Subject: [PATCH] Add docstring to swizzle and swizzle2 (#2674)

* Add docstring to swizzle and swizzle2

* Fixup

---------

Co-authored-by: Christoffer Lerno <christoffer@aegik.com>
---
 lib/std/core/builtin.c3 | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/lib/std/core/builtin.c3 b/lib/std/core/builtin.c3
index c8d0887b3..b0e05c97f 100644
--- a/lib/std/core/builtin.c3
+++ b/lib/std/core/builtin.c3
@@ -451,11 +451,24 @@ macro @prefetch(void* ptr, PrefetchLocality $locality = VERY_NEAR, bool $write =
 	$endif
 }
 
+<*
+ Shuffle a vector by its index
+ 
+ int[<4>] a = { 1, 2, 3, 4 };
+ assert(swizzle(a, 0, 1, 1, 3) == (int[<4>]) { 1, 2, 2, 4 });
+*>
 macro swizzle(v, ...) @builtin
 {
 	return $$swizzle(v, $vasplat);
 }
 
+<*
+ Shuffle two vectors by a common index from arranging the vectors sequentially in memory
+
+ int[<4>] a = { 1, 2, 3, 4 };
+ int[<4>] b = { 100, 1000, 10000, 100000 };
+ assert(swizzle2(a, b, 0, 1, 4, 6, 2) == (int[<5>]) { 1, 2, 100, 10000, 3 });
+*>
 macro swizzle2(v, v2, ...) @builtin
 {
 	return $$swizzle2(v, v2, $vasplat);