Skip to content

Commit 958b230

Browse files
codekilncodekiln
committed
docs: Update Rust documentation with new concepts and examples
- Added new pages for Destructuring, Two's Complement, and Zero Indexing - Enhanced existing documentation with additional examples and clarifications - Updated Rust variable documentation to include new types and shadowing concepts
1 parent d3fa87a commit 958b230

18 files changed

+337
-10
lines changed

‎journals/2025_11_27.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
- [[Rust/crate/rand/Rng]]
1616
- [[cargo/doc/--open]] can build the documentation for your deps and open it in your browser. Cool!
1717
- [[Rust/match]]
18-
- [[Programming/Pattern Matching]] - created general pattern matching concept documentation
19-
- [[Programming/Time/Compile]] and [[Programming/Time/Run]] - created documentation for compile-time and runtime execution phases
18+
- [[Programming/Pattern Matching]]
19+
- [[Programming/Destructuring]] - created general destructuring concept documentation
20+
- [[Programming/Zero Indexing]] - created documentation for zero-based indexing concept
2021
-

‎journals/2025_11_28.md‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,18 @@
11
## Rust Study
22
- ### [[Rust/Book/TRPL/Interactive]]
3-
- [[Rust/Variable/Constant]]
3+
- [[Rust/Variable]]
4+
- [[Rust/Variable/let]]
5+
- [[Rust/mut]]
6+
- [[Rust/Variable/Constant]]
7+
- [[Rust/Variable/Shadowing]]
8+
- [[Programming/Time/Compile]] and [[Programming/Time/Run]]
9+
- [[Rust/Variable/Type/Scalar/Integer]]
10+
- [[Programming/Two's Complement]] - binary representation
11+
- [[Programming/Two's Complement/Wrapping]]
12+
- [[Rust/Variable/Type/Scalar/Floating-Point]]
13+
- [[Rust/Variable/Type/Scalar/Boolean]]
14+
- [[Rust/Variable/Type/Scalar/Character]]
15+
- [[Rust/Variable/Type/Compound]]
16+
- [[Rust/Variable/Type/Compound/Tuple]]
17+
- [[Programming/Zero Indexing]]
18+
-

‎pages/Programming___Destructuring.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
- # Destructuring
2+
- Also known as: unpacking, destructuring assignment
3+
- A programming concept that allows unpacking values from data structures (arrays, objects, tuples, structs) into distinct variables
4+
- Simplifies the extraction of multiple values and enhances code readability
5+
- ## Overview
6+
- Enables developers to extract multiple values from data structures in a concise and readable manner
7+
- Particularly useful when dealing with complex data structures or when functions return multiple values
8+
- Reduces boilerplate code when accessing multiple properties or elements
9+
- ## Language Implementations
10+
- ### JavaScript
11+
- Destructuring assignment allows unpacking values from arrays or properties from objects
12+
- Array destructuring:
13+
- ~~~javascript
14+
const [first, second] = [1, 2];
15+
~~~
16+
- Object destructuring:
17+
- ~~~javascript
18+
const { name, age } = { name: 'Alice', age: 25 };
19+
~~~
20+
- ### Python
21+
- Tuple unpacking enables assigning values from tuples or lists to variables
22+
- Tuple unpacking:
23+
- ~~~python
24+
first, second = (1, 2)
25+
~~~
26+
- Dictionary unpacking (using unpacking operator):
27+
- ~~~python
28+
person = {'name': 'Alice', 'age': 25}
29+
name, age = person['name'], person['age']
30+
# Or with unpacking:
31+
{name, age} = person # Python 3.8+
32+
~~~
33+
- ### Rust
34+
- Pattern matching facilitates destructuring of tuples, structs, and enums
35+
- Tuple destructuring:
36+
- ~~~rust
37+
let (x, y) = (1, 2);
38+
~~~
39+
- Struct destructuring:
40+
- ~~~rust
41+
struct Point { x: i32, y: i32 }
42+
let point = Point { x: 3, y: 4 };
43+
let Point { x, y } = point;
44+
~~~
45+
- ## Benefits
46+
- ### Improved Readability
47+
- Provides a clear and concise way to extract values
48+
- Makes code easier to understand
49+
- ### Reduced Boilerplate
50+
- Eliminates the need for repetitive code when accessing multiple properties or elements
51+
- Reduces verbosity in variable assignments
52+
- ### Enhanced Maintainability
53+
- Simplifies variable assignments
54+
- Makes code maintenance more straightforward
55+
- ## Advanced Features
56+
- ### Default Values
57+
- Some languages allow setting default values during destructuring to handle undefined or missing properties
58+
- Example (JavaScript):
59+
- ~~~javascript
60+
const { name = 'Unknown', age = 0 } = person;
61+
~~~
62+
- ### Nested Destructuring
63+
- Can be applied to nested data structures
64+
- May increase complexity and reduce readability if overused
65+
- Example (JavaScript):
66+
- ~~~javascript
67+
const { user: { name, email } } = data;
68+
~~~
69+
- ### Rest/Spread Patterns
70+
- Some languages support collecting remaining elements
71+
- Example (JavaScript):
72+
- ~~~javascript
73+
const [first, ...rest] = [1, 2, 3, 4];
74+
~~~
75+
- ## Related
76+
- [[Programming/Pattern Matching]] - Destructuring is often used with pattern matching
77+
- [[Rust/Variable/Type/Compound/Tuple]] - Tuple destructuring in Rust
78+
- Variable assignment and binding
79+

‎pages/Programming___Two's Complement.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
- # [Two's Complement](https://en.wikipedia.org/wiki/Two%27s_complement)
2+
- A mathematical operation on binary numbers and the most common method for representing signed integers in computing
3+
- Simplifies arithmetic operations and eliminates the issue of having two representations for zero
4+
- ## Overview
5+
- The most significant bit (MSB) indicates the sign of the number:
6+
- `0` for positive numbers
7+
- `1` for negative numbers
8+
- Positive numbers are represented as usual in binary
9+
- Negative numbers are represented by inverting all bits of their absolute value (one's complement) and adding one to the least significant bit (LSB)
10+
- ## Range
11+
- For an n-bit binary number:
12+
- The range of representable integers is from `-2^(n-1)` to `2^(n-1) - 1`
13+
- For example, an 8-bit system can represent integers from `-128` to `127`
14+
- ## Advantages
15+
- ### Single Zero Representation
16+
- Unlike one's complement, which has both `00000000` and `11111111` representing zero, two's complement has a unique representation (`00000000`)
17+
- ### Simplified Arithmetic
18+
- Addition, subtraction, and multiplication operations are the same for both signed and unsigned numbers
19+
- Simplifies hardware design
20+
- No need for separate signed and unsigned arithmetic circuits
21+
- ## Converting to Two's Complement
22+
- To find the two's complement of a binary number:
23+
- 1. Invert all bits (one's complement)
24+
- 2. Add one to the LSB
25+
- ### Example: Representing -5 in 8-bit
26+
- Start with the binary representation of `5`: `00000101`
27+
- Invert all bits: `11111010`
28+
- Add one: `11111011`
29+
- Thus, `-5` is represented as `11111011` in 8-bit two's complement
30+
- ## Arithmetic Operations
31+
- ### Addition
32+
- Add the binary numbers directly
33+
- If there's a carry out of the MSB, it's discarded
34+
- ### Subtraction
35+
- Convert the number to be subtracted into its two's complement
36+
- Add it to the other number
37+
- ### Example: Computing 5 - 3 in 4-bit
38+
- Represent `5`: `0101`
39+
- Represent `3`: `0011`
40+
- Find two's complement of `3`:
41+
- Invert bits: `1100`
42+
- Add one: `1101`
43+
- Add `5` and `-3`:
44+
- `0101` + `1101` = `10010`
45+
- Discard the carry: `0010` (which is `2` in decimal)
46+
- ## Sign Extension
47+
- When increasing the number of bits (e.g., from 8-bit to 16-bit), the sign bit (MSB) is extended to preserve the number's value
48+
- **Positive numbers**: Pad with `0`s
49+
- **Negative numbers**: Pad with `1`s
50+
- ### Example
51+
- Extending `-5` (`11111011` in 8-bit) to 16-bit: `11111111 11111011`
52+
- ## Historical Context
53+
- The concept of two's complement has been integral to computer arithmetic since the mid-20th century
54+
- Notably utilized in early computers like the IBM System/360, introduced in 1964
55+
- This contributed to its widespread adoption in the computing industry
56+
- ## Related
57+
- Binary number representation
58+
- Signed integer representation
59+
- Computer arithmetic
60+
- Hardware design
61+

‎pages/Programming___Two's Complement___Wrapping.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
- values greater than the maximum value the type can hold “wrap around” to the minimum of the values the type can hold. In the case of a `u8`, the value 256 becomes 0, the value 257 becomes 1, and so on.

‎pages/Programming___Zero Indexing.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
- # [Zero-Based Indexing](https://en.wikipedia.org/wiki/Zero-based_numbering)
2+
- Also known as: zero indexing, zero-based numbering
3+
- A fundamental concept in computer science and programming where the first element of a sequence (array, list, tuple, etc.) is assigned the index 0, the second element the index 1, and so on
4+
- ## Overview
5+
- The first element is at index 0
6+
- The second element is at index 1
7+
- The nth element is at index n-1
8+
- Contrasts with one-based indexing, where the first element is assigned the index 1
9+
- ## Rationale
10+
- ### Memory Address Calculation
11+
- An array's name refers to the address of its first element
12+
- The index represents an offset from this base address
13+
- In C, the expression `array[i]` is equivalent to `*(array + i)`
14+
- The element at index `i` is located at the memory address `array` plus `i` times the size of each element
15+
- Starting the index at 0 simplifies this calculation, as the first element is at the base address with an offset of zero
16+
- ### Simplified Range Calculations
17+
- When defining ranges or performing calculations involving indices, zero-based indexing often leads to cleaner expressions
18+
- The length of a sequence can be directly used as the upper bound in loops without additional adjustments
19+
- Example: A loop from 0 to length-1 is more straightforward than from 1 to length
20+
- ## Advantages
21+
- **Simplified Calculations**: Cleaner and more intuitive expressions for ranges and loops
22+
- **Alignment with Memory Addressing**: Aligns with the way memory addresses are computed, leading to more efficient pointer arithmetic
23+
- **Widespread Adoption**: Used by most modern programming languages
24+
- ## Programming Languages Using Zero-Based Indexing
25+
- C
26+
- C++
27+
- Java
28+
- Python
29+
- JavaScript
30+
- Go
31+
- Swift
32+
- Kotlin
33+
- Rust
34+
- ## Contrast with One-Based Indexing
35+
- Some languages, particularly those used in scientific computing, prefer one-based indexing to align with traditional mathematical notation
36+
- Examples:
37+
- Fortran
38+
- MATLAB
39+
- R
40+
- In these languages, the first element of a sequence is accessed with index 1
41+
- Can be more intuitive for users familiar with mathematical conventions
42+
- ## Examples
43+
- ### Zero-Based (Most Languages)
44+
- First element: `array[0]`
45+
- Second element: `array[1]`
46+
- Last element of n-length array: `array[n-1]`
47+
- ### One-Based (Some Languages)
48+
- First element: `array[1]`
49+
- Second element: `array[2]`
50+
- Last element of n-length array: `array[n]`
51+
- ## Related
52+
- Array indexing and access
53+
- Memory addressing and pointer arithmetic
54+
- Programming language design
55+

‎pages/Rust___Error___Panic.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
- Rust uses the term *panicking* when a program exits with an error

‎pages/Rust___Variable.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,5 +4,7 @@
44
- `const` can be initialized with a specific subset of all possible expressions; see [Rust Reference’s section on constant evaluation](https://doc.rust-lang.org/reference/const_eval.html)
55
- `const` is required to have a type parameter
66
- {{embed [[Rust/Variable/let]]}}
7+
- {{embed [[Rust/Variable/Shadowing]]}}
78
-
8-
-
9+
-
10+
-

‎pages/Rust___Variable___Constant.md‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,13 @@
11
alias:: [[Rust/const]]
22

3-
- declared with `const`
4-
- required to have a [[Rust/Type/Annotation]]
5-
- [[Naming Convention]]: all uppercase with underscores between words
3+
- `const`
64
- [[Example]]
75
- ```rust
86
const THREE_HOURS_IN_SECONDS: u32 = 60 * 60 * 3;
97
```
8+
- required to have a [[Rust/Type/Annotation]]
9+
- [[Naming Convention]]: all uppercase with underscores between words
1010
- [[Rust/Expression/Constant]] [Rust Reference’s section on constant evaluation](https://doc.rust-lang.org/reference/const_eval.html)
1111
- There's a subset of expressions that can be used when creating a const. These are evaluated at [[Compile-time]].
12-
-
1312
- See also
1413
- [Variables and Mutability - The Rust Programming Language](https://rust-book.cs.brown.edu/ch03-01-variables-and-mutability.html)

‎pages/Rust___Variable___Shadowing.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
- you can use [[Rust/Variable/let]] on the same var more than once. Subsequent or nested use "shadows" prior use, following traditional scoping rules in c-family languages. Technically this is just a new binding.
2+
- ```rust
3+
let x = 5;
4+
println!("Initial x: {x}"); // 5
5+
let x = x + 1; // Shadowing
6+
println!("Shadowed x: {x}"); // 6
7+
{
8+
let x = x * 2; // Shadowing in inner scope
9+
println!("Inner scope x: {x}"); // 8
10+
}
11+
println!("Outer scope x: {x}"); // 6
12+
```
13+
- The rules of shadowing also work with [[Rust/mut]] - but mutations, in this case can only happen in the scope in which they are (re-)defined.
14+
- ```rust
15+
let mut x = 20;
16+
println!("Initial x: {x}"); // 20
17+
{
18+
let mut x = x;
19+
x += 2;
20+
}
21+
println!("After mutation x: {x}"); // 20
22+
```

0 commit comments

Comments
 (0)