From 453683bf44f2112719802eaac2b332d49eebd640 Mon Sep 17 00:00:00 2001
From: Yong He <yonghe@outlook.com>
Date: Mon, 19 Aug 2024 15:03:56 -0700
Subject: Tuple swizzling, concat, comparison and `countof`. (#4856)

* Tuple swizzling and element access.

* Update proposal status.

* Cleanup.

* Fix merrge error.

* Address review.
---
 docs/user-guide/03-convenience-features.md | 47 ++++++++++++++++++++++++++++++
 docs/user-guide/toc.html                   |  1 +
 2 files changed, 48 insertions(+)

(limited to 'docs/user-guide')

diff --git a/docs/user-guide/03-convenience-features.md b/docs/user-guide/03-convenience-features.md
index dc1723ebe..559e4c9b4 100644
--- a/docs/user-guide/03-convenience-features.md
+++ b/docs/user-guide/03-convenience-features.md
@@ -354,6 +354,53 @@ int test()
 }
 ```
 
+## Tuple Types
+
+Tuple types can hold collection of values of different types.
+Tuples types are defined in Slang with the `Tuple<...>` syntax, and
+constructed with either a constructor or the `makeTuple` function:
+```csharp
+Tuple<int, float, bool> t0 = Tuple<int, float, bool>(5, 2.0f, false);
+Tuple<int, float, bool> t1 = makeTuple(3, 1.0f, true);
+```
+
+Tuple elements can be accessed with `_0`, `_1` member names:
+```csharp
+int i = t0._0; // 5
+bool b = t1._2; // true
+```
+
+You can use the swizzle syntax similar to vectors and matrices to form new
+tuples:
+
+```csharp
+t0._0_0_1 // evaluates to (5, 5, 2.0f)
+```
+
+You can concatenate two tuples:
+
+```csharp
+concat(t0, t1) // evaluates to (5, 2.0f, false, 3, 1.0f, true)
+```
+
+If all element types of a tuple conforms to `IComparable`, then the tuple itself
+will conform to `IComparable`, and you can use comparison operators on the tuples
+to compare them:
+
+```csharp
+let cmp = t0 < t1; // false
+```
+
+You can use `countof()` on a tuple type or a tuple value to obtain the number of
+elements in a tuple. This is considered a compile-time constant.
+```csharp
+int n = countof(Tuple<int, float>); // 2
+int n1 = countof(makeTuple(1,2,3)); // 3
+```
+
+All tuple types will be translated to `struct` types, and receive the same layout
+as `struct` types.
+
 ## `Optional<T>` type
 
 Slang supports the `Optional<T>` type to represent a value that may not exist.
diff --git a/docs/user-guide/toc.html b/docs/user-guide/toc.html
index ca6aac92a..5b48c0d9d 100644
--- a/docs/user-guide/toc.html
+++ b/docs/user-guide/toc.html
@@ -38,6 +38,7 @@
 <li data-link="convenience-features#initializers"><span>Initializers</span></li>
 <li data-link="convenience-features#operator-overloading"><span>Operator Overloading</span></li>
 <li data-link="convenience-features#subscript-operator"><span>Subscript Operator</span></li>
+<li data-link="convenience-features#tuple-types"><span>Tuple Types</span></li>
 <li data-link="convenience-features#optionalt-type"><span>`Optional&lt;T&gt;` type</span></li>
 <li data-link="convenience-features#if-let-syntax"><span>`if_let` syntax</span></li>
 <li data-link="convenience-features#reinterprett-operation"><span>`reinterpret&lt;T&gt;` operation</span></li>
-- 
cgit v1.2.3