From da42be6885abbfccca9458b748a013086fdd2507 Mon Sep 17 00:00:00 2001 From: Nenad Date: Fri, 1 Nov 2024 13:12:57 +0100 Subject: [PATCH] Extract Option concept --- concepts/enums/about.md | 88 ------------------------------ concepts/enums/links.json | 4 -- concepts/option/.meta/config.json | 7 +++ concepts/option/about.md | 88 ++++++++++++++++++++++++++++++ concepts/option/introduction.md | 4 ++ concepts/option/links.json | 10 ++++ concepts/options/.meta/config.json | 7 --- concepts/options/about.md | 1 - concepts/options/introduction.md | 1 - concepts/options/links.json | 1 - config.json | 8 +-- 11 files changed, 113 insertions(+), 106 deletions(-) create mode 100644 concepts/option/.meta/config.json create mode 100644 concepts/option/about.md create mode 100644 concepts/option/introduction.md create mode 100644 concepts/option/links.json delete mode 100644 concepts/options/.meta/config.json delete mode 100644 concepts/options/about.md delete mode 100644 concepts/options/introduction.md delete mode 100644 concepts/options/links.json diff --git a/concepts/enums/about.md b/concepts/enums/about.md index 37731d4f..a4088a6c 100644 --- a/concepts/enums/about.md +++ b/concepts/enums/about.md @@ -113,92 +113,4 @@ msg.process(); // prints "quitting" In many situations, enums can come in handy especially when used with the `match` flow as used above in the traits implementation. Read more about the `match` flow in [The Cairo Book][match]. -## The `Option` Enum and Its Advantages - -The `Option` enum is a standard Cairo enum that represents the concept of an optional value. -It has two variants: `Some: T` and `None`. -`Some` variant has an associated value of type `T`, while `None` represents the absence of an associated value. - -```rust -enum Option { - Some: T, - None, -} -``` - -The `Option` enum is helpful because it allows you to explicitly represent the possibility of a value being absent, making your code more expressive and easier to reason about. -Using `Option` can also help prevent bugs caused by using uninitialized or unexpected `null` values. - -The function below shows how the `Option` enum is used to return the index of the first element of an array with a given value, or return `None` if the element is absent. - -```rust -fn find_value(mut arr: Span, value: felt252) -> Option { - let mut result = Option::None; - let mut index = 0; - - while let Option::Some(array_value) = arr - .pop_front() { - if (*array_value == value) { - result = Option::Some(index); - break; - }; - - index += 1; - }; - - result -} -``` - -## Concise Control Flow with `if let` and `while let` - -The `if let` syntax combines `if` and `let` to handle specific pattern matches more concisely. - -Using `match` to handle an `Option`: - -```rust -let config_max: Option = Option::Some(5); -match config_max { - Option::Some(max) => println!("The maximum is configured to be {}", max), - _ => (), -} -``` - -Using `if let` for the same logic: - -```rust -let number: Option = Option::Some(5); -if let Option::Some(max) = number { - println!("The maximum is configured to be {}", max); -} -``` - -You can also include an `else` with `if let`: - -```rust -let coin: Coin = Coin::Quarter; -if let Coin::Quarter = coin { - println!("You got a quarter!"); -} else { - println!("You got some other coin!"); -} -``` - -The `while let` syntax loops over `Option` values, executing a block for each matching pattern. - -```rust -fn main() { - let mut arr: Array = array![1, 2, 3, 4, 5, 6, 7, 8, 9]; - let mut sum: felt252 = 0; - while let Option::Some(value) = arr.pop_front() { - sum += value; - } - println!("{}", sum); -} -``` - -There are other native enums, one of which is the `Result` enum, which allows for graceful error handling. -Read more about the `Result` enum in [The Cairo Book][results]. - [match]: https://book.cairo-lang.org/ch06-02-the-match-control-flow-construct.html -[results]: https://book.cairo-lang.org/ch09-02-recoverable-errors.html#the-result-enum diff --git a/concepts/enums/links.json b/concepts/enums/links.json index 77fae044..c66e0047 100644 --- a/concepts/enums/links.json +++ b/concepts/enums/links.json @@ -6,9 +6,5 @@ { "url": "https://starknet-by-example.voyager.online/getting-started/cairo_cheatsheet/enums.html", "description": "Starknet by Example section on Enums" - }, - { - "url": "https://book.cairo-lang.org/ch06-03-concise-control-flow-with-if-let-and-while-let.html", - "description": "A section in the Cairo programming language book that discusses control flow with `if let` and `while let`" } ] diff --git a/concepts/option/.meta/config.json b/concepts/option/.meta/config.json new file mode 100644 index 00000000..7f998b49 --- /dev/null +++ b/concepts/option/.meta/config.json @@ -0,0 +1,7 @@ +{ + "blurb": "Option: a T which may or may not be there", + "authors": [ + "0xNeshi" + ], + "contributors": [] +} \ No newline at end of file diff --git a/concepts/option/about.md b/concepts/option/about.md new file mode 100644 index 00000000..a105f800 --- /dev/null +++ b/concepts/option/about.md @@ -0,0 +1,88 @@ +# Options + +The `Option` enum is a standard Cairo enum that represents the concept of an optional value. +It has two variants: `Some: T` and `None`. +`Some` variant has an associated value of type `T`, while `None` represents the absence of an associated value. + +```rust +enum Option { + Some: T, + None, +} +``` + +The `Option` enum is helpful because it allows you to explicitly represent the possibility of a value being absent, making your code more expressive and easier to reason about. +Using `Option` can also help prevent bugs caused by using uninitialized or unexpected `null` values. + +The function below shows how the `Option` enum is used to return the index of the first element of an array with a given value, or return `None` if the element is absent. + +```rust +fn find_value(mut arr: Span, value: felt252) -> Option { + let mut result = Option::None; + let mut index = 0; + + while let Option::Some(array_value) = arr + .pop_front() { + if (*array_value == value) { + result = Option::Some(index); + break; + }; + + index += 1; + }; + + result +} +``` + +## Concise Control Flow with `if let` and `while let` + +The `if let` syntax combines `if` and `let` to handle specific pattern matches more concisely. + +Using `match` to handle an `Option`: + +```rust +let config_max: Option = Option::Some(5); +match config_max { + Option::Some(max) => println!("The maximum is configured to be {}", max), + _ => (), +} +``` + +Using `if let` for the same logic: + +```rust +let number: Option = Option::Some(5); +if let Option::Some(max) = number { + println!("The maximum is configured to be {}", max); +} +``` + +You can also include an `else` with `if let`: + +```rust +let coin: Coin = Coin::Quarter; +if let Coin::Quarter = coin { + println!("You got a quarter!"); +} else { + println!("You got some other coin!"); +} +``` + +The `while let` syntax loops over `Option` values, executing a block for each matching pattern. + +```rust +fn main() { + let mut arr: Array = array![1, 2, 3, 4, 5, 6, 7, 8, 9]; + let mut sum: felt252 = 0; + while let Option::Some(value) = arr.pop_front() { + sum += value; + } + println!("{}", sum); +} +``` + +There are other native enums, one of which is the `Result` enum, which allows for graceful error handling. +Read more about the `Result` enum in [The Cairo Book][results]. + +[results]: https://book.cairo-lang.org/ch09-02-recoverable-errors.html#the-result-enum diff --git a/concepts/option/introduction.md b/concepts/option/introduction.md new file mode 100644 index 00000000..d9842f87 --- /dev/null +++ b/concepts/option/introduction.md @@ -0,0 +1,4 @@ +# Introduction + +The standard library provides an enum called `Option` to help you express when a value may or may not exist. +You'll see it referred to as `Option` where `T` is the type of the value you are working with. diff --git a/concepts/option/links.json b/concepts/option/links.json new file mode 100644 index 00000000..0fbbd840 --- /dev/null +++ b/concepts/option/links.json @@ -0,0 +1,10 @@ +[ + { + "url": "https://book.cairo-lang.org/ch06-01-enums.html#the-option-enum-and-its-advantages", + "description": "The Option enum in The Cairo book" + }, + { + "url": "https://book.cairo-lang.org/ch06-03-concise-control-flow-with-if-let-and-while-let.html", + "description": "A section in the Cairo programming language book that discusses control flow with `if let` and `while let`" + } +] diff --git a/concepts/options/.meta/config.json b/concepts/options/.meta/config.json deleted file mode 100644 index 35b1d32b..00000000 --- a/concepts/options/.meta/config.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "blurb": "", - "authors": [ - "" - ], - "contributors": [] -} diff --git a/concepts/options/about.md b/concepts/options/about.md deleted file mode 100644 index f607e58e..00000000 --- a/concepts/options/about.md +++ /dev/null @@ -1 +0,0 @@ -# Options diff --git a/concepts/options/introduction.md b/concepts/options/introduction.md deleted file mode 100644 index e10b99d0..00000000 --- a/concepts/options/introduction.md +++ /dev/null @@ -1 +0,0 @@ -# Introduction diff --git a/concepts/options/links.json b/concepts/options/links.json deleted file mode 100644 index fe51488c..00000000 --- a/concepts/options/links.json +++ /dev/null @@ -1 +0,0 @@ -[] diff --git a/config.json b/config.json index 2229d4a4..028b5cb6 100644 --- a/config.json +++ b/config.json @@ -214,7 +214,7 @@ "name": "Role Playing Game", "uuid": "1b014752-c3a4-4250-9483-89696864461b", "concepts": [ - "options" + "option" ], "prerequisites": [ "structs", @@ -230,7 +230,7 @@ "type-conversion" ], "prerequisites": [ - "options", + "option", "printing" ], "status": "wip" @@ -918,8 +918,8 @@ }, { "uuid": "0bd2a321-f169-49a9-83d6-7d91193db915", - "slug": "options", - "name": "Options" + "slug": "option", + "name": "Option" }, { "uuid": "c11a8aa5-cda4-4d02-a477-3db3d3ca5acf",