book chapter

Author: colin-r-schultz

book/src/SUMMARY.md

@@ -11,6 +11,7 @@
   - [Types with special support](./call_rust_from_cpp/special_types.md)
   - [Panic and exceptions](./call_rust_from_cpp/panic_and_exceptions.md)
   - [Raw pointers](./call_rust_from_cpp/raw_pointers.md)
+  - [Template types](./template_types.md)
 - [Calling C++ from Rust](./call_cpp_from_rust/index.md)
   - [Calling C++ free functions](./call_cpp_from_rust/function.md)
   - [Writing `impl` blocks for Rust types in C++](./call_cpp_from_rust/rust_impl.md)

book/src/template_types.md

@@ -0,0 +1,65 @@
+# Template types
+
+Template type definitions provide a shorthand syntax to avoid repeating the defintion of methods on common generic types. All of the items within a template type definition are copied into each matching concrete type definition. At the moment, template types are considered unstable and ust be activated with the `#unstable(template_types)` directive.
+
+For example:
+```
+#unstable(template_types)
+
+type<T> ::std::option::Option<T> {
+    constructor Some(T);
+    constructor None;
+    fn unwrap(self) -> T;
+    fn is_some(&self) -> bool;
+}
+
+type ::std::option::Option<i32> {
+    #layout(size = 8, align = 8);
+    wellknown_traits(Copy, Debug);
+    // the constructors and methods are automatically defined
+}
+```
+
+You can also define well-known traits and layouts in template types:
+```
+type<T> [T] {
+    wellknown_traits(?Sized);
+}
+
+type<T> ::std::vec::Vec<T> {
+    #layout(size = 24, align = 8);
+}
+
+type<T> option::Option<&T> {
+    #layout(size = 8, align = 8);
+    wellknown_traits(Copy);
+}
+```
+
+Note that multiple template defintions can apply to the same concrete type, so `Option<&i32>` would inherit definitions from the `Option<T>` template and the `Option<&T>` template.
+
+You can also override the layout given in a template:
+```
+type<T> Box<T> {
+    #layout(size = 8, align = 8);
+    // Most Boxed types are 8 bytes
+}
+
+type<T> Box<i32> {} // Inherits the 8 byte layouts
+
+type Box<dyn crate::MyTrait> {
+    #layout(size = 16, align = 8);
+    // Boxed trait objects are 16 bytes
+}
+```
+
+Zngur will still only emit C++ definitions for the concrete types that are defined. Template definitions on their own do not result in any C++ code. This also means that at the moment, any type mentioned in a template definition must be individually defined as well. For example, the following code will fail to compile unless `Option<String>` is defined to make `Result::<String, i64>::ok` valid. If the `Option<T>` template from above is defined, then we must add a definition for `String` as well to support `Option::<String>::unwrap`.
+```
+type<T, E> ::std::result::Result<T, E> {
+    fn ok(self) -> ::std::option::Option<T>;
+}
+
+type ::std::result::Result<::std::string::String, i64> {
+    #layout(size = 24, align = 8);
+}
+```

examples/template_types/main.zng

@@ -46,8 +46,7 @@ mod crate {
     type ::std::vec::Vec<TypeA> {
         wellknown_traits(Debug);
     }
-    // These definitions are required for the Vec<T> template to instantiate all methods
-    type [TypeA] {}
+    // This definition is required for the Vec<T> template to instantiate all methods
     type ::std::option::Option<&TypeA> {} 
 
     type TypeB {
@@ -58,7 +57,6 @@ mod crate {
 
     // All relevant definitions are provided by the templates
     type ::std::vec::Vec<TypeB> {}
-    type [TypeB] {}
     type ::std::option::Option<&TypeB> {}
 
     type ::std::boxed::Box<dyn MyTrait> {