feat(docs): add generics section to the docs (#3949)

* feat(docs): add generics section to the docs Signed-off-by: salaheldinsoliman <[email protected]> * feat(docs): import generics and abilities from the Move Ref Signed-off-by: salaheldinsoliman <[email protected]> --------- Signed-off-by: salaheldinsoliman <[email protected]>
iotaledger · Nov 12, 2024 · 0cd8f46 · 0cd8f46
1 parent 3ee8925
commit 0cd8f46
Show file tree

Hide file tree

Showing 6 changed files with 994 additions and 0 deletions.
diff --git a/docs/content/developer/iota-101/move-overview/generics.mdx b/docs/content/developer/iota-101/move-overview/generics.mdx
@@ -0,0 +1,116 @@
+# Generics
+
+Generics are a way to define a type or function that can work with any type. This is useful when you
+want to write a function which can be used with different types, or when you want to define a type
+that can hold any other type. Generics are the foundation of many advanced features in Move, such as
+collections, abstract implementations, and more.
+
+## In the Standard Library
+
+An example of a generic type is the [vector](../../../references/framework/move-stdlib/vector.mdx) type, which is a container type that
+can hold any other type. Another example of a generic type in the standard library is the
+[Option](../../../references/framework/move-stdlib/option.mdx) type, which is used to represent a value that may or may not be present.
+
+## Generic Syntax
+
+To define a generic type or function, a type signature needs to have a list of generic parameters
+enclosed in angle brackets (`<` and `>`). The generic parameters are separated by commas.
+
+```move file=<rootDir>/docs/examples/move/move-overview/generics.move#L8-L16 
+```
+
+In the example above, `Container` is a generic type with a single type parameter `T`, the `value`
+field of the container stores the `T`. The `new` function is a generic function with a single type
+parameter `T`, and it returns a `Container` with the given value. Generic types must be initialed
+with a concrete type, and generic functions must be called with a concrete type.
+
+```move file=<rootDir>/docs/examples/move/move-overview/generics.move#L20-L31 
+```
+
+In the test function `test_generic` we demonstrate three equivalent ways to create a new `Container`
+with a `u8` value. Because numeric types need to be inferred, we specify the type of the number
+literal.
+
+## Multiple Type Parameters
+
+You can define a type or function with multiple type parameters. The type parameters are then
+separated by commas.
+
+```move file=<rootDir>/docs/examples/move/move-overview/generics.move#L35-L44
+```
+
+In the example above, `Pair` is a generic type with two type parameters `T` and `U`, and the
+`new_pair` function is a generic function with two type parameters `T` and `U`. The function returns
+a `Pair` with the given values. The order of the type parameters is important, and it should match
+the order of the type parameters in the type signature.
+
+```move file=<rootDir>/docs/examples/move/move-overview/generics.move#L48-L63
+```
+
+If we added another instance where we swapped type parameters in the `new_pair` function, and tried
+to compare two types, we'd see that the type signatures are different, and cannot be compared.
+
+```move file=<rootDir>/docs/examples/move/move-overview/generics.move#L67-L80
+```
+
+Types for variables `pair1` and `pair2` are different, and the comparison will not compile.
+
+## Why Generics?
+
+In the examples above we focused on instantiating generic types and calling generic functions to
+create instances of these types. However, the real power of generics is the ability to define shared
+behavior for the base, generic type, and then use it independently of the concrete types. This is
+especially useful when working with collections, abstract implementations, and other advanced
+features in Move.
+
+```move file=<rootDir>/docs/examples/move/move-overview/generics.move#L86-L92
+```
+
+In the example above, `User` is a generic type with a single type parameter `T`, with shared fields
+`name` and `age`, and the generic `metadata` field which can store any type. No matter what the
+`metadata` is, all of the instances of `User` will have the same fields and methods.
+
+```move file=<rootDir>/docs/examples/move/move-overview/generics.move#L96-L104
+```
+
+## Phantom Type Parameters
+
+In some cases, you may want to define a generic type with a type parameter that is not used in the
+fields or methods of the type. This is called a _phantom type parameter_. Phantom type parameters
+are useful when you want to define a type that can hold any other type, but you want to enforce some
+constraints on the type parameter.
+
+```move file=<rootDir>/docs/examples/move/move-overview/generics.move#L108-L111
+```
+
+The `Coin` type here does not contain any fields or methods that use the type parameter `T`. It is
+used to differentiate between different types of coins, and to enforce some constraints on the type
+parameter `T`.
+
+```move file=<rootDir>/docs/examples/move/move-overview/generics.move#L115-L126
+```
+
+In the example above, we demonstrate how to create two different instances of `Coin` with different
+phantom type parameters `USD` and `EUR`. The type parameter `T` is not used in the fields or methods
+of the `Coin` type, but it is used to differentiate between different types of coins. It will make
+sure that the `USD` and `EUR` coins are not mixed up.
+
+## Constraints on Type Parameters
+
+Type parameters can be constrained to have certain abilities. This is useful when you need the inner
+type to allow certain behavior, such as _copy_ or _drop_. The syntax for constraining a type
+parameter is `T: <ability> + <ability>`.
+
+```move file=<rootDir>/docs/examples/move/move-overview/generics.move#L130-L138
+```
+
+Move Compiler will enforce that the type parameter `T` has the specified abilities. If the type
+parameter does not have the specified abilities, the code will not compile.
+
+
+```move file=<rootDir>/docs/examples/move/move-overview/generics.move#L142-L152
+```
+
+## Further Reading
+
+- [Generics](../../../references/move/generics.mdx) in the Move Reference.
diff --git a/docs/content/references/move/abilities.mdx b/docs/content/references/move/abilities.mdx
@@ -0,0 +1,240 @@
+# Abilities
+
+Abilities are a typing feature in Move that control what actions are permissible for values of a given type. This system grants fine grained control over the "linear" typing behavior of values, as well as if and how values are used in global storage. This is implemented by gating access to certain bytecode instructions so that for a value to be used with the bytecode instruction, it must have the ability required (if one is required at all—not every instruction is gated by an ability).
+
+## The Four Abilities
+
+The four abilities are:
+
+* [`copy`](#copy)
+    * Allows values of types with this ability to be copied.
+* [`drop`](#drop)
+    * Allows values of types with this ability to be popped/dropped.
+* [`store`](#store)
+    * Allows values of types with this ability to exist inside a struct in global storage.
+* [`key`](#key)
+    * Allows the type to serve as a key for global storage operations.
+
+### `copy`
+
+The `copy` ability allows values of types with that ability to be copied. It gates the ability to copy values out of local variables with the `copy` operator and to copy values via references with dereference `*e`.
+
+If a value has `copy`, all values contained inside of that value have `copy`.
+
+### `drop`
+
+The `drop` ability allows values of types with that ability to be dropped. By dropped, we mean that value is not transferred and is effectively destroyed as the Move program executes. As such, this ability gates the ability to ignore values in a multitude of locations, including:
+* not using the value in a local variable or parameter
+* not using the value in a sequence via `;`
+* overwriting values in variables in assignments
+* overwriting values via references when writing `*e1 = e2`.
+
+If a value has `drop`, all values contained inside of that value have `drop`.
+
+### `store`
+
+The `store` ability allows values of types with this ability to exist inside of a struct (resource) in global storage, *but* not necessarily as a top-level resource in global storage. This is the only ability that does not directly gate an operation. Instead it gates the existence in global storage when used in tandem with `key`.
+
+If a value has `store`, all values contained inside of that value have `store`
+
+### `key`
+
+The `key` ability allows the type to serve as a key for global storage operations. It gates all global storage operations, so in order for a type to be used with `move_to`, `borrow_global`, `move_from`, etc., the type must have the `key` ability. Note that the operations still must be used in the module where the `key` type is defined (in a sense, the operations are private to the defining module).
+
+If a value has `key`, all values contained inside of that value have `store`. This is the only ability with this sort of asymmetry.
+
+## Builtin Types
+
+Most primitive, builtin types have `copy`, `drop`, and `store` with the exception of `signer`, which just has `drop`
+
+* `bool`, `u8`, `u16`, `u32`, `u64`, `u128`, `u256`, and `address` all have `copy`, `drop`, and `store`.
+* `signer` has `drop`
+    * Cannot be copied and cannot be put into global storage
+* `vector<T>` may have `copy`, `drop`, and `store` depending on the abilities of `T`.
+    * See [Conditional Abilities and Generic Types](#conditional-abilities-and-generic-types) for more details.
+* Immutable references `&` and mutable references `&mut` both have `copy` and `drop`.
+    * This refers to copying and dropping the reference itself, not what they refer to.
+    * References cannot appear in global storage, hence they do not have `store`.
+
+None of the primitive types have `key`, meaning none of them can be used directly with the global storage operations.
+
+## Annotating Structs
+
+To declare that a `struct` has an ability, it is declared with `has <ability>` after the struct name but before the fields. For example:
+
+```move
+struct Ignorable has drop { f: u64 }
+struct Pair has copy, drop, store { x: u64, y: u64 }
+```
+
+In this case: `Ignorable` has the `drop` ability. `Pair` has `copy`, `drop`, and `store`.
+
+
+All of these abilities have strong guarantees over these gated operations. The operation can be performed on the value only if it has that ability; even if the value is deeply nested inside of some other collection!
+
+As such: when declaring a struct’s abilities, certain requirements are placed on the fields. All fields must satisfy these constraints. These rules are necessary so that structs satisfy the reachability rules for the abilities given above. If a struct is declared with the ability...
+
+* `copy`, all fields must have `copy`.
+* `drop`, all fields must have `drop`.
+* `store`, all fields must have `store`.
+* `key`, all fields must have `store`.
+    * `key` is the only ability currently that doesn’t require itself.
+
+For example:
+
+```move
+// A struct without any abilities
+struct NoAbilities {}
+
+struct WantsCopy has copy {
+    f: NoAbilities, // ERROR 'NoAbilities' does not have 'copy'
+}
+```
+
+and similarly:
+
+```move
+// A struct without any abilities
+struct NoAbilities {}
+
+struct MyResource has key {
+    f: NoAbilities, // Error 'NoAbilities' does not have 'store'
+}
+```
+
+## Conditional Abilities and Generic Types
+
+When abilities are annotated on a generic type, not all instances of that type are guaranteed to have that ability. Consider this struct declaration:
+
+```
+struct Cup<T> has copy, drop, store, key { item: T }
+```
+
+It might be very helpful if `Cup` could hold any type, regardless of its abilities. The type system can *see* the type parameter, so it should be able to remove abilities from `Cup` if it *sees* a type parameter that would violate the guarantees for that ability.
+
+This behavior might sound a bit confusing at first, but it might be more understandable if we think about collection types. We could consider the builtin type `vector` to have the following type declaration:
+
+```
+vector<T> has copy, drop, store;
+```
+
+We want `vector`s to work with any type. We don't want separate `vector` types for different abilities. So what are the rules we would want? Precisely the same that we would want with the field rules above.  So, it would be safe to copy a `vector` value only if the inner elements can be copied. It would be safe to ignore a `vector` value only if the inner elements can be ignored/dropped. And, it would be safe to put a `vector` in global storage only if the inner elements can be in global storage.
+
+To have this extra expressiveness, a type might not have all the abilities it was declared with depending on the instantiation of that type; instead, the abilities a type will have depends on both its declaration **and** its type arguments. For any type, type parameters are pessimistically assumed to be used inside of the struct, so the abilities are only granted if the type parameters meet the requirements described above for fields. Taking `Cup` from above as an example:
+
+* `Cup` has the ability `copy` only if `T` has `copy`.
+* It has `drop` only if `T` has `drop`.
+* It has `store` only if `T` has `store`.
+* It has `key` only if `T` has `store`.
+
+Here are examples for this conditional system for each ability:
+
+### Example: conditional `copy`
+
+```move
+struct NoAbilities {}
+struct S has copy, drop { f: bool }
+struct Cup<T> has copy, drop, store { item: T }
+
+fun example(c_x: Cup<u64>, c_s: Cup<S>) {
+    // Valid, 'Cup<u64>' has 'copy' because 'u64' has 'copy'
+    let c_x2 = copy c_x;
+    // Valid, 'Cup<S>' has 'copy' because 'S' has 'copy'
+    let c_s2 = copy c_s;
+}
+
+fun invalid(c_account: Cup<signer>, c_n: Cup<NoAbilities>) {
+    // Invalid, 'Cup<signer>' does not have 'copy'.
+    // Even though 'Cup' was declared with copy, the instance does not have 'copy'
+    // because 'signer' does not have 'copy'
+    let c_account2 = copy c_account;
+    // Invalid, 'Cup<NoAbilities>' does not have 'copy'
+    // because 'NoAbilities' does not have 'copy'
+    let c_n2 = copy c_n;
+}
+```
+
+### Example: conditional `drop`
+
+```move
+struct NoAbilities {}
+struct S has copy, drop { f: bool }
+struct Cup<T> has copy, drop, store { item: T }
+
+fun unused() {
+    Cup<bool> { item: true }; // Valid, 'Cup<bool>' has 'drop'
+    Cup<S> { item: S { f: false }}; // Valid, 'Cup<S>' has 'drop'
+}
+
+fun left_in_local(c_account: Cup<signer>): u64 {
+    let c_b = Cup<bool> { item: true };
+    let c_s = Cup<S> { item: S { f: false }};
+    // Valid return: 'c_account', 'c_b', and 'c_s' have values
+    // but 'Cup<signer>', 'Cup<bool>', and 'Cup<S>' have 'drop'
+    0
+}
+
+fun invalid_unused() {
+    // Invalid, Cannot ignore 'Cup<NoAbilities>' because it does not have 'drop'.
+    // Even though 'Cup' was declared with 'drop', the instance does not have 'drop'
+    // because 'NoAbilities' does not have 'drop'
+    Cup<NoAbilities> { item: NoAbilities {}};
+}
+
+fun invalid_left_in_local(): u64 {
+    let n = Cup<NoAbilities> { item: NoAbilities {}};
+    // Invalid return: 'n' has a value
+    // and 'Cup<NoAbilities>' does not have 'drop'
+    0
+}
+```
+
+### Example: conditional `store`
+
+```move
+struct Cup<T> has copy, drop, store { item: T }
+
+// 'MyInnerResource' is declared with 'store' so all fields need 'store'
+struct MyInnerResource has store {
+    yes: Cup<u64>, // Valid, 'Cup<u64>' has 'store'
+    // no: Cup<signer>, Invalid, 'Cup<signer>' does not have 'store'
+}
+
+// 'MyResource' is declared with 'key' so all fields need 'store'
+struct MyResource has key {
+    yes: Cup<u64>, // Valid, 'Cup<u64>' has 'store'
+    inner: Cup<MyInnerResource>, // Valid, 'Cup<MyInnerResource>' has 'store'
+    // no: Cup<signer>, Invalid, 'Cup<signer>' does not have 'store'
+}
+```
+
+### Example: conditional `key`
+
+```move
+struct NoAbilities {}
+struct MyResource<T> has key { f: T }
+
+fun valid(account: &signer) acquires MyResource {
+    let addr = signer::address_of(account);
+     // Valid, 'MyResource<u64>' has 'key'
+    let has_resource = exists<MyResource<u64>>(addr);
+    if (!has_resource) {
+         // Valid, 'MyResource<u64>' has 'key'
+        move_to(account, MyResource<u64> { f: 0 })
+    };
+    // Valid, 'MyResource<u64>' has 'key'
+    let r = borrow_global_mut<MyResource<u64>>(addr)
+    r.f = r.f + 1;
+}
+
+fun invalid(account: &signer) {
+   // Invalid, 'MyResource<NoAbilities>' does not have 'key'
+   let has_it = exists<MyResource<NoAbilities>>(addr);
+   // Invalid, 'MyResource<NoAbilities>' does not have 'key'
+   let NoAbilities {} = move_from<NoAbilities>(addr);
+   // Invalid, 'MyResource<NoAbilities>' does not have 'key'
+   move_to(account, NoAbilities {});
+   // Invalid, 'MyResource<NoAbilities>' does not have 'key'
+   borrow_global<NoAbilities>(addr);
+}
+```