Struct drop_tracker::DropTracker

pub struct DropTracker<K> { /* private fields */ }

Creates DropItems and tracks their state.

DropItems can be created using track or try_track and their state can be later checked using state.

DropItems are identified by keys. A key can be of any type that implement the Hash and Eq traits, which include, for example: u32, char, str, …

See the module documentation for details.

Implementations

impl<K> DropTracker<K>

pub fn new() -> Self

Creates a new empty DropTracker.

Examples

use drop_tracker::DropTracker;

let tracker = DropTracker::<u32>::new();
assert_eq!(tracker.tracked().count(), 0);

pub fn tracked(
    &self
) -> impl Clone + Iterator<Item = &K> + ExactSizeIterator + FusedIterator

Returns an iterator over the keys tracked by this DropTracker.

The order of keys returned by this iterator is non deterministic.

Examples

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();
let item_a = tracker.track("a");
let item_b = tracker.track("b");
let item_c = tracker.track("c");

let mut keys = tracker.tracked()
                      .collect::<Vec<&&str>>();
keys.sort();
assert_eq!(keys, [&"a", &"b", &"c"]);

pub fn alive(&self) -> impl Clone + Iterator<Item = &K> + FusedIterator

Returns an iterator over the keys tracked by this DropTracker that are alive.

The order of keys returned by this iterator is non deterministic.

Examples

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();
let item_a = tracker.track("a");
let item_b = tracker.track("b");
let item_c = tracker.track("c");

drop(item_c);

let mut alive_keys = tracker.alive()
                            .collect::<Vec<&&str>>();
alive_keys.sort();
assert_eq!(alive_keys, [&"a", &"b"]);

drop(item_a);
drop(item_b);

assert_eq!(tracker.alive().count(), 0);

pub fn dropped(&self) -> impl Clone + Iterator<Item = &K> + FusedIterator

Returns an iterator over the keys tracked by this DropTracker that have been dropped.

The order of keys returned by this iterator is non deterministic.

Examples

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();
let item_a = tracker.track("a");
let item_b = tracker.track("b");
let item_c = tracker.track("c");

assert_eq!(tracker.dropped().count(), 0);

drop(item_a);
drop(item_b);

let mut alive_keys = tracker.dropped()
                            .collect::<Vec<&&str>>();
alive_keys.sort();
assert_eq!(alive_keys, [&"a", &"b"]);

pub fn forget_all(&mut self)

Forgets all the items tracked by this DropTracker.

The DropItems previously returned by the tracker will still work normally, but it will no longer be possible to query their status after forgetting them.

Examples

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();
assert_eq!(tracker.tracked().count(), 0);

let item_a = tracker.track("a");
let item_b = tracker.track("b");
let item_c = tracker.track("c");
assert_eq!(tracker.tracked().count(), 3);

tracker.forget_all();
assert_eq!(tracker.tracked().count(), 0);

pub fn forget_dropped(&mut self)

Forgets all the items tracked by this DropTracker that have been dropped.

The DropItems previously returned by the tracker will still work normally, but it will no longer be possible to query their status after forgetting them.

Examples

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();
assert_eq!(tracker.tracked().count(), 0);

let item_a = tracker.track("a");
let item_b = tracker.track("b");
let item_c = tracker.track("c");
assert_eq!(tracker.tracked().count(), 3);

// After dropping an item, the item is still tracked
drop(item_a);
drop(item_b);
assert_eq!(tracker.tracked().count(), 3);

// Use `forget_dropped` to lose track of items that have been dropped
tracker.forget_dropped();
assert_eq!(tracker.tracked().count(), 1);

let mut keys = tracker.tracked()
                      .collect::<Vec<&&str>>();
keys.sort();
assert_eq!(keys, [&"c"]);

impl<K: Hash + Eq> DropTracker<K>

pub fn track(&mut self, key: K) -> DropItem<K> where
    K: Clone, 

Creates a new DropItem identified by the given key.

The value held by the DropItem is a clone of the key. Use DropTracker::track_with_value if you wish to specify a custom value.

Panics

Panics if the key is already used by another tracked item.

Call forget, forget_dropped or forget_all if you wish to reuse a key from an item you no longer need to track.

See try_track for a variant of this method that does not panic.

Examples

use drop_tracker::DropTracker;
use drop_tracker::State;

let mut tracker = DropTracker::new();

let item = tracker.track("abc");
assert_eq!(tracker.state("abc"), State::Alive);

drop(item);
assert_eq!(tracker.state("abc"), State::Dropped);

Using the same key twice causes a panic:

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();

let item1 = tracker.track("abc");
let item2 = tracker.track("abc"); // panics!

Use forget to reuse the same key:

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();

let item1 = tracker.track("abc");
let _ = tracker.forget("abc");
let item2 = tracker.track("abc"); // works

pub fn try_track(&mut self, key: K) -> Result<DropItem<K>, CollisionError> where
    K: Clone, 

Creates a new DropItem identified by the given key, or Err if the key is already in use.

The value held by the DropItem is a clone of the key. Use DropTracker::try_track_with_value if you wish to specify a custom value.

See also track.

Examples

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();

let item = tracker.try_track("abc");
assert!(item.is_ok());

let item = tracker.try_track("abc");
assert!(item.is_err()); // key is already used

pub fn track_with_value<V>(&mut self, key: K, value: V) -> DropItem<V>

Creates a new DropItem identified by the given key and holding the given value.

Panics

Panics if the key is already used by another tracked item.

Call forget, forget_dropped or forget_all if you wish to reuse a key from an item you no longer need to track.

See try_track_with_value for a variant of this method that does not panic.

Examples

use drop_tracker::DropTracker;
use drop_tracker::State;

let mut tracker = DropTracker::new();

let item = tracker.track_with_value("abc", vec![1, 2, 3]);
assert_eq!(tracker.state("abc"), State::Alive);

drop(item);
assert_eq!(tracker.state("abc"), State::Dropped);

Using the same key twice causes a panic:

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();

let item1 = tracker.track_with_value("abc", vec![1, 2, 3]);
let item2 = tracker.track_with_value("abc", vec![4, 5, 6]); // panics!

Use forget to reuse the same key:

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();

let item1 = tracker.track_with_value("abc", vec![1, 2, 3]);
let _ = tracker.forget("abc");
let item2 = tracker.track_with_value("abc", vec![4, 5, 6]); // works

pub fn try_track_with_value<V>(
    &mut self,
    key: K,
    value: V
) -> Result<DropItem<V>, CollisionError>

Creates a new DropItem identified by the given key and holding the given value, or Err if the key is already in use.

See also track_with_value.

Examples

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();

let item = tracker.try_track_with_value("abc", vec![1, 2, 3]);
assert!(item.is_ok());

let item = tracker.try_track_with_value("abc", vec![4, 5, 6]);
assert!(item.is_err()); // key is already used

impl<K: Hash + Eq> DropTracker<K>

pub fn state<Q>(&self, key: &Q) -> State where
    K: Borrow<Q>,
    Q: Hash + Eq + ?Sized, 

Checks the state of a DropItem tracked by this DropTracker: alive or dropped.

Panics

Panics if the given key is not tracked.

See try_state for a variant of this method that does not panic.

Examples

use drop_tracker::DropTracker;
use drop_tracker::State;

let mut tracker = DropTracker::new();

let item = tracker.track("abc");
assert_eq!(tracker.state("abc"), State::Alive);

drop(item);
assert_eq!(tracker.state("abc"), State::Dropped);

Querying a key that is not tracked causes a panic:

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();

let item = tracker.track("abc");
let state = tracker.state("def"); // panics!

pub fn try_state<Q>(&self, key: &Q) -> Result<State, NotTrackedError> where
    K: Borrow<Q>,
    Q: Hash + Eq + ?Sized, 

Checks the state of a DropItem tracked by this DropTracker: alive or dropped. Returns Err it the given key is not tracked.

See also state.

Examples

use drop_tracker::DropTracker;
use drop_tracker::NotTrackedError;
use drop_tracker::State;

let mut tracker = DropTracker::new();

let item = tracker.track("abc");
assert_eq!(tracker.try_state("abc"), Ok(State::Alive));
assert_eq!(tracker.try_state("def"), Err(NotTrackedError));

drop(item);
assert_eq!(tracker.try_state("abc"), Ok(State::Dropped));
assert_eq!(tracker.try_state("def"), Err(NotTrackedError));

pub fn forget<Q>(&mut self, key: &Q) -> State where
    K: Borrow<Q>,
    Q: Hash + Eq + ?Sized, 

Forgets an item tracked by this DropTracker, and returns its current state (alive or dropped).

The DropItems previously returned by the tracker will still work normally, but it will no longer be possible to query their status after forgetting them.

Panics

Panics if the given key is not tracked.

See try_forget for a variant of this method that does not panic.

Examples

use drop_tracker::DropTracker;
use drop_tracker::State;

let mut tracker = DropTracker::new();

let item = tracker.track("a");
assert!(tracker.is_tracked("a"));

assert_eq!(tracker.forget("a"), State::Alive);
assert!(!tracker.is_tracked("a"));

Forgetting a key that is not tracked causes a panic:

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();

let item = tracker.track("abc");
let state = tracker.forget("def"); // panics!

pub fn try_forget<Q>(&mut self, key: &Q) -> Result<State, NotTrackedError> where
    K: Borrow<Q>,
    Q: Hash + Eq + ?Sized, 

Forgets an item tracked by this DropTracker, and returns its current state (alive or dropped), or Err if the item is not tracked.

The DropItems previously returned by the tracker will still work normally, but it will no longer be possible to query their status after forgetting them.

See also forget.

Examples

use drop_tracker::DropTracker;
use drop_tracker::NotTrackedError;
use drop_tracker::State;

let mut tracker = DropTracker::new();

let item = tracker.track("a");
assert!(tracker.is_tracked("a"));

assert_eq!(tracker.try_forget("a"), Ok(State::Alive));
assert_eq!(tracker.try_forget("b"), Err(NotTrackedError));

pub fn is_tracked<Q>(&self, key: &Q) -> bool where
    K: Borrow<Q>,
    Q: Hash + Eq + ?Sized, 

Returns true if an item identified by the given key is tracked by this DropTracker, false otherwise.

Examples

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();
assert!(!tracker.is_tracked("abc"));

let item = tracker.track("abc");
assert!(tracker.is_tracked("abc"));

pub fn all_alive<Q, Item, Iter>(
    &self,
    iter: Iter
) -> Result<(), NotAllAliveError<Item>> where
    K: Borrow<Q>,
    Q: Hash + Eq + ?Sized,
    Item: Borrow<Q>,
    Iter: IntoIterator<Item = Item>, 

Returns Ok if all the given keys point to items that are alive, Err otherwise.

An error may be returned in two cases: either a key is not tracked, or it has been dropped.

Examples

use drop_tracker::DropTracker;
use drop_tracker::NotAllAliveError;

let mut tracker = DropTracker::new();

let item1 = tracker.track(1);
let item2 = tracker.track(2);
let item3 = tracker.track(3);
let item4 = tracker.track(4);

drop(item3);
drop(item4);

assert_eq!(tracker.all_alive([1, 2]), Ok(()));

assert_eq!(tracker.all_alive([1, 2, 3, 4, 5, 6]),
           Err(NotAllAliveError {
               dropped: vec![3, 4],
               untracked: vec![5, 6],
           }));

pub fn all_dropped<Q, Item, Iter>(
    &self,
    iter: Iter
) -> Result<(), NotAllDroppedError<Item>> where
    K: Borrow<Q>,
    Q: Hash + Eq + ?Sized,
    Item: Borrow<Q>,
    Iter: IntoIterator<Item = Item>, 

Returns Ok if all the given keys point to items that are dropped, Err otherwise.

An error may be returned in two cases: either a key is not tracked, or it has been dropped.

Examples

use drop_tracker::DropTracker;
use drop_tracker::NotAllDroppedError;

let mut tracker = DropTracker::new();

let item1 = tracker.track(1);
let item2 = tracker.track(2);
let item3 = tracker.track(3);
let item4 = tracker.track(4);

drop(item3);
drop(item4);

assert_eq!(tracker.all_dropped([3, 4]), Ok(()));

assert_eq!(tracker.all_dropped([1, 2, 3, 4, 5, 6]),
           Err(NotAllDroppedError {
               alive: vec![1, 2],
               untracked: vec![5, 6],
           }));

Trait Implementations

impl<K: Debug> Debug for DropTracker<K>

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

Formats the value using the given formatter.

impl<K: Default> Default for DropTracker<K>

fn default() -> DropTracker<K>

Returns the “default value” for a type.