Struct Binding 

pub struct Binding<T>(/* private fields */)
where
    T: 'static;

A Binding<T> represents a mutable value of type T that can be observed.

Bindings provide a reactive way to work with values. When a binding’s value changes, it can notify watchers that have registered interest in the value.

Implementations

impl<T> Binding<T>

where T: 'static + Clone,

pub fn container(value: T) -> Binding<T>

Creates a new binding from a value by wrapping it in a container.

The container provides the reactive capabilities for the value.

impl<T> Binding<T>

where T: 'static,

pub fn custom( custom: impl CustomBinding<Output = T> + Clone + 'static, ) -> Binding<T>

Creates a binding that uses a custom implementation of the CustomBinding trait.

pub fn get(&self) -> T

Gets the current value of the binding.

pub fn get_mut(&self) -> BindingMutGuard<'_, T>

Gets mutable access to the binding’s value through a guard.

When the guard is dropped, the binding is updated with the modified value.

Note: In rust, let _ = binding.get_mut(); DO NOT immediately drop the guard. Since it just binds to a variable named _, the guard will live until the end of the current scope. Please use *guard to modify the value in one line.

Example

use nami::Binding;
let n = Binding::int(10);
*n.get_mut() += 5; // do not bind the guard to a let pattern...even it is `_`

Tip: For better performance when modifying container bindings, consider using the with_mut method instead.

pub fn set(&self, value: T)

Sets the binding to a new value

pub fn take(&self) -> T

where T: Default + Clone,

Takes the value out of the binding, replacing it with the default value.

This is equivalent to std::mem::take and notifies watchers of the change.

Example

use nami::{binding, Binding};
let mut text: Binding<String> = binding("hello");
let taken = text.take();
assert_eq!(taken, "hello");
assert_eq!(text.get(), String::new());

pub fn set_from(&self, value: impl Into<T>)

Sets the binding to a new value with automatic type conversion.

Accepts any value that implements Into<T>, providing the same ergonomic benefits as the binding() constructor.

Examples

use nami::{binding, Binding};

let mut text: Binding<String> = binding("initial");

// Direct &str usage - no .into() or .to_string() needed
text.set_from("updated");
assert_eq!(text.get(), "updated");

let mut count: Binding<i64> = binding(0);   
count.set(42);
assert_eq!(count.get(), 42i64);

pub fn with_mut<R>(&self, f: impl FnOnce(&mut T) -> R) -> R

where T: Clone,

Applies a function to mutably borrow the binding’s value.

This is more efficient than get_mut() for container bindings as it avoids unnecessary cloning. The function receives a mutable reference to the value and any changes will notify watchers when the function completes.

pub fn mapping<Output, Getter, Setter>( source: &Binding<T>, getter: Getter, setter: Setter, ) -> Binding<Output>

where Getter: 'static + Clone + Fn(T) -> Output, Setter: 'static + Clone + Fn(&Binding<T>, Output),

Creates a bidirectional mapping between this binding and another type.

The getter transforms values from this binding’s type to the output type. The setter transforms values from the output type back to this binding’s type.

pub fn filter( &self, filter: impl Clone + Fn(&T) -> bool + 'static, ) -> Binding<T>

where T: 'static,

Creates a binding that only allows values passing a filter function.

When attempting to set a value that doesn’t pass the filter, the operation is ignored.

pub fn condition( &self, condition: impl Clone + Fn(&T) -> bool + 'static, ) -> Binding<bool>

where T: 'static,

Creates a binding that maps this binding’s value to a boolean condition.

The resulting binding is read-only and reflects whether the condition is met.

Example

let number = nami::binding(5i32);
let is_positive = number.condition(|&n: &i32| n > 0);
assert_eq!(is_positive.get(), true);

pub fn equal_to(&self, other: T) -> Binding<bool>

where T: Clone + PartialEq + 'static,

Creates a binding that tracks whether this binding’s value equals a specific value.

The resulting binding is read-only.

Example

let text = nami::binding("hello".to_string());
let is_hello = text.equal_to("hello".to_string());
assert_eq!(is_hello.get(), true);

impl<T> Binding<T>

where T: 'static,

pub fn mailbox_with_executor<E>(&self, executor: E) -> BindingMailbox<T>

where E: LocalExecutor,

Attaches this Binding to a mailbox using a provided executor.

Returns a BindingMailbox which can be cloned and used to send the binding to other tasks for mutation or observation.

pub fn mailbox(&self) -> BindingMailbox<T>

Attaches this Binding to a mailbox using the default native executor.

impl<T> Binding<T>

where T: PartialOrd + 'static,

pub fn range(&self, range: impl RangeBounds<T> + Clone + 'static) -> Binding<T>

Creates a binding that only allows values within a specified range.

pub fn clamp(&self, range: impl RangeBounds<T> + Clone + 'static) -> Binding<T>

where T: Clone,

Creates a binding that clamps values to the specified range.

Values below the range minimum are clamped to the minimum. Values above the range maximum are clamped to the maximum.

impl<T> Binding<T>

where T: Signed,

pub fn sign(&self) -> Binding<bool>

Creates a binding that tracks the sign of this binding’s value.

The resulting binding is true for positive values and false for negative values. Setting true makes the value positive, setting false makes it negative.

Tip: Zero is considered positive.

Example

use nami::Binding;
let number = Binding::int(-10i32);
let sign = number.sign();
assert_eq!(sign.get(), false);

impl Binding<i32>

pub fn int(i: i32) -> Binding<i32>

Creates a new integer binding with the given value.

Example

let counter = nami::Binding::int(42);
assert_eq!(counter.get(), 42);

impl<T> Binding<T>

where T: Clone,

pub fn append<Ele>(&self, ele: Ele)

where T: Extend<Ele>,

Appends an element to the binding’s value and notifies watchers.

The binding’s value must implement Extend for the element type.

Example

let mut text: nami::Binding<String> = nami::binding(String::from("Hello"));
text.append(" World");
assert_eq!(text.get(), "Hello World");

impl<T> Binding<T>

where T: Add<Output = T> + Clone + 'static,

pub fn add_assign(&self, other: T)

Applies the + operation to the binding’s current value and the provided value.

impl<T> Binding<T>

where T: Sub<Output = T> + Clone + 'static,

pub fn sub_assign(&self, other: T)

Applies the - operation to the binding’s current value and the provided value.

impl<T> Binding<T>

where T: Mul<Output = T> + Clone + 'static,

pub fn mul_assign(&self, other: T)

Applies the * operation to the binding’s current value and the provided value.

impl<T> Binding<T>

where T: Div<Output = T> + Clone + 'static,

pub fn div_assign(&self, other: T)

Applies the / operation to the binding’s current value and the provided value.

impl<T> Binding<T>

where T: Rem<Output = T> + Clone + 'static,

pub fn rem_assign(&self, other: T)

Applies the % operation to the binding’s current value and the provided value.

impl<T> Binding<T>

where T: BitAnd<Output = T> + Clone + 'static,

pub fn bitand_assign(&self, other: T)

Applies the & operation to the binding’s current value and the provided value.

impl<T> Binding<T>

where T: BitOr<Output = T> + Clone + 'static,

pub fn bitor_assign(&self, other: T)

Applies the | operation to the binding’s current value and the provided value.

impl<T> Binding<T>

where T: BitXor<Output = T> + Clone + 'static,

pub fn bitxor_assign(&self, other: T)

Applies the ^ operation to the binding’s current value and the provided value.

impl<T> Binding<T>

where T: Shl<Output = T> + Clone + 'static,

pub fn shl_assign(&self, other: T)

Applies the << operation to the binding’s current value and the provided value.

impl<T> Binding<T>

where T: Shr<Output = T> + Clone + 'static,

pub fn shr_assign(&self, other: T)

Applies the >> operation to the binding’s current value and the provided value.

impl<T> Binding<Option<T>>

pub fn unwrap_or_else( &self, default: impl Clone + Fn() -> T + 'static, ) -> Binding<T>

where T: Clone + 'static,

Creates a binding that unwraps the option or uses a default value from a closure.

When setting values on the returned binding, they are wrapped in Some.

Example

let maybe_text = nami::binding(None::<String>);
let text = maybe_text.unwrap_or_else(|| "default".to_string());
assert_eq!(text.get(), "default");

pub fn unwrap_or(&self, default: T) -> Binding<T>

where T: Clone + 'static,

Creates a binding that unwraps the option or uses a default value.

When setting values on the returned binding, they are wrapped in Some.

Example

let maybe_number = nami::binding(None::<i32>);
let number = maybe_number.unwrap_or(42);
assert_eq!(number.get(), 42);

pub fn unwrap_or_default(&self) -> Binding<T>

where T: Default + Clone + 'static,

Creates a binding that unwraps the option or uses the type’s default value.

When setting values on the returned binding, they are wrapped in Some.

Example

let maybe_vec = nami::binding(None::<Vec<i32>>);
let vec: nami::Binding<Vec<i32>> = maybe_vec.unwrap_or_default();
assert!(vec.get().is_empty());

pub fn some_equal_to(&self, equal: T) -> Binding<bool>

where T: Eq + Clone + 'static,

Creates a binding that tracks whether this option contains a specific value.

The resulting binding is true when this option contains Some(equal), and false when it contains Some(other_value) or None. Setting true on the result sets this binding to Some(equal). Setting false has no effect on the binding.

Example

let maybe_text = nami::binding(Some("hello".to_string()));
let is_hello = maybe_text.some_equal_to("hello".to_string());
assert_eq!(is_hello.get(), true);

impl Binding<bool>

pub fn bool(value: bool) -> Binding<bool>

Creates a new boolean binding with the given value.

Example

let flag = nami::Binding::bool(true);
assert_eq!(flag.get(), true);

pub fn toggle(&self)

Toggles the boolean value and notifies watchers.

True becomes false, false becomes true.

Example

let mut flag = nami::binding(false);
flag.toggle();
assert_eq!(flag.get(), true);

pub fn then<T>(&self, if_true: T) -> Binding<Option<T>>

where T: Clone + 'static,

Creates a conditional binding that returns Some(value) when true, None when false.

Setting Some(value) on the result sets this binding to true. Setting None sets this binding to false.

Example

let is_logged_in = nami::binding(true);
let username = is_logged_in.then("alice".to_string());
assert_eq!(username.get(), Some("alice".to_string()));

pub fn then_some<T>(&self, if_true: T) -> Binding<Option<T>>

where T: Clone + 'static,

Creates a conditional binding that returns Some(value) when true, None when false.

This is identical to then() but follows Rust’s Option::then_some() naming convention.

Example

let enabled = nami::binding(false);
let button_text = enabled.then_some("Click me!".to_string());
assert_eq!(button_text.get(), None);

pub fn select<T>(&self, if_true: T, if_false: T) -> Binding<T>

where T: Eq + Clone + 'static,

Creates a binding that selects between two values based on this boolean.

Returns if_true when this binding is true, if_false when false. Setting the if_true value on the result sets this binding to true. Setting the if_false value sets this binding to false.

Example

let dark_mode = nami::binding(false);
let theme = dark_mode.select("dark".to_string(), "light".to_string());
assert_eq!(theme.get(), "light");

pub fn reverse(&self) -> Binding<bool>

Creates a binding that returns the logical inverse of this boolean binding.

When this binding is true, the returned binding is false, and vice versa. Setting a value on the returned binding will set the inverse value on this binding.

Example

let enabled = nami::binding(true);
let disabled = enabled.reverse();
assert_eq!(disabled.get(), false);

impl<T> Binding<T>

where T: Clone + Neg<Output = T> + 'static,

pub fn negate(&self) -> Binding<T>

Creates a binding that produces the negated value of this binding.

Updating the derived binding will reflect the negated value back to the source.

impl<T> Binding<T>

where T: Project,

pub fn project(&self) -> <T as Project>::Projected

Projects this binding into its component parts.

This method uses the Project trait implementation to decompose the binding into separate reactive bindings for each component. Changes to any projected binding will be reflected in the original binding and vice versa.

Examples

use nami::{Binding, binding};

let tuple_binding: Binding<(i32, i32, i32)> = binding((1, 2, 3));
let (mut a, mut b, c) = tuple_binding.project();

// Modify individual projections
a.set(10);
b.set(20);

// Original binding reflects changes
assert_eq!(tuple_binding.get(), (10, 20, 3));

Trait Implementations

impl<T, RHS> Add<RHS> for Binding<T>

where RHS: Signal, T: Add<<RHS as Signal>::Output> + Clone + 'static, <RHS as Signal>::Output: Clone,

type Output = Map<Zip<Binding<T>, RHS>, fn((T, <RHS as Signal>::Output)) -> <T as Add<<RHS as Signal>::Output>>::Output, <T as Add<<RHS as Signal>::Output>>::Output>

The resulting type after applying the + operator.

fn add(self, rhs: RHS) -> <Binding<T> as Add<RHS>>::Output

Performs the + operation.

impl<T, RHS> BitAnd<RHS> for Binding<T>

where RHS: Signal, T: BitAnd<<RHS as Signal>::Output> + Clone + 'static, <RHS as Signal>::Output: Clone,

type Output = Map<Zip<Binding<T>, RHS>, fn((T, <RHS as Signal>::Output)) -> <T as BitAnd<<RHS as Signal>::Output>>::Output, <T as BitAnd<<RHS as Signal>::Output>>::Output>

The resulting type after applying the & operator.

fn bitand(self, rhs: RHS) -> <Binding<T> as BitAnd<RHS>>::Output

Performs the & operation.

impl<T, RHS> BitOr<RHS> for Binding<T>

where RHS: Signal, T: BitOr<<RHS as Signal>::Output> + Clone + 'static, <RHS as Signal>::Output: Clone,

type Output = Map<Zip<Binding<T>, RHS>, fn((T, <RHS as Signal>::Output)) -> <T as BitOr<<RHS as Signal>::Output>>::Output, <T as BitOr<<RHS as Signal>::Output>>::Output>

The resulting type after applying the | operator.

fn bitor(self, rhs: RHS) -> <Binding<T> as BitOr<RHS>>::Output

Performs the | operation.

impl<T, RHS> BitXor<RHS> for Binding<T>

where RHS: Signal, T: BitXor<<RHS as Signal>::Output> + Clone + 'static, <RHS as Signal>::Output: Clone,

type Output = Map<Zip<Binding<T>, RHS>, fn((T, <RHS as Signal>::Output)) -> <T as BitXor<<RHS as Signal>::Output>>::Output, <T as BitXor<<RHS as Signal>::Output>>::Output>

The resulting type after applying the ^ operator.

fn bitxor(self, rhs: RHS) -> <Binding<T> as BitXor<RHS>>::Output

Performs the ^ operation.

impl<T> Clone for Binding<T>

fn clone(&self) -> Binding<T>

Creates a clone of this binding.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Debug for Binding<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T> Default for Binding<T>

where T: Default + Clone + 'static,

fn default() -> Binding<T>

Creates a binding with the default value for type T.

impl<T, RHS> Div<RHS> for Binding<T>

where RHS: Signal, T: Div<<RHS as Signal>::Output> + Clone + 'static, <RHS as Signal>::Output: Clone,

type Output = Map<Zip<Binding<T>, RHS>, fn((T, <RHS as Signal>::Output)) -> <T as Div<<RHS as Signal>::Output>>::Output, <T as Div<<RHS as Signal>::Output>>::Output>

The resulting type after applying the / operator.

fn div(self, rhs: RHS) -> <Binding<T> as Div<RHS>>::Output

Performs the / operation.

impl<T> From<Binding<T>> for Computed<T>

fn from(val: Binding<T>) -> Computed<T>

Converts to this type from the input type.

impl<T, RHS> Mul<RHS> for Binding<T>

where RHS: Signal, T: Mul<<RHS as Signal>::Output> + Clone + 'static, <RHS as Signal>::Output: Clone,

type Output = Map<Zip<Binding<T>, RHS>, fn((T, <RHS as Signal>::Output)) -> <T as Mul<<RHS as Signal>::Output>>::Output, <T as Mul<<RHS as Signal>::Output>>::Output>

The resulting type after applying the * operator.

fn mul(self, rhs: RHS) -> <Binding<T> as Mul<RHS>>::Output

Performs the * operation.

impl<T> Neg for Binding<T>

where T: Clone + Neg<Output = T> + 'static,

fn neg(self) -> <Binding<T> as Neg>::Output

Implements unary negation for bindings.

type Output = Binding<T>

The resulting type after applying the - operator.

impl Not for Binding<bool>

fn not(self) -> <Binding<bool> as Not>::Output

Implements the logical NOT operator for boolean bindings.

type Output = Binding<bool>

The resulting type after applying the ! operator.

impl<T, RHS> Rem<RHS> for Binding<T>

where RHS: Signal, T: Rem<<RHS as Signal>::Output> + Clone + 'static, <RHS as Signal>::Output: Clone,

type Output = Map<Zip<Binding<T>, RHS>, fn((T, <RHS as Signal>::Output)) -> <T as Rem<<RHS as Signal>::Output>>::Output, <T as Rem<<RHS as Signal>::Output>>::Output>

The resulting type after applying the % operator.

fn rem(self, rhs: RHS) -> <Binding<T> as Rem<RHS>>::Output

Performs the % operation.

impl<T, RHS> Shl<RHS> for Binding<T>

where RHS: Signal, T: Shl<<RHS as Signal>::Output> + Clone + 'static, <RHS as Signal>::Output: Clone,

type Output = Map<Zip<Binding<T>, RHS>, fn((T, <RHS as Signal>::Output)) -> <T as Shl<<RHS as Signal>::Output>>::Output, <T as Shl<<RHS as Signal>::Output>>::Output>

The resulting type after applying the << operator.

fn shl(self, rhs: RHS) -> <Binding<T> as Shl<RHS>>::Output

Performs the << operation.

impl<T, RHS> Shr<RHS> for Binding<T>

where RHS: Signal, T: Shr<<RHS as Signal>::Output> + Clone + 'static, <RHS as Signal>::Output: Clone,

type Output = Map<Zip<Binding<T>, RHS>, fn((T, <RHS as Signal>::Output)) -> <T as Shr<<RHS as Signal>::Output>>::Output, <T as Shr<<RHS as Signal>::Output>>::Output>

The resulting type after applying the >> operator.

fn shr(self, rhs: RHS) -> <Binding<T> as Shr<RHS>>::Output

Performs the >> operation.

impl<T> Signal for Binding<T>

where T: 'static,

fn get(&self) -> <Binding<T> as Signal>::Output

Computes the current value of the binding.

fn watch( &self, watcher: impl Fn(Context<<Binding<T> as Signal>::Output>) + 'static, ) -> <Binding<T> as Signal>::Guard

Registers a watcher to be notified when the binding’s value changes.

type Output = T

The type of value produced by this computation.

type Guard = Box<dyn WatcherGuard>

The guard type returned by the watch method that manages watcher lifecycle.

impl<T, RHS> Sub<RHS> for Binding<T>

where RHS: Signal, T: Sub<<RHS as Signal>::Output> + Clone + 'static, <RHS as Signal>::Output: Clone,

type Output = Map<Zip<Binding<T>, RHS>, fn((T, <RHS as Signal>::Output)) -> <T as Sub<<RHS as Signal>::Output>>::Output, <T as Sub<<RHS as Signal>::Output>>::Output>

The resulting type after applying the - operator.

fn sub(self, rhs: RHS) -> <Binding<T> as Sub<RHS>>::Output

Performs the - operation.