Skip to content

Commit

Permalink
doc: Update
Browse files Browse the repository at this point in the history
  • Loading branch information
mcmah309 committed Dec 23, 2024
1 parent 3a5160a commit 8e8161e
Show file tree
Hide file tree
Showing 10 changed files with 27 additions and 14 deletions.
2 changes: 1 addition & 1 deletion book/src/libs/array/array.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Array
***
`Arr` (Array) is a zero cost extension type of `List`, where the `List` is treated as non-growable. This is useful for correctly handling lists where growable is false and const lists - as these types of lists are treated the same in the regular Dart type system, which may lead to errors. With `Arr`, type intent is clear for maintainers and developers are able think about code performance more critically.
[Arr](https://pub.dev/documentation/rust/latest/rust/Arr-extension-type.html) (Array) is a zero cost extension type of `List`, where the `List` is treated as non-growable. This is useful for correctly handling lists where growable is false and const lists - as these types of lists are treated the same in the regular Dart type system, which may lead to errors. With `Arr`, type intent is clear for maintainers and developers are able think about code performance more critically.
```dart
Arr<int?> array = Arr(null, 10);
```
Expand Down
10 changes: 5 additions & 5 deletions book/src/libs/cell/cell.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# Cell
***
Cell is library of useful wrappers types (cells) - [pub.dev](https://pub.dev/documentation/rust/latest/cell/cell-library.html).
Cell is library of useful wrappers types (cells).

[Cell](#cell) - A wrapper with interior mutability.
[Cell](https://pub.dev/documentation/rust/latest/rust/Cell-class.html) - A wrapper with interior mutability.

[OnceCell](#oncecell) - A cell which can be written to only once.
[OnceCell](https://pub.dev/documentation/rust/latest/rust/OnceCell-class.html) - A cell which can be written to only once.

[LazyCell](#lazycell) - A value which is initialized on the first access.
[LazyCell](https://pub.dev/documentation/rust/latest/rust/LazyCell-class.html) - A value which is initialized on the first access.

[LazyCellAsync](#lazycellasync) - A value which is asynchronously initialized on the first access.
[LazyCellAsync](https://pub.dev/documentation/rust/latest/rust/LazyCellAsync-class.html) - A value which is asynchronously initialized on the first access.


## Cell
Expand Down
2 changes: 1 addition & 1 deletion book/src/libs/env/env.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Env

Env introduces `Env` for handling the environment. It works like `Platform`,
Env introduces [Env](https://pub.dev/documentation/rust/latest/rust/Env-class.html) for handling the environment. It works like `Platform`,
except it is cross-platform (also works on web), since it is independent of `dart:io`, and has additional methods.

```dart
Expand Down
15 changes: 14 additions & 1 deletion book/src/libs/fs/fs.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
# Fs

Fs introduces `Fs`, a container of static methods for working with the file system in a safe manner.
Fs introduces [Fs](https://pub.dev/documentation/rust/latest/rust/Fs-class.html) and
[OpenOptions](https://pub.dev/documentation/rust/latest/rust/OpenOptions-class.html).
`Fs` is a container of static methods for working with the file system in a safe manner.
`Fs` combines many of the functionalities in `File`/`Directory`/`Link`/`FileStat`/`FileSystemEntity`
into one location and will never throw an exception. Instead of using instances of the previous
entities, `Fs` works only on paths.
Expand All @@ -18,4 +20,15 @@ catch (e) {
// handle
}
// handle
```
`OpenOptions` is a more extensive builder pattern for opening files in place of `File(..).open(mode)`
```dart
OpenOptions options = Options()
..append(true)
..create(true)
..createNew(true)
..read(true)
..truncate(true)
..write(true)
RandomAccessFile randomAccessFile = options.openSync("path/to/file".asPath()).unwrap();
```
2 changes: 1 addition & 1 deletion book/src/libs/iter/iter.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Iter
***
A Rust `Iterator` is analogous to the union of a Dart `Iterable` and `Iterator`. Since Dart already has an `Iterator` class, to avoid confusion,
the Dart implementation of the Rust iterator is `Iter`. `Iter`
the Dart implementation of the Rust iterator is [Iter](https://pub.dev/documentation/rust/latest/rust/Iter-class.html). `Iter`
makes working with collections of `rust` types and regular Dart types a breeze. e.g.

```dart
Expand Down
2 changes: 1 addition & 1 deletion book/src/libs/ops/ops.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

## RangeBounds

`RangeBounds` works the same as Rust's `RangeBounds` (usually seen as syntactic sugar e.g. `1..=3`)
[RangeBounds](https://pub.dev/documentation/rust/latest/rust/RangeBounds-class.html) works the same as Rust's `RangeBounds` (usually seen as syntactic sugar e.g. `1..=3`)
They have two uses:
1. `RangeBounds` can be used to get a `Slice` of an `Arr`, `Slice`, or `List`.
```dart
Expand Down
2 changes: 1 addition & 1 deletion book/src/libs/option/option.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Option
***
`Option` represents the union of two types - `Some<T>` and `None`.
[Option](https://pub.dev/documentation/rust/latest/rust/Option-class.html) represents the union of two types - `Some<T>` and `None`.

`Option` is easy to declare and translate back and forth between nullable types.
```dart
Expand Down
2 changes: 1 addition & 1 deletion book/src/libs/panic/panic.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Panic
***
As with `Error` in Dart Core, `Panic` represents a state that should never happen and thus should never be caught.
As with `Error` in Dart Core, [Panic](https://pub.dev/documentation/rust/latest/rust/Panic-class.html) represents a state that should never happen and thus should never be caught.
Rust vs Dart Error handling terminology:

| Dart Exception Type | Equivalent in Rust |
Expand Down
2 changes: 1 addition & 1 deletion book/src/libs/result/result.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Result
***
`Result<T, E>` is the type used for returning and propagating errors. It is an alternative to throwing exceptions. It is a sealed type with the variants, `Ok(T)`, representing success and containing a value, and `Err(E)`, representing error and containing an error value.
[Result<T, E>](https://pub.dev/documentation/rust/latest/rust/Result-class.html) is the type used for returning and propagating errors. It is an alternative to throwing exceptions. It is a sealed type with the variants, `Ok(T)`, representing success and containing a value, and `Err(E)`, representing error and containing an error value.

To better understand the motivation around the `Result` type refer to this [article](https://mcmah309.github.io/#/blog/the_result_type_in_dart).

Expand Down
2 changes: 1 addition & 1 deletion book/src/libs/slice/slice.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Slice
***
A `Slice` is a contiguous sequence of elements in a `List`. Slices are a view into a list without allocating and copying to a new list,
A [Slice](https://pub.dev/documentation/rust/latest/rust/Slice-class.html) is a contiguous sequence of elements in a `List`. Slices are a view into a list without allocating and copying to a new list,
thus slices are more efficient than creating a sub-list, but they do not own their own data. That means shrinking the original list can cause the slices range to become invalid, which may cause an exception.

`Slice` also has a lot of efficient methods for in-place mutation within and between slices. e.g.
Expand Down

0 comments on commit 8e8161e

Please sign in to comment.