Rust Advanced Lesson

overview

Rust is a compiled semantically enhanced modern programming language with syntax loosely similar to C++ that provides the built-in cargo package manager, modules and the rustup tool chain installer.

Rust is suited for embedded processing, fault-tolerant mission critical systems, concurrent processing with channels for transferring values between threads, and it provides package abstraction and import, various pointer implementations, including references, raw pointer, owned pointer and the borrowed pointer, reborrowing , and lifetime, generic types, powerful traits, allocators, including no-heap allocation, closures, mutable and fearless concurrency paradigm, and closures. Like C++ it has destructors via Drop scope as well as control over allocation and will be imminently suitable for resource management. Rust also supports operator overloading via traits.

Rust provides async/await keywords that provide async programming through the Future trait, with the .await method, provides concurrency synchronisation via futures::join!, futures::select! macros and spawning provided to support mixing OS threads and async Tasks. The executors for async operations are not embedded in the language, instead are provided by runtime libraries. Async programming maps well to streams and web-development.

Rust also provides the unit type and the usual array and the additional compound types tuples.

Rust provides rustup for tool-chain management and supports cross-compilation for many platforms - thus providing good portability. I can see it being very useful in the world of prolific IoT devices, as well as in large complex systems.

Rust has several call-by mechanisms and entrenched with this is object lifetimes management and access that is enforced by the compiler:

// Examples of methods implemented on struct `Example`.
struct Example;
type Alias = Example;
trait Trait { type Output; }
impl Trait for Example { type Output = Example; }
impl Example {
    fn by_value(self: Self) {}
    fn by_ref(self: &Self) {}
    fn by_ref_mut(self: &mut Self) {}
    fn by_box(self: Box<Self>) {}
    fn by_rc(self: Rc<Self>) {}
    fn by_arc(self: Arc<Self>) {}
    fn by_pin(self: Pin<&Self>) {}
    fn explicit_type(self: Arc<Example>) {}
    fn with_lifetime<'a>(self: &'a Self) {}
    fn nested<'a>(self: &mut &'a Arc<Rc<Box<Alias>>>) {}
    fn via_projection(self: <Example as Trait>::Output) {}
}

• pass by reference is a "move" of the pointer
• pass by mutable reference permits the function to modify the referenced object
• pass by box means the the Boxed item will be deallocated when the function goes out of scope. A Box implements Drop and owns its pointer
• Rc is a smart pointer that implements a reference count; the reference count is increased on each call to a function or when cloned, until the object is no longer referenced by code.
• Arc is an atomically referenced counted object and may be used in multithreaded context.

So I am going to trial switching critical system development over to this new language platform. I can't wait to put it to use and I already have bunches of ideas in the backlog.

Rust uses copy/destroy move when passing parameters; the old variable reference is no longer valid after such a move, and access constraint will be enforced by the compiler to prevent accessing the original value that was moved. Here is a brief explanation of the call by semantics:

• the Rust provision is described in the rustbook
• cargo is described in the cargo book
• the rust language is described in the rust language book
• the rustc compiler is described in its own reference

The standard library is described in the std cargo reference.

I expect that rust will displace C++ as the language of choice for safe embedded and complex system development despite the steeper learning curve. Of interest is it can be used for web-application development.

rust ideas

• rust on raspberry pi
  • https://www.geeksforgeeks.org/how-to-install-rust-on-raspberry-pi/
  • https://www.freecodecamp.org/news/embedded-rust-programming-on-raspberry-pi-zero-w/
  • https://duckduckgo.com/?q=rust+on+raspberry+pi&ia=web
  • bare-metal rust on pi https://github.com/wizofe/rust-raspi3-tutorial
• rust CID
• rust cargo proxy
• rust async IO for raspberry pi
• rust cargo repository mirror

reference code

Example code is provided https://doc.rust-lang.org/stable/rust-by-example/

Plus there are other interesting aspects:

• HAL
  • RPAL raspberry pi HAL https://github.com/golemparts/rppal

example codes

• getting started https://doc.rust-lang.org/book/ch01-00-getting-started.html
• text to morse code https://www.freecodecamp.org/news/embedded-rust-programming-on-raspberry-pi-zero-w/
• mqtt https://betterprogramming.pub/rust-for-iot-is-it-time-67b14ab34b8

platforms

• pico https://allianceforthefuture-com.ngontinh24.com/article/getting-started-with-rust-on-a-raspberry-pi-pico-part-1
• ESP32 https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/hw-reference/esp32c3/user-guide-devkitm-1.html
  • https://core-electronics.com.au/development-boards/esp32.html

This is a teach yourself category:Advanced Lesson - see the #training for video lessons.

performance

Rust is a statically evaluated language that has no garbage collection, and the compiler asserts preconditions with the goal to providing safe concurrent programming. It uses the LLVM toolchain and its resultant executable code performs quite well.

native applications

These graphs are from comparative benchmarks of the simple algorithms that are easily written in other languages.

web application-frameworks

These web-benchmarks compare different application frameworks written in a candidate language:

The frameworks and their implementation languages:

• happyx - nim https://github.com/HapticX/happyx
• activej - java https://activej.io/
• fomo - php https://github.com/fomo-framework/fomo
• uwebsockets - C /C++ https://github.com/uNetworking/uWebSockets.js
• actix - rust https://actix.rs/
• drogon - C++ https://github.com/drogonframework/drogon
• spring - java https://spring.io/
• express - node-js

installation

Rust is installed via the rustup installer

• on Linux download rustup and execute as regular user:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

• or on windows use the installer

https://static.rust-lang.org/rustup/dist/i686-pc-windows-gnu/rustup-init.exe

If you have installed rust before then you may update it to the latest via rustup

• update

rustup update

• verify

cargo --version
cargo 1.71.0 (cfd3bbd8f 2023-06-08)

• uninstall via

rustup self uninstall

cargo

Cargo is the package manager that may be used to build, document and also run rust applications.

The project layout:

.
├── Cargo.lock
├── Cargo.toml
├── src/
│   ├── lib.rs
│   ├── main.rs
│   └── bin/
│       ├── named-executable.rs
│       ├── another-executable.rs
│       └── multi-file-executable/
│           ├── main.rs
│           └── some_module.rs
├── benches/
│   ├── large-input.rs
│   └── multi-file-bench/
│       ├── main.rs
│       └── bench_module.rs
├── examples/
│   ├── simple.rs
│   └── multi-file-example/
│       ├── main.rs
│       └── ex_module.rs
└── tests/
    ├── some-integration-tests.rs
    └── multi-file-test/
        ├── main.rs
        └── test_module.rs

dependencies

• Cargo.toml is about describing your dependencies in a broad sense, and is written by you.
• Cargo.lock contains exact information about your dependencies (including transitive dependencies), and is automatically contained by Cargo and should not be manually edited.

tests

Cargo can run your tests with the cargo test command. Cargo looks for tests to run in two places: in each of your src files and any tests in tests/. Tests in your src files should be unit tests and documentation tests. Tests in tests/ should be integration-style tests. As such, you’ll need to import your crates into the files in tests.

build

Cargo stores the output of a build into the “target” directory. By default, this is the directory named target in the root of your workspace. To change the location, you can set the CARGO_TARGET_DIR environment variable, the build.target-dir config value, or the --target-dir command-line flag.

The directory layout depends on whether or not you are using the --target flag to build for a specific platform. If --target is not specified, Cargo runs in a mode where it builds for the host architecture. The output goes into the root of the target directory, with each profile stored in a separate subdirectory:

Directory	Description
target/debug/	Contains output for the dev profile.
target/release/	Contains output for the release profile (with the --release option).
target/foo/	Contains build output for the foo profile (with the --profile=foo option).

For historical reasons, the dev and test profiles are stored in the debug directory, and the release and bench profiles are stored in the release directory. User-defined profiles are stored in a directory with the same name as the profile.

When building for another target with --target, the output is placed in a directory with the name of the target:

directories

Cargo caches data in the following directory structure:

/home/$USER/.cargo
├── bin
│   ├── cargo
│   ├── cargo-clippy
│   ├── cargo-fmt
│   ├── cargo-miri
│   ├── clippy-driver
│   ├── rls
│   ├── rust-analyzer
│   ├── rustc
│   ├── rustdoc
│   ├── rustfmt
│   ├── rust-gdb
│   ├── rust-gdbgui
│   ├── rust-lldb
│   ├── rustup
│   └── ssd-benchmark
├── env
├── git
│   ├── CACHEDIR.TAG
│   ├── checkouts
│   │   ├── application-services-99bb257f08384f94
│   │   │   └── c51b635
│   │   │       ├── automation
│   │   │       │   ├── cargo-update-pr.py
...
│   ├── db
│   │   ├── application-services-99bb257f08384f94
...
| registry
│   ├──cache
│      └── index.crates.io-6f17d22bba15001f
│          ├── adler-1.0.2.crate
│          ├── ahash-0.4.7.crate
│          ├── aho-corasick-0.7.18.crate
│          ├── alsa-0.4.3.crate
│          ├── alsa-sys-0.3.1.crate
│          ├── anyhow-1.0.57.crate
...
└── src
    └── index.crates.io-6f17d22bba15001f
        ├── adler-1.0.2
        │   ├── benches
        │   │   └── bench.rs
        │   ├── Cargo.toml
        │   ├── Cargo.toml.orig
        │   ├── CHANGELOG.md
        │   ├── LICENSE-0BSD
        │   ├── LICENSE-APACHE
        │   ├── LICENSE-MIT
        │   ├── README.md
        │   ├── RELEASE_PROCESS.md
        │   └── src
        │       ├── algo.rs
        │       └── lib.rs

This can make the requirements on the home drive very large.

du -h ~/.cargo
...
1.5G	.cargo/

IDEs

Trialing the VisualStudio code IDE.

VisualStudio

VisualStudio IDEmay be installed on Debian/Ubuntu Linux.

• download VisualStudio for Debian 12
• prequisites:

sudo apt install git

• install

sudo apt install ./code_1.80.2-1690491597_amd64.deb

The getting started document link

https://code.visualstudio.com/docs/?dv=linux64_deb

The VisualStudio IDE is called code and can be launched from an XTerm via

code

Here is the explanation for the rust language

https://code.visualstudio.com/docs/languages/rust

required extensions

For the Extension market place (Boxes) install

• rust-analyser

• CodeLLDB

cargo watch

Watches and runs when changes are made to cargo project. Very useful.

• https://github.com/watchexec/cargo-watch
• https://crates.io/crates/cargo-watch/3.0.3

rust playground

The online playground IDE is very useful for testing and providing examples to others with its permalink facility:

• https://play.rust-lang.org/?version=stable&mode=debug&edition=2021

syntax

When a name is forbidden because it is a reserved word (such as crate), either use a raw identifier (r#crate) or use a trailing underscore (crate_). Don't misspell the word (krate).

🚩 Note: a leading _ in a variable name is a statement that the variable does not need to be referenced.

rust style

• snake_case for variable, functions, attributes et al.
  • function and method names
  • local variables
  • macro names
  • constants (consts and immutable statics) - shall be SCREAMING_SNAKE_CASE.
• CamelCase T
  • Struct
  • Types
  • Enum variants

comments

Use inline comments // instead of block comments /* .... */

Documentation comments /// for markdown

rust semantics

attributes

attributes are declarative tags placed above function definitions, modules, items, etc. They provide additional information or alter the behaviour of the code. Attributes in Rust start with a hashtag (#) and are placed inside square brackets ([]). For instance, an attribute could look like this: #[attribute].

Attributes can be classified into the following kinds:

• Built-in attributes
• Macro attributes
• Derive macro helper attributes
• Tool attributes

macro

The term macro refers to a family of features in Rust: declarative macros with macro_rules! and three kinds of procedural macros:

• Custom #[derive] macros that specify code added with the derive attribute used on structs and enums
• Attribute-like macros that define custom attributes usable on any item
• Function-like macros that look like function calls but operate on the tokens specified as their argument

println

The println!, print! macros emits formatted string to stdout while eprint! and eprintln! output to stderr, and the macro format! writes formatted test to String, while the write! and writeln! macros emit the formatted string to a stream.

std::fmt contains many traits which govern the display of text:

• fmt:Debug uses the {:?} marker
• fmt:Display uses the {} marker.

Implementing the fmt::Display trait automatically implements the ToString trait which allows us to convert the type to String.

• Formatted Print
• https://stackoverflow.com/questions/56485167/how-to-format-a-byte-into-a-2-digit-hex-string-in-rust
• https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&gist=fae66e4c050d1a343aa99881d91d2aad

fn main() {
    println!("{:#01x}", 10);
    println!("{:#02x}", 10);
    println!("{:#03x}", 10);
    println!("{:#04x}", 10);
    println!("{:#05x}", 10);
    println!("{:#06x}", 10);
}

• Prints:

0xa
0xa
0xa
0x0a
0x00a
0x000a

interpolation

Recall that String interpolation is performed by the format! (macro).

• https://doc.rust-lang.org/std/fmt/

format!("Hello");                 // => "Hello"
format!("Hello, {}!", "world");   // => "Hello, world!"
format!("The number is {}", 1);   // => "The number is 1"
format!("{:?}", (3, 4));          // => "(3, 4)"
format!("{value}", value=4);      // => "4"
let people = "Rustaceans";
format!("Hello {people}!");       // => "Hello Rustaceans!"
format!("{} {}", 1, 2);           // => "1 2"
format!("{:04}", 42);             // => "0042" with leading zeros
format!("{:#?}", (100, 200));     // => "(
                                  //       100,
                                  //       200,
                                  //     )"

positional parameters

Each formatting argument is allowed to specify which value argument it’s referencing, and if omitted it is assumed to be “the next argument”. For example, the format string {} {} {} would take three parameters, and they would be formatted in the same order as they’re given. The format string {2} {1} {0}, however, would format arguments in reverse order.

named parameters

Rust itself does not have a Python-like equivalent of named parameters to a function, but the format! macro is a syntax extension that allows it to leverage named parameters. Named parameters are listed at the end of the argument list and have the syntax:

 identifier '=' expression

For example, the following format! expressions all use named arguments:

format!("{argument}", argument = "test");   // => "test"
format!("{name} {}", 1, name = 2);          // => "2 1"
format!("{a} {c} {b}", a="a", b='b', c=3);  // => "a 3 b"

If a named parameter does not appear in the argument list, format! will reference a variable with that name in the current scope.

formatting parameters

Each argument being formatted can be transformed by a number of formatting parameters.

• width

// All of these print "Hello x    !"
println!("Hello {:5}!", "x");
println!("Hello {:1$}!", "x", 5);
println!("Hello {1:0$}!", 5, "x");
println!("Hello {:width$}!", "x", width = 5);
let width = 5;
println!("Hello {:width$}!", "x");

• fill/alignment

assert_eq!(format!("Hello {:<5}!", "x"),  "Hello x    !");
assert_eq!(format!("Hello {:-<5}!", "x"), "Hello x----!");
assert_eq!(format!("Hello {:^5}!", "x"),  "Hello   x  !");
assert_eq!(format!("Hello {:>5}!", "x"),  "Hello     x!");

• [fill]< - the argument is left-aligned in width columns
• [fill]^ - the argument is center-aligned in width columns
• [fill]> - the argument is right-aligned in width columns
• Sign/#/0

assert_eq!(format!("Hello {:+}!", 5), "Hello +5!");
assert_eq!(format!("{:#x}!", 27), "0x1b!");
assert_eq!(format!("Hello {:05}!", 5),  "Hello 00005!");
assert_eq!(format!("Hello {:05}!", -5), "Hello -0005!");
assert_eq!(format!("{:#010x}!", 27), "0x0000001b!");

These are all flags altering the behavior of the formatter.

See https://doc.rust-lang.org/std/fmt/ for full details.

Types

Primitives include:

• scalar
• bool
• unit type ()
• arrays

scalar

numeric
u8	u16	u32	u64	u128
i8	i16	i32	i64	i128
usize			... architecture dependent
isize			... architecture dependent
		f32	f64
character
char
boolean
bool

tuple

let tuple = ( 1, 2.2, 'a', "string", (1,'b'));
println!("{:?}",tuple);
println!("{:#?}",tuple);}

• output

(1, 2.2, 'a', "string", (1, 'b'))
(
    1,
    2.2,
    'a',
    "string",
    (
        1,
        'b',
    ),
)

array

An array is a fixed-size sequence of N elements of type T. The array type is written as [T; N]. The size is a constant expression that evaluates to a usize.

Examples:

// A stack-allocated array
let array: [i32; 3] = [1, 2, 3];

// A heap-allocated array, coerced to a slice
let boxed_array: Box<[i32]> = Box::new([1, 2, 3]);
All elements of arrays are always initialized, and access to an array is always bounds-checked in safe methods and operators.

str

str: a stack allocated UTF-8 string, which can be borrowed as &str and sometimes &’static str, but can’t be moved

String

String: a heap allocated UTF-8 string, which can be borrow as &String and &str, and can be moved.

let x: String = "abcdef";

slice

A slice is a dynamically sized type representing a 'view' into a sequence of elements of type T. The slice type is written as [T].

Slice types are generally used through pointer types. For example:

&[T]: a 'shared slice', often just called a 'slice'. It doesn't own the data it points to; it borrows it.
&mut [T]: a 'mutable slice'. It mutably borrows the data it points to.
Box<[T]>: a 'boxed slice'

Examples:

// A heap-allocated array, coerced to a slice
let boxed_array: Box<[i32]> = Box::new([1, 2, 3]);

// A (shared) slice into an array
let slice: &[i32] = &boxed_array[..];
All elements of slices are always initialized, and access to a slice is always bounds-checked in safe methods and operators.

size

use std::mem::size_of;
use std::mem::size_of_val;

fn main() {
    let x: char = 'a';
    println!("{}",size_of::<char>());
    println!("{}",size_of_val::<char>(&x));
}

pointer

let my_num: i32 = 10;
let my_num_ptr: *const i32 = &my_num;
let mut my_speed: i32 = 88;
let my_speed_ptr: *mut i32 = &mut my_speed;
To get a pointer to a boxed value, dereference the box:

let my_num: Box<i32> = Box::new(10);
let my_num_ptr: *const i32 = &*my_num;
let mut my_speed: Box<i32> = Box::new(88);
let my_speed_ptr: *mut i32 = &mut *my_speed;

reference

A reference represents a borrow of some owned value. You can get one by using the & or &mut operators on a value, or by using a ref or ref mut pattern.

For those familiar with pointers, a reference is just a pointer that is assumed to be aligned, not null, and pointing to memory containing a valid value of T - for example, &bool can only point to an allocation containing the integer values 1 (true) or 0 (false), but creating a &bool that points to an allocation containing the value 3 causes undefined behaviour. In fact, Option<&T> has the same memory representation as a nullable but aligned pointer, and can be passed across FFI boundaries as such.

In most cases, references can be used much like the original value. Field access, method calling, and indexing work the same (save for mutability rules, of course). In addition, the comparison operators transparently defer to the referent’s implementation, allowing references to be compared the same as owned values.

References have a lifetime attached to them, which represents the scope for which the borrow is valid. A lifetime is said to “outlive” another one if its representative scope is as long or longer than the other. The 'static lifetime is the longest lifetime, which represents the total life of the program. For example, string literals have a 'static lifetime because the text data is embedded into the binary of the program, rather than in an allocation that needs to be dynamically managed.

&mut T references can be freely coerced into &T references with the same referent type, and references with longer lifetimes can be freely coerced into references with shorter ones.

Reference equality by address, instead of comparing the values pointed to, is accomplished via implicit reference-pointer coercion and raw pointer equality via ptr::eq, while PartialEq compares values.

use std::ptr;

let five = 5;
let other_five = 5;
let five_ref = &five;
let same_five_ref = &five;
let other_five_ref = &other_five;

assert!(five_ref == same_five_ref);
assert!(five_ref == other_five_ref);

assert!(ptr::eq(five_ref, same_five_ref));
assert!(!ptr::eq(five_ref, other_five_ref));

custom types

• struct

struct Person {
    name: String,
    age: u8,
}

• enum

enum WebEvent {
    // An `enum` variant may either be `unit-like`,
    PageLoad,
    PageUnload,
    // like tuple structs,
    KeyPress(char),
    Paste(String),
    // or c-like structures.
    Click { x: i64, y: i64 },
}

// A function which takes a `WebEvent` enum as an argument and
// returns nothing.
fn inspect(event: WebEvent) {
    match event {
        WebEvent::PageLoad => println!("page loaded"),
        WebEvent::PageUnload => println!("page unloaded"),
        // Destructure `c` from inside the `enum` variant.
        WebEvent::KeyPress(c) => println!("pressed '{}'.", c),
        WebEvent::Paste(s) => println!("pasted \"{}\".", s),
        // Destructure `Click` into `x` and `y`.
        WebEvent::Click { x, y } => {
            println!("clicked at x={}, y={}.", x, y);
        },
    }
}

• union

union MyUnion {
    f1: u32,
    f2: f32,
}

constants

• constants

static LANGUAGE: &str = "Rust";
const THRESHOLD: i32 = 10;

literals

numerical

An integer literal expression consists of a single INTEGER_LITERAL token.

If the token has a suffix, the suffix must be the name of one of the primitive integer types: u8, i8, u16, i16, u32, i32, u64, i64, u128, i128, usize, or isize, and the expression has that type.

If the token has no suffix, the expression's type is determined by type inference:

If an integer type can be uniquely determined from the surrounding program context, the expression has that type.

If the program context under-constrains the type, it defaults to the signed 32-bit integer i32.

If the program context over-constrains the type, it is considered a static type error.

The value of the float expression is determined from the string representation of the token as follows:

Any suffix is removed from the string.

Any underscores are removed from the string.

Then the string is converted to the expression's type as if by f32::from_str or f64::from_str.

let x = 255_u16;


let x = 0xff + 0o77 + 0b1111_1010 + l_024;

let x = 0.01_f64;

let x = 1.312E+03_f32;

generic types

• https://doc.rust-lang.org/book/ch10-01-syntax.html

In struct

struct Point<T> {
    x: T,
    y: T,
}

fn main() {
    let integer = Point { x: 5, y: 10 };
    let float = Point { x: 1.0, y: 4.0 };
}

In enum

enum Option<T> {
    Some(T),
    None,
}

In functions

struct Point<X1, Y1> {
    x: X1,
    y: Y1,
}

impl<X1, Y1> Point<X1, Y1> {
    fn mixup<X2, Y2>(self, other: Point<X2, Y2>) -> Point<X1, Y2> {
        Point {
            x: self.x,
            y: other.y,
        }
    }
}

fn main() {
    let p1 = Point { x: 5, y: 10.4 };
    let p2 = Point { x: "Hello", y: 'c' };

    let p3 = p1.mixup(p2);

    println!("p3.x = {}, p3.y = {}", p3.x, p3.y);
}

type_name

Obtaining type information

use std::any::type_name;

fn type_of<T>(_: T) -> &'static str {
    type_name::<T>()
}

fn main() {
    let message: &str = "Hello world!";
    println!("{} {}", message,type_of(message));
}

• result

Hello world! &str
10 i32

See also the Any Trait<fref>rust Any Trait https://doc.rust-lang.org/std/any/trait.Any.html</ref>

variables

Variables are a component of a stack frame, either a named function parameter, an anonymous temporary, or a named local variable. A local variable holds a value directly, allocated within a stack's memory. and the value is part of the stack-frame.

Local variables are immutable unless declared otherwise:

• immutable

let _immutable_binding = 1;

• mutable

let  mut mutable_binding = 1;

Function parameters are immutable unless declared mutable too.

The entire stack frame containing variables is allocated in an uninitialized state. Subsequent statments within the may or may not initialize a local variable.

Diagnostics

    // Ok
    mutable_binding += 1;

    println!("After mutation: {}", mutable_binding);

    // Error! Cannot assign a new value to an immutable variable
    _immutable_binding += 1;

• variables may be initialized after they are declared which is used in if/else blocks to initialize immutable variables.

scope

• variables have scope i.e. they belong to a block and are not visible outside that block
• out-block variables may be shadowed' inner variables shadow outer variables (of the same name).
• freezing an immutable reference to data freezes the data; said data cannot be modified until the immutable reference goes out of scope.

casting

Rust provides 'no implicit type conversion.

Primitive types may be cast to other primitive types

   let decimal = 65.4321_f32;

    // Error! No implicit conversion
    let integer: u8 = decimal;
    // FIXME ^ Comment out this line

    // Explicit conversion
    let integer = decimal as u8;
    let character = integer as char;

suffixed literal

• Literal may be cast to a type by a suffix.

    
     // Suffixed literals, their types are known at initialization
    let x = 1u8;
    let y = 2u32;
    let z = 3f32;

• inference

The compiler can make inference about types (after an assignment), and from then on it will enforce that type inference.

fn main() {
    // Because of the annotation, the compiler knows that `elem` has type u8.
    let elem = 5u8;

    // Create an empty vector (a growable array).
    let mut vec = Vec::new();
    // At this point the compiler doesn't know the exact type of `vec`, it
    // just knows that it's a vector of something (`Vec<_>`).

    // Insert `elem` in the vector.
    vec.push(elem);
    // Aha! Now the compiler knows that `vec` is a vector of `u8`s (`Vec<u8>`)
    // TODO ^ Try commenting out the `vec.push(elem)` line

    println!("{:?}", vec);
}

• alias; a type may be aliased via a CamelCase name e.g.

type NanoSecond = u64;

conversion

• conversion; rust supports type conversion, even for struct and enum, via Traits From and Into
• string conversion and parsing

Algebraic features

statistics

• https://rust-lang-nursery.github.io/rust-cookbook/science/mathematics/statistics.html
• https://docs.rs/statistical/latest/statistical/

nalgebra/

• https://docs.rs/nalgebra/latest/nalgebra/

matrices

Linear Algebra is supported by Matrix and Complex types.

• https://docs.rs/matrix/latest/matrix/index.html
• https://rust-lang-nursery.github.io/rust-cookbook/science/mathematics/linear_algebra.html
  • https://docs.rs/matrix/latest/matrix/operation/index.html

complex numbers

• https://docs.rs/num-complex/latest/num_complex/

operators

Operators are described

• markup https://doc.rust-lang.org/book/appendix-02-operators.html
• names https://doc.rust-lang.org/std/ops/index.html

Operator overloading is also provided, e.g. for Complex numbers.

• https://doc.rust-lang.org/std/ops/index.html

Trait

The following traits are implemented for all &T, regardless of the type of its referent:

• Copy
• Clone (Note that this will not defer to T’s Clone implementation if it exists!)
• Deref
• Borrow
• fmt::Pointer

&mut T references get all of the above except Copy and Clone (to prevent creating multiple simultaneous mutable borrows), plus the following, regardless of the type of its referent:

• DerefMut
• BorrowMut

The following traits are implemented on &T references if the underlying T also implements that trait:

• All the traits in std::fmt except fmt::Pointer (which is implemented regardless of the type of its referent) and fmt::Write
• PartialOrd
• Ord
• PartialEq
• Eq
• AsRef
• Fn (in addition, &T references get FnMut and FnOnce if T: Fn)
• Hash
• ToSocketAddrs
• Send (&T references also require T: Sync)
• Sync

&mut T references get all of the above except ToSocketAddrs, plus the following, if T implements that trait:

• AsMut
• FnMut (in addition, &mut T references get FnOnce if T: FnMut) fmt::Write
• Iterator
• DoubleEndedIterator
• ExactSizeIterator
• FusedIterator
• TrustedLen
• io::Write
• Read
• Seek
• BufRead

Note that due to method call deref coercion, simply calling a trait method will act like they work on references as well as they do on owned values! The implementations described here are meant for generic contexts, where the final type T is a type parameter or otherwise not locally known.

control flow

• if/else
• loop

LoopExpression :
   LoopLabel? (
         InfiniteLoopExpression
      | PredicateLoopExpression
      | PredicatePatternLoopExpression
      | IteratorLoopExpression
      | LabelBlockExpression
   )

'outer: loop {
    while true {
        break 'outer;
    }
}

let result = 'block: {
    do_thing();
    if condition_not_met() {
        break 'block 1;
    }
    do_next_thing();
    if condition_not_met() {
        break 'block 2;
    }
    do_last_thing();
    3
};

When associated with a loop, a break expression may be used to return a value from that loop, via one of the forms break EXPR or break 'label EXPR, where EXPR is an expression whose result is returned from the loop. For example:

let (mut a, mut b) = (1, 1);
let result = loop {
    if b > 10 {
        break b;
    }
    let c = a + b;
    a = b;
    b = c;
};
// first number in Fibonacci sequence over 10:
assert_eq!(result, 13);

• while

let mut i = 0;

while i < 10 {
    println!("hello");
    i = i + 1;
}
<pre>
<pre>
let mut vals = vec![2, 3, 1, 2, 2];
while let Some(v @ 1) | Some(v @ 2) = vals.pop() {
    // Prints 2, 2, then 1
    println!("{}", v);
}

• for

let v = &["apples", "cake", "coffee"];

for text in v {
    println!("I like {}.", text);
}

• for range (See also range expression.)

let mut sum = 0;
// note this will run 11 times with n =1 ... n =10
for n in 1..11 {
    sum += n;
}

• match

  // tuples
  match triple {
        // Destructure the second and third elements
        (0, y, z) => println!("First is `0`, `y` is {:?}, and `z` is {:?}", y, z),
        (1, ..)  => println!("First is `1` and the rest doesn't matter"),
        (.., 2)  => println!("last is `2` and the rest doesn't matter"),
        (3, .., 4)  => println!("First is `3`, last is `4`, and the rest doesn't matter"),
        // `..` can be used to ignore the rest of the tuple
        _      => println!("It doesn't matter what they are"),
        // `_` means don't bind the value to a variable
    }

     match array {
        // Binds the second and the third elements to the respective variables
        [0, second, third] =>
            println!("array[0] = 0, array[1] = {}, array[2] = {}", second, third),

        // Single values can be ignored with _
        [1, _, third] => println!(
            "array[0] = 1, array[2] = {} and array[1] was ignored",
            third
        ),

    match color {
        Color::Red   => println!("The color is Red!"),
        Color::Blue  => println!("The color is Blue!"),
        Color::Green => println!("The color is Green!"),
        Color::RGB(r, g, b) =>
 
    match reference {
        // If `reference` is pattern matched against `&val`, it results
        // in a comparison like:
        // `&i32`
        // `&val`
        // ^ We see that if the matching `&`s are dropped, then the `i32`
        // should be assigned to `val`.
        &val => println!("Got a value via destructuring: {:?}", val),
    }

    // To avoid the `&`, you dereference before matching.
    match *reference {
        val => println!("Got a value via dereferencing: {:?}", val),
    }

    // struct
    match foo {
        Foo { x: (1, b), y } => println!("First of x is 1, b = {},  y = {} ", b, y),

        // you can destructure structs and rename the variables,
        // the order is not important
        Foo { y: 2, x: i } => println!("y is 2, i = {:?}", i),

        // and you can also ignore some variables:
        Foo { y, .. } => println!("y = {}, we don't care about x", y),
        // this will give an error: pattern does not mention field `x`
        //Foo { y } => println!("y = {}", y),
    }

• match guards

    match temperature {
        Temperature::Celsius(t) if t > 30 => println!("{}C is above 30 Celsius", t),
        // The `if condition` part ^ is a guard
        Temperature::Celsius(t) => println!("{}C is below 30 Celsius", t),

        Temperature::Fahrenheit(t) if t > 86 => println!("{}F is above 86 Fahrenheit", t),
        Temperature::Fahrenheit(t) => println!("{}F is below 86 Fahrenheit", t),
    }

• match binding

  match age() {
        0             => println!("I haven't celebrated my first birthday yet"),
        // Could `match` 1 ..= 12 directly but then what age
        // would the child be? Instead, bind to `n` for the
        // sequence of 1 ..= 12. Now the age can be reported.
        n @ 1  ..= 12 => println!("I'm a child of age {:?}", n),
        n @ 13 ..= 19 => println!("I'm a teen of age {:?}", n),
        // Nothing bound. Return the result.
        n             => println!("I'm an old person of age {:?}", n),
    }

• if let
• let/else
• while let

range expression

Production	Syntax	Type	Range
RangeExpr	start..end	std::ops::Range	start ≤ x < end
RangeFromExpr	start..	std::ops::RangeFrom	start ≤ x
RangeToExpr	..end	std::ops::RangeTo	x < end
RangeFullExpr	..	std::ops::RangeFul	-
RangeInclusiveExpr	start..=end	std::ops::RangeInclusive	start ≤ x ≤ end
RangeToInclusiveExpr	..=end	std::ops::RangeToInclusive	x ≤ end

functions

// Function that returns a boolean value
fn is_divisible_by(lhs: u32, rhs: u32) -> bool {
    // Corner case, early return
    if rhs == 0 {
        return false;
    }

    // This is an expression, the `return` keyword is not necessary here
    lhs % rhs == 0
}

• associated functions

struct Point {
    x: f64,
    y: f64,
}

// Implementation block, all `Point` associated functions & methods go in here
impl Point {
    // This is an "associated function" because this function is associated with
    // a particular type, that is, Point.
    //
    // Associated functions don't need to be called with an instance.
    // These functions are generally used like constructors.
    fn origin() -> Point {
        Point { x: 0.0, y: 0.0 }
    }

    // Another associated function, taking two arguments:
    fn new(x: f64, y: f64) -> Point {
        Point { x: x, y: y }
    }
}

• methods

impl Rectangle {
    // This is a method
    // `&self` is sugar for `self: &Self`, where `Self` is the type of the
    // caller object. In this case `Self` = `Rectangle`
    fn area(&self) -> f64 {
        // `self` gives access to the struct fields via the dot operator
        let Point { x: x1, y: y1 } = self.p1;
        let Point { x: x2, y: y2 } = self.p2;

        // `abs` is a `f64` method that returns the absolute value of the
        // caller
        ((x1 - x2) * (y1 - y2)).abs()
    }

    fn perimeter(&self) -> f64 {
        let Point { x: x1, y: y1 } = self.p1;
        let Point { x: x2, y: y2 } = self.p2;

        2.0 * ((x1 - x2).abs() + (y1 - y2).abs())
    }

    // This method requires the caller object to be mutable
    // `&mut self` desugars to `self: &mut Self`
    fn translate(&mut self, x: f64, y: f64) {
        self.p1.x += x;
        self.p2.x += x;

        self.p1.y += y;
        self.p2.y += y;
    }
}

• closure | |

fn main() {
    let outer_var = 42;
    
    // A regular function can't refer to variables in the enclosing environment
    //fn function(i: i32) -> i32 { i + outer_var }
    // TODO: uncomment the line above and see the compiler error. The compiler
    // suggests that we define a closure instead.

    // Closures are anonymous, here we are binding them to references
    // Annotation is identical to function annotation but is optional
    // as are the `{}` wrapping the body. These nameless functions
    // are assigned to appropriately named variables.
    let closure_annotated = |i: i32| -> i32 { i + outer_var };
    let closure_inferred  = |i     |          i + outer_var  ;

• iterator
• HOF - higher order functions
• diverging function !

use rand; // 0.8.4

fn main() {
    let foo;
    if rand::random::<bool>() {
        foo = "Hello, world!";
    } else {
        diverge();
    }
    println!("{foo}");
}

fn diverge() {
    panic!("Crash!");
}

We declare a variable foo, but we only initialize it in one branch of the if expression. This fails to compile with the following error:

error[E0381]: borrow of possibly-uninitialized variable: `foo`
  --> src/main.rs:10:15
   |
10 |     println!("{foo}");
   |               ^^^^^ use of possibly-uninitialized `foo`

However, if we change the definition of our diverge function like this:

fn diverge() -> ! {
    panic!("Crash!");
}

then the code successfully compiles. The compiler knows that if the else branch is taken, it will never reach the println! because diverge() diverges. Therefore, it's not an error that the else branch doesn't initialize foo.

closure expression

A closure expression denotes a function that maps a list of parameters onto the expression that follows the parameters. Just like a let binding, the closure parameters are irrefutable patterns, whose type annotation is optional and will be inferred from context if not given. Each closure expression has a unique, anonymous type.

Significantly, closure expressions capture their environment, which regular function definitions do not. Without the move keyword, the closure expression infers how it captures each variable from its environment, preferring to capture by shared reference, effectively borrowing all outer variables mentioned inside the closure's body. If needed the compiler will infer that instead mutable references should be taken, or that the values should be moved or copied (depending on their type) from the environment. A closure can be forced to capture its environment by copying or moving values by prefixing it with the move keyword. This is often used to ensure that the closure's lifetime is 'static.

Syntax
ClosureExpression :
   move?
   ( || | | ClosureParameters? | )
   (Expression | -> TypeNoBounds BlockExpression)

ClosureParameters :
   ClosureParam (, ClosureParam)* ,?

ClosureParam :
   OuterAttribute* PatternNoTopAlt ( : Type )?

E.g.

fn ten_times<F>(f: F) where F: Fn(i32) {
    for index in 0..10 {
        f(index);
    }
}

ten_times(|j| println!("hello, {}", j));
// With type annotations
ten_times(|j: i32| -> () { println!("hello, {}", j) });

let word = "konnichiwa".to_owned();
ten_times(move |j| println!("{}, {}", word, j));

namespaces

A namespace is a logical grouping of declared names. Names are segregated into separate namespaces based on the kind of entity the name refers to. Namespaces allow the occurrence of a name in one namespace to not conflict with the same name in another namespace.

Within a namespace, names are organized in a hierarchy, where each level of the hierarchy has its own collection of named entities.

There are several different namespaces that each contain different kinds of entities. The usage of a name will look for the declaration of that name in different namespaces, based on the context.

• Type Namespace containing
  • Module declarations
  • External crate declarations
  • External crate prelude items
  • Struct, union, enum, enum variant declarations
  • Trait item declarations
  • Type aliases
  • Associated type declarations
  • Built-in types:
    • boolean,
    • numeric,
    • and textual
  • Generic type parameters
  • Self type
  • Tool attribute modules
• Value Namespace
  • Function declarations
  • Constant item declarations
  • Static item declarations
  • Struct constructors
  • Enum variant constructors
  • Self constructors
  • Generic const parameters
  • Associated const declarations
  • Associated function declarations
  • Local bindings
    • let,
    • if let,
    • while let,
    • for,
    • match arms,
    • function parameters,
    • closure parameters
  • Captured closure variables
• Macro Namespace
  • macro_rules declarations
  • Built-in attributes
  • Tool attributes
  • Function-like procedural macros
  • Derive macros
  • Derive macro helpers
  • Attribute macros
• Lifetime Namespace
  • Generic lifetime parameters
• Label Namespace
  • Loop labels
  • Block labels

A path is a sequence of one or more path segments separated by a namespace qualifier (::) e.g. std::io

use std::io::{self, Write};
mod m {
    #[clippy::cyclomatic_complexity = "0"]
    pub (in super) fn f1() {}
}

The :: token is required before the opening < for generic arguments to avoid ambiguity with the less-than operator. This is colloquially known as "turbofish" syntax e.g.

(0..10).collect::<Vec<_>>();
Vec::<u8>::with_capacity(1024);

Paths starting with :: are considered to be global paths where the segments of the path start being resolved from a place which differs based on edition. Each identifier in the path must resolve to an item.

pub fn foo() {
    // In the 2018 edition, this accesses `std` via the extern prelude.
    // In the 2015 edition, this accesses `std` via the crate root.
    let now = ::std::time::Instant::now();
    println!("{:?}", now);
}

'self resolves the path relative to the current module. self can only be used as the first segment, without a preceding ::.

fn foo() {}
fn bar() {
    self::foo();
}

Self, with a capital "S", is used to refer to the implementing type within traits and implementations. Self can only be used as the first segment, without a preceding ::.

trait T {
    type Item;
    const C: i32;
    // `Self` will be whatever type that implements `T`.
    fn new() -> Self;
    // `Self::Item` will be the type alias in the implementation.
    fn f(&self) -> Self::Item;
}
struct S;
impl T for S {
    type Item = i32;
    const C: i32 = 9;
    fn new() -> Self {           // `Self` is the type `S`.
        S
    }
    fn f(&self) -> Self::Item {  // `Self::Item` is the type `i32`.
        Self::C                  // `Self::C` is the constant value `9`.
    }
}

super in a path resolves to the parent module. It may only be used in leading segments of the path, possibly after an initial self segment.

mod a {
    pub fn foo() {}
}
mod b {
    pub fn foo() {
        super::a::foo(); // call a's foo function
    }
}
super may be repeated several times after the first super or self to refer to ancestor modules.

mod a {
    fn foo() {}

    mod b {
        mod c {
            fn foo() {
                super::super::foo(); // call a's foo function
                self::super::super::foo(); // call a's foo function
            }
        }
    }
}

crate resolves the path relative to the current crate. crate can only be used as the first segment, without a preceding ::.

fn foo() {}
mod a {
    fn bar() {
        crate::foo();
    }
}

$crate is only used within macro transcribers, and can only be used as the first segment, without a preceding ::. $crate will expand to a path to access items from the top level of the crate where the macro is defined, regardless of which crate the macro is invoked.

pub fn increment(x: u32) -> u32 {
    x + 1
}

#[macro_export]
macro_rules! inc {
    ($x:expr) => ( $crate::increment($x) )
}

cannonical path

Items defined in a module or implementation have a canonical path that corresponds to where within its crate it is defined. All other paths to these items are aliases. The canonical path is defined as a path prefix appended by the path segment the item itself defines.

Implementations and use declarations do not have canonical paths, although the items that implementations define do have them. Items defined in block expressions do not have canonical paths. Items defined in a module that does not have a canonical path do not have a canonical path. Associated items defined in an implementation that refers to an item without a canonical path, e.g. as the implementing type, the trait being implemented, a type parameter or bound on a type parameter, do not have canonical paths.

The path prefix for modules is the canonical path to that module. For bare implementations, it is the canonical path of the item being implemented surrounded by angle (<>) brackets. For trait implementations, it is the canonical path of the item being implemented followed by as followed by the canonical path to the trait all surrounded in angle (<>) brackets.

The canonical path is only meaningful within a given crate. There is no global namespace across crates; an item's canonical path merely identifies it within the crate.

// Comments show the canonical path of the item.

mod a { // crate::a
    pub struct Struct; // crate::a::Struct

    pub trait Trait { // crate::a::Trait
        fn f(&self); // crate::a::Trait::f
    }

    impl Trait for Struct {
        fn f(&self) {} // <crate::a::Struct as crate::a::Trait>::f
    }

    impl Struct {
        fn g(&self) {} // <crate::a::Struct>::g
    }
}

mod without { // crate::without
    fn canonicals() { // crate::without::canonicals
        struct OtherStruct; // None

        trait OtherTrait { // None
            fn g(&self); // None
        }

        impl OtherTrait for OtherStruct {
            fn g(&self) {} // None
        }

        impl OtherTrait for crate::a::Struct {
            fn g(&self) {} // None
        }

        impl crate::a::Trait for OtherStruct {
            fn f(&self) {} // None
        }
    }
}

prelude

A prelude is a collection of names tgat are automatically brought into scope of every module in a crate. These are not part of the crate and cannot be referred by the crate because they are not members of that crate module

There are several different preludes:

• Standard library prelude
• Extern prelude
• Language prelude
• macro_use prelude
• Tool prelude

visibility

Visibility :

• public
  • pub
  • pub ( crate )
  • pub ( self )
  • pub ( super )
  • pub ( in SimplePath )

pub mod outer_mod {
    pub mod inner_mod {
        // This function is visible within `outer_mod`
        pub(in crate::outer_mod) fn outer_mod_visible_fn() {}
        // Same as above, this is only valid in the 2015 edition.
        pub(in outer_mod) fn outer_mod_visible_fn_2015() {}

        // This function is visible to the entire crate
        pub(crate) fn crate_visible_fn() {}

        // This function is visible within `outer_mod`
        pub(super) fn super_mod_visible_fn() {
            // This function is visible since we're in the same `mod`
            inner_mod_visible_fn();
        }

        // This function is visible only within `inner_mod`,
        // which is the same as leaving it private.
        pub(self) fn inner_mod_visible_fn() {}
    }
    pub fn foo() {
        inner_mod::outer_mod_visible_fn();
        inner_mod::crate_visible_fn();
        inner_mod::super_mod_visible_fn();

        // This function is no longer visible since we're outside of `inner_mod`
        // Error! `inner_mod_visible_fn` is private
        //inner_mod::inner_mod_visible_fn();
    }
}

• pub use

//rust allows publicly re-exporting items through a pub use directive. This allows the exported item to be used in the current module through the rules above. 

pub use self::implementation::api;

mod implementation {
    pub mod api {
        pub fn f() {}
    }
}

standard library

TO DO copy these across https://en.wikipedia.org/wiki/Rust_(programming_language)

The std crate provides the standard library features.

• macros - which includes print! and println!
• box
• vectors
• string
• option
• result
• panic
• HashMap
  • HashSet
• Rc
• Arc
• std::thread Threads
• std::sync::mpsc::{Sender, Receiver} - Channels
• std::path::Path - Path
• std::fs::File - File
• std::process::Command - ChildProcess
  • Pipe
• std::fs file system operations

ownership

• ->String https://hermanradtke.com/2015/05/29/creating-a-rust-function-that-returns-string-or-str.html/
• fn ( String ) takes ownership of String

asm

Rust supports the use of inline assembly.

use std::arch::asm;

// Multiply x by 6 using shifts and adds
let mut x: u64 = 4;
unsafe {
    asm!(
        "mov {tmp}, {x}",
        "shl {tmp}, 1",
        "shl {x}, 2",
        "add {x}, {tmp}",
        x = inout(reg) x,
        tmp = out(reg) _,
    );
}
assert_eq!(x, 4 * 6);

Possible uses:

• https://developer.arm.com/documentation/dui0473/m/arm-and-thumb-instructions/bkpt
• https://en.wikipedia.org/wiki/INT_(x86_instruction)#:~:text=The%20INT3%20instruction%20is%20a,to%20set%20a%20code%20breakpoint.

error handling

• ? from trait

unsafety

The rust compiler enforces safety via static analysis. Unsafe operations are those that can potentially violate the memory-safety guarantees of Rust's static semantics.

The following language level features cannot be used in the safe subset of Rust:

• Dereferencing a raw pointer.
• Reading or writing a mutable or external static variable.
• Accessing a field of a union, other than to assign to it.
• Calling an unsafe function (including an intrinsic or foreign function).
• Implementing an unsafe trait.

A block of code can be prefixed with the unsafe keyword, to permit calling unsafe functions or dereferencing raw pointers. By default, the body of an unsafe function is also considered to be an unsafe block; this can be changed by enabling the unsafe_op_in_unsafe_fn lint.

By putting operations into an unsafe block, the programmer states that they have taken care of satisfying the extra safety conditions of all operations inside that block.

An unsafe trait is a trait that comes with extra safety conditions that must be upheld by implementations of the trait. The unsafe trait should come with documentation explaining what those extra safety conditions are.

Such a trait must be prefixed with the keyword unsafe and can only be implemented by unsafe impl blocks.

not unsafe behavious

The Rust compiler does not consider the following behaviors unsafe, though a programmer may (should) find them undesirable, unexpected, or erroneous.

• Deadlocks
• Leaks of memory and other resources
• Exiting without calling destructors
• Exposing randomized base addresses through pointer leaks
• Integer overflow

If a program contains arithmetic overflow, the programmer has made an error. In the following discussion, we maintain a distinction between arithmetic overflow and wrapping arithmetic. The first is erroneous, while the second is intentional.

When the programmer has enabled debug_assert! assertions (for example, by enabling a non-optimized build), implementations must insert dynamic checks that panic on overflow. Other kinds of builds may result in panics or silently wrapped values on overflow, at the implementation's discretion.

In the case of implicitly-wrapped overflow, implementations must provide well-defined (even if still considered erroneous) results by using two's complement overflow conventions.

The integral types provide inherent methods to allow programmers explicitly to perform wrapping arithmetic. For example, i32::wrapping_add provides two's complement, wrapping addition.

The standard library also provides a Wrapping<T> newtype which ensures all standard arithmetic operations for T have wrapping semantics.

See RFC 560 for error conditions, rationale, and more details about integer overflow.

• Logic errors

Safe code may impose extra logical constraints that can be checked at neither compile-time nor runtime. If a program breaks such a constraint, the behavior may be unspecified but will not result in undefined behavior. This could include panics, incorrect results, aborts, and non-termination. The behavior may also differ between runs, builds, or kinds of build.

For example, implementing both Hash and Eq requires that values considered equal have equal hashes. Another example are data structures like BinaryHeap, BTreeMap, BTreeSet, HashMap and HashSet which describe constraints on the modification of their keys while they are in the data structure. Violating such constraints is not considered unsafe, yet the program is considered erroneous and its behavior unpredictable.

linkage

TBD.

debugging

Rust application can be debugged via the wrapper for gdb

rust-gdb

GDB Commands are outlined:

• media:GDB-cheat-sheet.pdf

Alternatively you may debug via #VisualStudio

Problem areas

• changing stack size https://www.reddit.com/r/rust/comments/872fc4/how_to_increase_the_stack_size/

variadic functions

• https://stackoverflow.com/questions/28951503/how-can-i-create-a-function-with-a-variable-number-of-arguments

numeric types

• https://lib.rs/crates/bnum
• https://docs.rs/num-bigint/latest/num_bigint/struct.BigInt.html
• https://docs.rs/num-bigint/latest/num_bigint/struct.BigUint.html
• https://lib.rs/crates/bigdecimal
• https://lib.rs/crates/ibig
• https://lib.rs/crates/fpdec
• https://lib.rs/crates/num-bigfloat
• https://lib.rs/crates/rust_decimal
• https://lib.rs/crates/num-traits
• https://lib.rs/crates/daisycalc
• https://lib.rs/crates/mathru
• https://lib.rs/crates/numbat-cli
• https://lib.rs/crates/rithm
• https://lib.rs/crates/scilib
• https://lib.rs/crates/maths-rs
• https://lib.rs/crates/dec
• https://lib.rs/crates/ode_solvers
• https://lib.rs/crates/ndrustfft
• https://lib.rs/crates/scientific
• https://lib.rs/crates/rpn-c
• https://lib.rs/crates/precise-calc
• https://lib.rs/crates/qalqulator

time

Well time will cause you problem until you understand the various packages:

• std::time - for instance and duration objects
• std::chrono - date/time manipulation
• rustix (Posix bindings) https://crates.io/crates/rustix
• embassy-time https://lib.rs/crates/embassy-time

... there are more.

use chrono::{Local,Utc, NaiveDateTime,DateTime};
use std::time::{Duration,Instant,SystemTime};

fn main() {
    let _a = Utc;
    let _b: Duration = Duration::new(0,0);
    let _c = Instant::now();

    /// instance of time features
    let system_time = SystemTime::now();
    let utc_date:DateTime<Utc> = system_time.into();
    println!("sysTime=[{}]",utc_date);

    
    /// proper time features
    let local_time =  Local::now();      // current date time
    let time = local_time.timestamp();               // timestamp
    let nano = local_time.timestamp_subsec_nanos();
    let utc_time = local_time.naive_utc();  // utc time
    println!("local=[{:?}] utc=[{:?}] timestamp=[{}]",local_time,utc_time,time);
}

PDF

The reference doc

• https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/PDF32000_2008.pdf

crates

• https://crates.io/crates/pdf
• https://crates.io/crates/pdf2
• https://crates.io/crates/pdf-extract
• https://crates.io/crates/mdbook-latex
• https://crates.io/crates/mdbook-pdf
• https://github.com/ralpha/pdf_signing
• lopdf https://crates.io/crates/lopdf
• https://crates.io/crates/pdf_cli
• https://crates.io/crates/pdf-create
• https://crates.io/crates/pdf_form
• pdfium wrapper https://crates.io/crates/pdfium-render
• https://crates.io/crates/pdf-writer
• pandoc wrapper https://crates.io/crates/rsmooth
• html -> pdf https://crates.io/crates/htop
• html -> pdf (uses headless chrome to do the conversion) https://crates.io/crates/html2pdf
• https://crates.io/crates/scannedpdf
• https://crates.io/crates/budgetinvoice
• markdown https://crates.io/crates/crowbook
• markdown https://crates.io/crates/p4d-mdproof
• extract data https://crates.io/crates/cephalon
• bindings https://crates.io/crates/qpdf
• chromium interaction https://crates.io/crates/chromiumoxide
• commic and ebook https://crates.io/crates/eloran
• embedded LaTexX engine https://crates.io/crates/tectonic
• pdf tools https://crates.io/crates/rpdf
• pdf library https://crates.io/crates/pdfdbg

modbus

• https://crates.io/crates/tokio-modbus

graphics

• 2D https://docs.rs/piston2d-graphics/latest/graphics/
• Charts https://docs.rs/charts/latest/charts/
• charming https://github.com/yuankunzhang/charming
• https://crates.io/crates/rgb
• https://crates.io/crates/tiny-skia-path
• https://crates.io/crates/epaint
• https://crates.io/crates/kurbo
• https://crates.io/crates/zeno
• https://crates.io/crates/plotly
• https://crates.io/crates/robust
• https://crates.io/crates/raqote
• GPU https://crates.io/crates/gpu-alloc
• GPU https://crates.io/crates/pixels
• game api https://crates.io/crates/bevy
• image https://crates.io/crates/resize
• https://lib.rs/crates/async-graphql
• https://lib.rs/crates/gtk4
• https://lib.rs/crates/glib
• https://lib.rs/crates/map_3d
• https://lib.rs/crates/stroke

computer vision

• https://lib.rs/crates/opencv

benchmarks and profiling

• microbench https://lib.rs/crates/microbench
• benchmarking using flamegraphs and perf https://www.youtube.com/watch?v=D53T1Ejig1Q
• firestorm https://lib.rs/crates/firestorm
  • inferno https://docs.rs/inferno/latest/inferno/
    • getting started with flamegraphs https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/monitoring_and_managing_system_status_and_performance/getting-started-with-flamegraphs_monitoring-and-managing-system-status-and-performance
    • flamegraphs https://www.brendangregg.com/flamegraphs.html
    • tracing-flame https://lib.rs/crates/tracing-flame
    • https://lib.rs/crates/tracy-client
• perf-event Linux kernel profiler
• iai-callgrind https://lib.rs/crates/iai-callgrind
• critereon https://lib.rs/crates/criterion
• tiny-bench https://lib.rs/crates/tiny-bench
• brunch https://lib.rs/crates/brunch
• countme allocated instances https://lib.rs/crates/countme
• metered https://crates.io/crates/metered-macro
• https://lib.rs/crates/dogstatsd
  • gnup lot http://www.gnuplot.info/
• pyrosocpe mulit-language agents and server for visualisation with dadgerDB back end.
• profiling https://lib.rs/crates/profiling
• puffin https://lib.rs/crates/puffin
• counts https://lib.rs/crates/profiling
• https://lib.rs/crates/usdt
• dhatrs heap profiling https://lib.rs/crates/dhat
• self-meter https://crates.io/crates/self-meter
• self-meter-http https://crates.io/crates/self-meter-http
• prometheus
  • https://github.com/prometheus/prometheus
  • https://crates.io/crates/prometheus-client
  • https://crates.io/crates/open-metrics-client
• metrics https://docs.rs/metrics/0.21.1/metrics/
• metrics-core https://docs.rs/metrics-core/latest/metrics_core/
  • https://docs.rs/metrics-runtime/latest/metrics_runtime/

GUI

GUI framework:

name	production	compatibility
dixosus	?	desktop and web
gtk-rs	yes	cross-platform
fltk-rs	yes	cross-platform
iced	no	cross-platform and web
relm	no	cross-platform
Azul	yes	cross-platform
egui	old	cross-platform
Tauri	yes	desktop and web
Slint	yes	crossplatorm and web (demo only/requires licence)
Druid	yes superceded by Xilim	desktop and web
xilim	?	desktop and web

• GUI https://blog.logrocket.com/state-of-rust-gui-libraries/
• https://docs.rs/piston2d-graphics/latest/graphics/
• NativeWindowsGUI https://github.com/gabdube/native-windows-gui
• GTK https://gtk-rs.org/
• (web) egui https://crates.io/crates/egui
• https://docs.rs/nannou/0.18.1/nannou/
• slint https://madewithslint.com/
• (web) tauri https://tauri.app/
• druid (native) https://github.com/linebender/druid superceeded by xilim.
• xilim https://github.com/linebender/xilem/ (supercedes druid)
  • https://xilem.dev/
  • https://xi.zulipchat.com/
• elm https://guide.elm-lang.org/architecture/
• dioxus (web,app, desktop) https://dioxuslabs.com/

findings

• https://gitlab.com/virtio-fs/virtiofsd

comparative performance

• language performance https://github.com/niklas-heer/speed-comparison
• https://benchmarksgame-team.pages.debian.net/benchmarksgame/box-plot-summary-charts.html
• rust vs C https://benchmarksgame-team.pages.debian.net/benchmarksgame/fastest/rust.html
• rust vs others Mandlebrot https://programming-language-benchmarks.vercel.app/problem/mandelbrot

training videos

• (excellent) start here for beginners by @zubiarfan https://www.youtube.com/watch?v=BpPEoZW5IiY
  • https://github.com/3rfaan/courses/tree/main/Rust/rust-by-practice/src
• https://www.rustadventure.dev/
• Traits and polymorphism https://www.youtube.com/watch?v=CHRNj5oubwc
  • https://www.youtube.com/watch?v=xcygqF5LVmM
• Borrow checker https://www.youtube.com/watch?v=HwupNf9iCJk
  • clone(), copy(), & , &, 'lifetimes mut https://www.youtube.com/watch?v=TJTDTyNdJdY
• smart pointers https://www.youtube.com/watch?v=CTTiaOo4cbY
• data science linfa https://www.youtube.com/watch?v=mlcSpxicx-4
• AI rust https://www.youtube.com/watch?v=FI-8L-hobDY
• Ok Error Result options https://www.youtube.com/watch?v=f82wn-1DPas
• rust macros https://www.youtube.com/watch?v=IsCBibC0PZE
  • https://danielkeep.github.io/tlborm/book/README.html
    • Ook https://danielkeep.github.io/tlborm/book/aeg-ook.html
• testing & mocking rust https://www.youtube.com/watch?v=8XaVlL3lObQ
• universal libraries https://www.youtube.com/watch?v=uKlHwko36c4
  • wasmer https://github.com/wasmerio/wasmer
• log observability parseable https://www.youtube.com/watch?v=2Eg_Keqt1I0
  • https://github.com/parseablehq/parseable
• SQLX https://www.youtube.com/watch?v=v9fnBhzH5u8
• (excellent) introduction to web-application full stack using: axum tower tokio - Reinart Stropek https://www.youtube.com/watch?v=DCpILwGas-M
  • https://github.com/rstropek/rust-api-fxs
• rust-web-app axum https://www.youtube.com/watch?v=3cA_mk4vdWY
  • https://rust10x.com/web
  • https://github.com/rust10x/rust-web-app