Trait Tap

pub trait Tap
where
    Self: Sized,
{
    // Provided methods
    fn tap(self, func: impl FnOnce(&Self)) -> Self { ... }
    fn tap_mut(self, func: impl FnOnce(&mut Self)) -> Self { ... }
    fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self
       where Self: Borrow<B>,
             B: ?Sized { ... }
    fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self
       where Self: BorrowMut<B>,
             B: ?Sized { ... }
    fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self
       where Self: AsRef<R>,
             R: ?Sized { ... }
    fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self
       where Self: AsMut<R>,
             R: ?Sized { ... }
    fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self
       where Self: Deref<Target = T>,
             T: ?Sized { ... }
    fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self
       where Self: DerefMut + Deref<Target = T>,
             T: ?Sized { ... }
    fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self { ... }
    fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self { ... }
    fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self
       where Self: Borrow<B>,
             B: ?Sized { ... }
    fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self
       where Self: BorrowMut<B>,
             B: ?Sized { ... }
    fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self
       where Self: AsRef<R>,
             R: ?Sized { ... }
    fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self
       where Self: AsMut<R>,
             R: ?Sized { ... }
    fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self
       where Self: Deref<Target = T>,
             T: ?Sized { ... }
    fn tap_deref_mut_dbg<T>(self, func: impl FnOnce(&mut T)) -> Self
       where Self: DerefMut + Deref<Target = T>,
             T: ?Sized { ... }
}

Point-free value inspection and modification.

This trait provides methods that permit viewing the value of an expression without requiring a new let binding or any other alterations to the original code other than insertion of the .tap() call.

The methods in this trait do not perform any view conversions on the value they receive; it is borrowed and passed directly to the effect argument.

Provided Methods

fn tap(self, func: impl FnOnce(&Self)) -> Self

Immutable access to a value.

This function permits a value to be viewed by some inspecting function without affecting the overall shape of the expression that contains this method call. It is useful for attaching assertions or logging points into a multi-part expression.

Examples

Here we use .tap() to attach logging tracepoints to each stage of a value-processing pipeline.

use tap::tap::Tap;

let end = make_value()
  // this line has no effect on the rest of the code
  .tap(|v| log!("The produced value was: {}", v))
  .process_value();

fn tap_mut(self, func: impl FnOnce(&mut Self)) -> Self

Mutable access to a value.

This function permits a value to be modified by some function without affecting the overall shape of the expression that contains this method call. It is useful for attaching modifier functions that have an &mut Self -> () signature to an expression, without requiring an explicit let mut binding.

Examples

Here we use .tap_mut() to sort an array without requring multiple bindings.

use tap::tap::Tap;

let sorted = [1i32, 5, 2, 4, 3]
  .tap_mut(|arr| arr.sort());
assert_eq!(sorted, [1, 2, 3, 4, 5]);

Without tapping, this would be written as

let mut received = [1, 5, 2, 4, 3];
received.sort();
let sorted = received;

The mutable tap is a convenient alternative when the expression to produce the collection is more complex, for example, an iterator pipeline collected into a vector.

fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self

where Self: Borrow<B>, B: ?Sized,

Immutable access to the Borrow<B> of a value.

This function is identcal to Tap::tap, except that the effect function recevies an &B produced by Borrow::<B>::borrow, rather than an &Self.

fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self

where Self: BorrowMut<B>, B: ?Sized,

Mutable access to the BorrowMut<B> of a value.

This function is identical to Tap::tap_mut, except that the effect function receives an &mut B produced by BorrowMut::<B>::borrow_mut, rather than an &mut Self.

fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self

where Self: AsRef<R>, R: ?Sized,

Immutable access to the AsRef<R> view of a value.

This function is identical to Tap::tap, except that the effect function receives an &R produced by AsRef::<R>::as_ref, rather than an &Self.

fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self

where Self: AsMut<R>, R: ?Sized,

Mutable access to the AsMut<R> view of a value.

This function is identical to Tap::tap_mut, except that the effect function receives an &mut R produced by AsMut::<R>::as_mut, rather than an &mut Self.

fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self

where Self: Deref<Target = T>, T: ?Sized,

Immutable access to the Deref::Target of a value.

This function is identical to Tap::tap, except that the effect function receives an &Self::Target produced by Deref::deref, rather than an &Self.

fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self

where Self: DerefMut + Deref<Target = T>, T: ?Sized,

Mutable access to the Deref::Target of a value.

This function is identical to Tap::tap_mut, except that the effect function receives an &mut Self::Target produced by DerefMut::deref_mut, rather than an &mut Self.

fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self

Calls .tap() only in debug builds, and is erased in release builds.

fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self

Calls .tap_mut() only in debug builds, and is erased in release builds.

fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self

where Self: Borrow<B>, B: ?Sized,

Calls .tap_borrow() only in debug builds, and is erased in release builds.

fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self

where Self: BorrowMut<B>, B: ?Sized,

Calls .tap_borrow_mut() only in debug builds, and is erased in release builds.

fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self

where Self: AsRef<R>, R: ?Sized,

Calls .tap_ref() only in debug builds, and is erased in release builds.

fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self

where Self: AsMut<R>, R: ?Sized,

Calls .tap_ref_mut() only in debug builds, and is erased in release builds.

fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self

where Self: Deref<Target = T>, T: ?Sized,

Calls .tap_deref() only in debug builds, and is erased in release builds.

fn tap_deref_mut_dbg<T>(self, func: impl FnOnce(&mut T)) -> Self

where Self: DerefMut + Deref<Target = T>, T: ?Sized,

Calls .tap_deref_mut() only in debug builds, and is erased in release builds.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<T> Tap for T

where T: Sized,