This library provides utility functions:
π‘ To learn more about this library, please read how it was built on developerlife.com:
π‘ You can also read all the Rust content on developerlife.com here. Also, the equivalent of this library is available for TypeScript and is called r3bl-ts-utils.
Please add the following to your Cargo.toml file:
toml
[dependencies]
r3bl_rs_utils = "0.6.9"
Store is thread safe and asynchronous (using Tokio). The middleware and subscribers will be run in
asynchronously via Tokio tasks. But the reducer functions will be run in sequence (not in separate
Tokio tasks).
β‘ Any functions or blocks that you write which uses the Redux library will have to be marked
asyncas well. And you will have to spawn the Tokio runtime by using the#[tokio::main]macro. If you use the default runtime then Tokio will use multiple threads and its task stealing implementation to give you parallel and concurrent behavior. You can also use the single threaded runtime; its really up to you.
Here's an example of how to use it. Let's say we have the following action enum, and state struct.
```rust /// Action enum.
pub enum Action { Add(i32, i32), AddPop(i32), Clear, MiddlewareCreateClearAction, }
/// State.
pub struct State {
pub stack: Vec
Here's an example of the reducer function.
rust
// Reducer function (pure).
let reducer_fn = |state: &State, action: &Action| match action {
Action::Add(a, b) => {
let sum = a + b;
State { stack: vec![sum] }
}
Action::AddPop(a) => {
let sum = a + state.stack[0];
State { stack: vec![sum] }
}
Action::Clear => State { stack: vec![] },
_ => state.clone(),
};
Here's an example of an async subscriber function (which are run in parallel after an action is dispatched). The following example uses a lambda that captures a shared object. This is a pretty common pattern that you might encounter when creating subscribers that share state in your enclosing block or scope.
rust
// This shared object is used to collect results from the subscriber function & test it later.
let shared_object = Arc::new(Mutex::new(Vec::<i32>::new()));
// This subscriber function is curried to capture a reference to the shared object.
let subscriber_fn = with(shared_object.clone(), |it| {
let curried_fn = move |state: State| {
let mut stack = it.lock().unwrap();
stack.push(state.stack[0]);
};
curried_fn
});
Here are two types of async middleware functions. One that returns an action (which will get
dispatched once this middleware returns), and another that doesn't return anything (like a logger
middleware that just dumps the current action to the console). Note that both these functions share
the shared_object reference from above.
```rust // This middleware function is curried to capture a reference to the shared object. let mwreturnsnone = with(sharedobject.clone(), |it| { let curriedfn = move |action: Action| { let mut stack = it.lock().unwrap(); match action { Action::Add(, _) => stack.push(-1), Action::AddPop() => stack.push(-2), Action::Clear => stack.push(-3), _ => {} } None }; curried_fn });
// This middleware function is curried to capture a reference to the shared object. let mwreturnsaction = with(sharedobject.clone(), |it| { let curriedfn = move |action: Action| { let mut stack = it.lock().unwrap(); match action { Action::MiddlewareCreateClearAction => stack.push(-4), _ => {} } Some(Action::Clear) }; curried_fn }); ```
Here's how you can setup a store with the above reducer, middleware, and subscriber functions.
rust
// Setup store.
let mut store = Store::<State, Action>::new();
store
.add_reducer(ReducerFnWrapper::new(reducer_fn))
.await
.add_subscriber(SafeSubscriberFnWrapper::new(subscriber_fn))
.await
.add_middleware(SafeMiddlewareFnWrapper::new(mw_returns_none))
.await;
Finally here's an example of how to dispatch an action in a test. You can dispatch actions
asynchronously using dispatch_spawn() which is "fire and forget" meaning that the caller won't
block or wait for the dispatch_spawn() to return. Then you can dispatch actions synchronously if
that's what you would like using dispatch().
```rust // Test reducer and subscriber by dispatching Add and AddPop actions asynchronously. store.dispatchspawn(Action::Add(10, 10)).await; store.dispatch(&Action::Add(1, 2)).await; asserteq!(sharedobject.lock().unwrap().pop(), Some(3)); store.dispatch(&Action::AddPop(1)).await; asserteq!(sharedobject.lock().unwrap().pop(), Some(21)); store.clearsubscribers().await;
// Test async middleware: mwreturnsaction. sharedobject.lock().unwrap().clear(); store .addmiddleware(SafeMiddlewareFnWrapper::new(mwreturnsaction)) .dispatch(&Action::MiddlewareCreateClearAction) .await; asserteq!(store.getstate().stack.len(), 0); asserteq!(sharedobject.lock().unwrap().pop(), Some(-4)); ```
[Arena] and [MTArena] types are the implementation of a
non-binary tree data structure that is
inspired by memory arenas.
Here's a simple example of how to use the [Arena] type:
```rust use r3blrsutils::{ treememoryarena::{Arena, HasId, MTArena, ResultUidList}, utils::{styleprimary, styleprompt}, };
let mut arena = Arena::
Here's how you get weak and strong references from the arena (tree), and tree walk:
```rust use r3blrsutils::{ treememoryarena::{Arena, HasId, MTArena, ResultUidList}, utils::{styleprimary, styleprompt}, };
let mut arena = Arena::
{ assert!(arena.getnodearc(&node1id).issome()); let node1ref = dbg!(arena.getnodearc(&node1id).unwrap()); let node1refweak = arena.getnodearcweak(&node1id).unwrap(); asserteq!(node1ref.read().unwrap().payload, node1value); asserteq!( node1refweak.upgrade().unwrap().read().unwrap().payload, 42 ); }
{ let nodeiddne = 200 as usize; assert!(arena.getnodearc(&nodeiddne).is_none()); }
{ let node1id = 0 as usize; let nodelist = dbg!(arena.treewalkdfs(&node1id).unwrap()); asserteq!(nodelist.len(), 1); asserteq!(node_list, vec![0]); } ```
Here's an example of how to use the [MTArena] type:
```rust use std::{ sync::Arc, thread::{self, JoinHandle}, };
use r3blrsutils::{ treememoryarena::{Arena, HasId, MTArena, ResultUidList}, utils::{styleprimary, styleprompt}, };
type ThreadResult = Vec
let mut handles: Handles = Vec::new();
let arena = MTArena::
// Thread 1 - add root. Spawn and wait (since the 2 threads below need the root). { let arenaarc = arena.getarenaarc(); let thread = thread::spawn(move || { let mut arenawrite = arenaarc.write().unwrap(); let root = arenawrite.addnewnode("foo".to_string(), None); vec![root] }); thread.join().unwrap(); }
// Perform tree walking in parallel. Note the lambda does capture many enclosing variable context. { let arenaarc = arena.getarenaarc(); let fnarc = Arc::new(move |uid, payload| { println!( "{} {} {} Arena weakcount:{} strongcount:{}", styleprimary("walkerfn - closure"), uid, payload, Arc::weakcount(&arenaarc), Arc::weakcount(&arenaarc) ); });
// Walk tree w/ a new thread using arc to lambda.
{
let threadhandle: JoinHandle
let result_node_list = thread_handle.join().unwrap();
println!("{:#?}", result_node_list);
}
// Walk tree w/ a new thread using arc to lambda.
{
let threadhandle: JoinHandle
let result_node_list = thread_handle.join().unwrap();
println!("{:#?}", result_node_list);
} } ```
π There are more complex ways of using [
Arena] and [MTArena]. Please look at these extensive integration tests that put them thru their paces here.
This struct allows users to create a lazy hash map. A function must be provided that computes the values when they are first requested. These values are cached for the lifetime this struct. Here's an example.
```rust use std::sync::atomic::{AtomicUsize, Ordering::SeqCst}; use r3blrsutils::utils::LazyMemoValues;
// These are copied in the closure below. let arcatomiccount = AtomicUsize::new(0); let mut avariable = 123; let mut aflag = false;
let mut generatevaluefn = LazyMemoValues::new(|it| { arcatomiccount.fetchadd(1, SeqCst); avariable = 12; aflag = true; avariable + it });
asserteq!(arcatomiccount.load(SeqCst), 0); asserteq!(generatevaluefn.getref(&1), &13); asserteq!(arcatomiccount.load(SeqCst), 1); asserteq!(generatevaluefn.getref(&1), &13); // Won't regenerate the value. asserteq!(arcatomic_count.load(SeqCst), 1); // Doesn't change. ```
This module contains a set of functions to make it easier to work with terminals.
The following is an example of how to use is_stdin_piped():
rust
fn run(args: Vec<String>) -> Result<(), Box<dyn Error>> {
match is_stdin_piped() {
true => piped_grep(PipedGrepOptionsBuilder::parse(args)?)?,
false => grep(GrepOptionsBuilder::parse(args)?)?,
}
Ok(())
}
The following is an example of how to use readline():
```rust use r3blrsutils::utils::{ printheader, readline, styledimmed, styleerror, styleprimary, style_prompt, };
fn makeaguess() -> String { println!("{}", Blue.paint("Please input your guess.")); let (bytesread, guess) = readline(); println!( "{} {}, {} {}", styledimmed("#bytes read:"), styleprimary(&bytesread.tostring()), styledimmed("You guessed:"), style_primary(&guess) ); guess } ```
Here's a list of functions available in this module:
readline_with_prompt()print_prompt()readline()is_tty()is_stdout_piped()is_stdin_piped()Functions that make it easy to unwrap a value safely. These functions are provided to improve the
ergonomics of using wrapped values in Rust. Examples of wrapped values are <Arc<RwLock<T>>, and
<Option>. These functions are inspired by Kotlin scope functions & TypeScript expression based
language library which can be found
here on r3bl-ts-utils.
Here are some examples.
```rust use r3blrsutils::utils::{ callifsome, unwraparcreadlockandcall, unwraparcwritelockandcall, withmut, }; use r3blrsutils::utils::{ReadGuarded, WriteGuarded}; use r3blrsutils::{ arenatypes::HasId, ArenaMap, FilterFn, NodeRef, ResultUidList, WeakNodeRef, };
if let Some(parentid) = parentidopt { let parentnodearcopt = self.getnodearc(parentid); callifsome(&parentnodearcopt, &|parentnodearc| { unwraparcwritelockandcall(&parentnodearc, &mut |parentnode| { parentnode.children.push(newnode_id); }); }); } ```
Here's a list of functions that are provided:
call_if_some()call_if_none()call_if_ok()call_if_err()with()with_mut()unwrap_arc_write_lock_and_call()unwrap_arc_read_lock_and_call()Here's a list of type aliases provided for better readability:
ReadGuarded<T>WriteGuarded<T>ANSI colorized text https://github.com/ogham/rust-ansi-term helper methods. Here's an example.
```rust use r3blrsutils::utils::{ printheader, readline, styledimmed, styleerror, styleprimary, style_prompt, };
fn makeaguess() -> String { println!("{}", Blue.paint("Please input your guess.")); let (bytesread, guess) = readline(); println!( "{} {}, {} {}", styledimmed("#bytes read:"), styleprimary(&bytesread.tostring()), styledimmed("You guessed:"), style_primary(&guess) ); guess } ```
Here's a list of functions available in this module:
print_header()style_prompt()style_primary()style_dimmed()style_error()π§ WIP - This is an experimental module that isnβt ready yet. It is the first step towards creating
a TUI library that can be used to create sophisticated TUI applications. This is similar to Ink
library for Node.js & TypeScript (that uses React and Yoga). Or kinda like tui built atop
crossterm (and not termion).
π§βπ¬ This library is in early development.
Please report any issues to the issue tracker. And if you have any feature requests, feel free to add them there too π.