Merge remote-tracking branch 'origin/main' into github-pages

Author: dumindu

content/en/docs/a8.primitive-data-types.md

@@ -156,7 +156,15 @@ let (b, c) = a; // b = 1, c = 1.5
 
 let a = (1, 1.5, true, 'a');
 let (b, _, _, c) = a; // b = 1, c = 'a'
+let (b, .., c) = a; // b = 1, c = 'a'
 
+let a = (1, 2, 3, true, false, 'a', 'b', 'c');
+let (b, ..) = a; // b = 1
+let (.., c) = a; // c = 'c'
+let (e, f, g, .., h, i, j) = a; // 1 2 3 'a' 'b' 'c'
+```
+
+```rust
 // Nesting
 let a = (1, 1.5);
 let b = (a, (2, 4), 6); // ((1, 1.5), (2, 4), 6)
@@ -284,14 +292,14 @@ We can check the default byte sizes of data types via `std::mem::size_of`. For e
 
 - Other than adding the type annotations to the variables, **for numeric types**, we can append the data type directly to the value as the suffix. Also, to improve the readability of long numbers, we can use `_` as a divider.
 
-```rust
-let a = 5i8; // Equals to `let a: i8 = 5;`
+  ```rust
+  let a = 5i8; // Equals to `let a: i8 = 5;`
 
-let b = 100_000_000; // Equals to `let b = 100000000;`
-// 💡 The placements of _s are not strict. ex. 10000_0000 is also valid.
+  let b = 100_000_000; // Equals to `let b = 100000000;`
+  // 💡 The placements of _s are not strict. ex. 10000_0000 is also valid.
 
-let pi = 3.141_592_653_59_f64; // Equals to `let pi: f64 = 3.14159265359`
-// 💡 make sure group digits consistently by underscores avoid warnings
+  let pi = 3.141_592_653_59_f64; // Equals to `let pi: f64 = 3.14159265359`
+  // 💡 make sure group digits consistently by underscores avoid warnings
 
-const PI: f64 = 3.141_592_653_59; // In the constants and statics, the data type must be annotated in the beginning.
-```
+  const PI: f64 = 3.141_592_653_59; // In the constants and statics, the data type must be annotated in the beginning.
+  ```

content/en/docs/a9.operators.md

@@ -152,20 +152,20 @@ println!("{} {}", a.0, a.1); // 2 Tim
 
 - About **string concatenation**,
 
-```rust
-let (s1, s2) = ("abc", "123"); // both &str
-// All bellow codes return abc123 (in String data type)
+  ```rust
+  let (s1, s2) = ("abc", "123"); // both &str
+  // All bellow codes return abc123 (in String data type)
 
-// 1. via + operator
-let s = String::from(s1) + s2; // String + &str
+  // 1. via + operator
+  let s = String::from(s1) + s2; // String + &str
 
-// 2. via push_str method
-let mut s = String::from(s1);
-s.push_str(s2); // String + &str
+  // 2. via push_str method
+  let mut s = String::from(s1);
+  s.push_str(s2); // String + &str
 
-// 3. via format! macro
-let s = format!("{s1}{s2}"); // &str/String + &str/String
+  // 3. via format! macro
+  let s = format!("{s1}{s2}"); // &str/String + &str/String
 
-// 4. via concat method
-let s = [s1, s2].concat(); // &str or String array
-```
+  // 4. via concat method
+  let s = [s1, s2].concat(); // &str or String array
+  ```

content/en/docs/b3.enums.md

@@ -10,8 +10,6 @@ slug: enums
   - Unnamed ordered data (a tuple variant)
   - Named data (a struct variant)
 
-> 💡In other words, any type of valid struct (unit, tuple, c-like) can be used as an enum variant.
-
 ## Definition
 
 ### With Unit Variants
@@ -34,15 +32,17 @@ enum Day {
 ```rust
 enum FlashMessage {
     Success, // 💡 A unit variant (no data)
-    Error(u8, String), // 💡 A tuple variant (One/more , separated data)
-    Warning { field: String, message: String }, // 💡 A struct variant (One/more , separated name: value data)
+    Error(u8, String), // 💡 A tuple variant (one or more , separated data)
+    Warning { field: String, message: String }, // 💡 A struct variant (one or more , separated name: value data)
 }
 ```
 
 ## Initialization
 
+### With Different Kinds of Variants
+
 ```rust
-#[allow(dead_code)] // 💡 Remove dead_code warnings, as we don't access the elements of variants.
+#![allow(dead_code)] // 💡 Remove dead_code warnings, as we don't access the elements of variants.
 
 #[derive(Debug)]
 enum FlashMessage {
@@ -67,6 +67,25 @@ fn main() {
 }
 ```
 
+### With a Default Variant
+
+```rust
+#[derive(Default)]
+enum Hand {
+    Left,
+    #[default] // 💡Set Right as the default variant
+    Right,
+},
+
+fn main() {
+    let a = Hand::default(); // Initialization with the default variant
+
+    assert_eq!(a, Hand::Right); // Hand default value is Right
+}
+
+// 💡 #[derive(Default)] attribute automatically generates a default implementation for the Default trait for a struct or enum.
+```
+
 ## Pattern Matching & Destructuring
 
 ### By `match`
@@ -97,9 +116,8 @@ fn main() {
 ```
 
 ```rust
-#[allow(dead_code)] // 💡 Remove dead_code warnings, as we don't access all elements of the variants.
+#![allow(dead_code)] // 💡 Remove dead_code warnings, as we don't access all elements of the variants.
 
-#[derive(Debug)]
 enum FlashMessage {
     Success,
     Error(u32, String),
@@ -124,7 +142,6 @@ fn main() {
 ```rust
 #![allow(dead_code)] // 💡 Remove dead_code warnings, as we don't access the all elements of variants.
 
-#[derive(Debug)]
 enum FlashMessage {
     Success,
     Error(u32, String),

content/en/docs/b4.generics.md

@@ -3,128 +3,157 @@ title: Generics
 slug: generics
 ---
 
-> [📖](https://doc.rust-lang.org/beta/book/first-edition/generics.html) Sometimes, when writing a function or data type, we may want it to work for multiple types of arguments. In Rust, we can do this with generics.
+The core concept of Rust generics is abstraction over types. In other words, we can write code that can operate on any data type without specifying the exact type but uppercase letter (or [PascalCase](https://en.wikipedia.org/wiki/Camel_case) identifier). In the compile time Rust ensures the type safety and generates optimized code for each concrete type used in the code.
 
-💭 The concept is, instead of declaring a specific data type we use an uppercase letter(or [PascalCase](https://en.wikipedia.org/wiki/Camel_case) identifier). ex, **instead of x : u8** we use **x : T** . but we have to inform to the compiler that T is a generic type(can be any type) by adding `<T>` at first.
+For example, 
+- Instead of `x: u8` we use **`x: T`**. 
+- And inform the compiler that `T` is a generic type (can be any type) by adding **`<T>`** at first.
 
-## Generalizing functions
+> 💡 Using T, U, V ... as generic type names is quite a convention. We can use any PascalCase names as well.
+
+## Functions
+
+### With One Generic Type
+
+💡 For simplicity, `fn first` accepts two arguments of the same type `T` and returns the first argument. As we don't use the second argument in the function, we prefix it with `_`, to prevent `unused_variables` warning.
 
 ```rust
-fn takes_anything<T>(x: T) { // x has type T, T is a generic type
+fn first<T>(x: T, _y: T) -> T { // 💡 Instead of specific type, we use T and add <T> at first
+    x
 }
 
-fn takes_two_of_the_same_things<T>(x: T, y: T) { // Both x and y has the same type
+fn main() {
+    let a: i8 = first(0, -1);
+    let b: i32 = first(1, 2);
+    let c: bool = first(true, false);
+    let d: String = first("01".to_string(), "02".to_string());
+
+    println!("{a} {b} {c} {d}"); // 0 1 true 01
 }
+```
+
+### With Multiple Generic Types
+
+```rust
+fn first<T, U>(x: T, _y: U) -> T {
+    x
+}
+
+fn main() {
+    let a: i8 = first(0i8, -1i32); // x: i8, y: i32
+    let b: i32 = first(1i32, 2i64); // x: i32, y: i64
+
+    let c: bool = first(true, false); // x: bool, y: bool 
+    // ⭐️ Even funtions with multiple generic types, we can have same type.
 
-fn takes_two_things<T, U>(x: T, y: U) { // Multiple types
+    println!("{a} {b} {c}"); // 0 1 true
 }
 ```
 
-## Generalizing structs
+### With Trait Bounds
+
+`{}` requires the `std::fmt::Display` trait and `{:?}` requires the `std::fmt::Debug` trait. We have to set `T: Display` or `T: Debug` or both `T: Display + Debug` to tell the compiler that `T` satisfy the requirements for either operation.
 
 ```rust
-struct Point<T> {
-  x: T,
-  y: T,
+use std::fmt::{Debug, Display};
+
+fn print_together<T: Display + Debug>(x: T, y: T) {
+    println!("{} {:?}", x, y);
 }
 
 fn main() {
-  let point_a = Point { x: 0, y: 0 }; // T is a int type
-  let point_b = Point { x: 0.0, y: 0.0 }; // T is a float type
+    print_together(0, 1); // 0 1
+    print_together("001", "002"); // 001 "002"
 }
+```
+
+## With Structs
+
+```rust
+use std::fmt::Display;
+
+struct Point<T: Display> {
+    x: T,
+    y: T,
+}
+
+fn main() {
+    let a = Point { x: 0_i8, y: 1 }; // x, y: i8
+    let b = Point { x: 0.0001_f64, y: 0.0002 }; // x, y: f64
 
-// 🔎 When adding an implementation for a generic struct, the type parameters should be declared after the impl as well
-//   impl<T> Point<T> {
+    println!("{} {}", a.x, a.y); // 0 1
+    println!("{} {}", b.x, b.y); // 0.0001 0.0002
+}
 ```
 
-## Generalizing enums
+💯 When adding an implementation for a generic struct, the type parameters should be declared after the impl as well. Ex, `impl<T> Point<T>`
+
+## With Enums
 
 ```rust
-enum Option<T> {
+// An output can have either Some value or no value/ None.
+enum Option<T> { // T is a generic and it can contain any type of value.
     Some(T),
     None,
 }
 
-enum Result<T, E> {
+// A result can represent either success/ Ok or failure/ Err.
+enum Result<T, E> { // T and E are generics. T can contain any type of value, E can be any error.
     Ok(T),
     Err(E),
 }
 ```
 
-> ⭐️ Above [Option](https://doc.rust-lang.org/std/option/index.html) and [Result](https://doc.rust-lang.org/std/result/index.html) types are kind of special generic types which are already defined in Rust’s standard library. 
-> - An **optional value** can have either **Some** value or no value/ **None**.
-> - A **result** can represent either success/ **Ok** or failure/ **Err**
+⭐️ [Option](https://doc.rust-lang.org/std/option/index.html) and [Result](https://doc.rust-lang.org/std/result/index.html) types are kind of special generic types which are already defined in Rust’s standard library.
+- An **optional value** can have either **Some** value or no value/ **None**. Express the possibility of absence.
+- A **result** can represent either success/ **Ok** or failure/ **Err**. Expresses the possibility of failure.
 
-### Usages of Option
- 
-```rust
-// 01 - - - - - - - - - - - - - - - - - - - - - -
-fn get_id_by_username(username: &str) -> Option<usize> {
-    // if username can be found in the system, set userId
-        return Some(userId);
-    // else
-        None
-}
-
-// 💭 So, on the above function, instead of setting return type as usize
-//   set return type as Option<usize>
-// Instead of return userId, return Some(userId)
-//   else None (💡remember? last return statement no need return keyword and ending ;)
+### Option
 
-// 02 - - - - - - - - - - - - - - - - - - - - - -
+```rust
 struct Task {
     title: String,
-    assignee: Option<Person>,
+    assignee: Option<Person>, // 💡 Instead of `assignee: Person`, we use `assignee: Option<Person>` as the assignee can be `None`.
 }
+```
+ 
+```rust
+fn get_id_by_username(username: &str) -> Option<usize> { // 💡 Instead of setting return type as `usize`, set it `Option<usize>`
+    // if username can be found in the system, return userId
+        return Some(userId); // 💡 Instead of return userId, return Some(userId)
 
-// 💭 Instead of assignee: Person, we use Option<Person>
-// because the task has not been assigned to a specific person
-
-// - - - - - - - - - - - - - - - - - - - - - - -
-// When using Option types as return types on functions
-// we can use pattern matching to catch the relevant return type(Some/None) when calling them
+    // else
+        None // 💡 The last return statement no need `return` keyword and ending `;`
+}
 
 fn main() {
     let username = "anonymous";
-    match get_id_by_username(username) {
+    match get_id_by_username(username) { // 💡 We can use pattern matching to catch the relevant return type (Some/None)
         None => println!("User not found"),
-        Some(i) => println!("User Id: {}", i)
+        Some(i) => println!("User Id: {}", i),
     }
 }
 ```
 
-### Usages of Result
- 
-> [📖](https://doc.rust-lang.org/book/first-edition/error-handling.html) The Option type is a way to use Rust’s type system to express the possibility of absence. Result expresses the possibility of error.
+### Result
 
 ```rust
-// - - - - - - - - - - - - - - - - - - - - - -
-fn get_word_count_from_file(file_name: &str) -> Result<u32, &str> {
-  // if the file is not found on the system, return error
-    return Err("File can not be found!")
-  // else, count and return the word count
-    // let mut word_count: u32; ....
-    Ok(word_count)
-}
+fn get_word_count_from_file(file_name: &str) -> Result<u32, &str> { // 💡 Instead of setting return type as `u32`, set it `Result<u32, &str>`
+    // if the file is not found on the system, return error
+        return Err("File can not be found!"); // 💡 Instead panic/ break when the file can not be found; return Err(something)
 
-// 💭 On the above function,
-// instead panic(break) the app, when the file can not be found; return Err(something)
-// or when it could get the relevant data; return Ok(data)
-
-
-// - - - - - - - - - - - - - - - - - - - - - - -
-// We can use pattern matching to catch the relevant return type(Ok/Err) when calling it
+    // else, count and return the word count
+        Ok(word_count) // 💡 Instead of return `word_count`, return `Ok(word_count)`
+        // 💡 The last return statement no need `return` keyword and ending `;`
+}
 
 fn main() {
     let mut file_name = "file_a";
-    match get_word_count_from_file(file_name) {
+    match get_word_count_from_file(file_name) { // 💡 We can use pattern matching to catch the relevant return type (Ok/Err)
         Ok(i) => println!("Word Count: {}", i),
         Err(e) => println!("Error: {}", e)
     }
 }
 ```
 
-
-> 🔎 Many useful methods have been implemented around Option and Result types. More information can be found on [std::option::Option](https://doc.rust-lang.org/std/option/enum.Option.html) and [std::result::Result](https://doc.rust-lang.org/std/result/enum.Result.html) pages on Rust doc.
-
-⭐️ Also **more practical examples** of options & results can be found on [Error Handling](https://doc.rust-lang.org/book/first-edition/error-handling.html) section in  Rust doc.
+💭 This is a quick reference about the `Option` and `Result` as enums. Please don’t worry about them much now, as we will discuss them later.