Struct ProgressRecord

pub struct ProgressRecord { /* private fields */ }

Every step of the underlying iterator, one of these is generated. It contains all the information of how this iterator is progresing. Use the methods to access data on it.

Implementations

impl ProgressRecord

pub fn duration_since_start(&self) -> Duration

Duration since iteration started

pub fn num_done(&self) -> usize

Number of items we’ve generated so far. Will be 0 for the first element

let mut progressor = (0..1_000).progress();
let (state, num) = progressor.next().unwrap();
assert_eq!(state.num_done(), 1);

let mut progressor = (0..1_000).progress().skip(10);
let (state, num) = progressor.next().unwrap();
assert_eq!(state.num_done(), 11);

pub fn previous_record_tm(&self) -> Option<Instant>

The Instant for when the previous record was generated. None if there was no previous record.

This can be useful for calculating fine-grained rates

pub fn started_iterating(&self) -> Instant

Return the time Instant that this iterator started

pub fn rate(&self) -> f64

Number of items per second, calculated from the start

pub fn fraction(&self) -> Option<f64>

How far through the iterator as a fraction, if known. First looks at the assumed_fraction if you have overridden that. Uses the underlying iterator’s .size_hint() method if that is an exact value, falling back to any assumed size (set with .assume_size(...)). Otherwise returns None.

use iter_progress::ProgressableIter;
let mut progressor = (0..1_000).progress().skip(120);
let (state, num) = progressor.next().unwrap();
assert_eq!(num, 120);
assert_eq!(state.fraction(), Some(0.121));

Returns None if we cannot know, e.g. for an infinite iterator

let mut progressor = (0..).progress().skip(120);
let (state, num) = progressor.next().unwrap();
assert_eq!(state.fraction(), None);

pub fn assume_fraction(&mut self, f: impl Into<f64>)

Assume that this is actually at this fraction through If the underlying Iterator doesn’t provide a useful size_hint, but you “know” the real fraction (e.g. if reading from a file), you can override the value for this ProgressRecord. This new value is used for rate & time calculations.

let mut progressor = (0..).progress();
let (mut state, _num) = progressor.next().unwrap();
assert_eq!(state.fraction(), None);     // No fraction possible
// Be we know we're 12% the way through
state.assume_fraction(0.12);
assert_eq!(state.fraction(), Some(0.12));

pub fn percent(&self) -> Option<f64>

Percentage progress through the iterator, if known.

use iter_progress::ProgressableIter;
let mut progressor = (0..1_000).progress().skip(120);
let (state, num) = progressor.next().unwrap();
assert_eq!(state.percent(), Some(12.1));

Returns None if we cannot know, e.g. for an infinite iterator

let mut progressor = (0..).progress().skip(120);
let (state, num) = progressor.next().unwrap();
assert_eq!(state.percent(), None);

pub fn print_every_n_sec<T: Display>(&self, n: f32, msg: T)

Print out msg, but only if there has been n seconds since last printout. (uses print!(), so newline not included)

pub fn do_every_n_sec<F: Fn(&Self)>(&self, n: impl Into<f32>, f: F)

Call this function, but only every n sec (as close as possible). Could be a print statement.

pub fn should_do_every_n_sec(&self, n: impl Into<f32>) -> bool

If we want to do every n sec, should we do it now?

pub fn should_do_every_n_items(&self, n: usize) -> bool

If we want to do every n items, should we do it now?

pub fn print_every_n_items<T: Display>(&self, n: usize, msg: T)

Print out msg, but only if there has been n items. Often you want to print out a debug message every 1,000 items or so. This function does that.

pub fn do_every_n_items<F: Fn(&Self)>(&self, n: usize, f: F)

Do thing but only every n items. Could be a print statement.

takes 2 arguments, n and the function (f) which takes a &ProgressState. f will only be called every n items that pass through the iterator.

for (state, _) in (0..150).progress() {
   state.do_every_n_items(5, |state| {
       println!("Current progress: {}%", state.percent().unwrap());
   });
}

pub fn rolling_average_duration(&self) -> &Option<Duration>

Rolling average time to process each item this iterator is processing if it is recording that. None if it’s not being recorded, or it’s too soon to know (e.g. for the first item).

pub fn rolling_average_rate(&self) -> Option<f64>

Rolling average number of items per second this iterator is processing if it is recording that. None if it’s not being recorded, or it’s too soon to know (e.g. for the first item).

pub fn exp_average_duration(&self) -> &Option<Duration>

Exponential average time to process each item this iterator is processing if it is recording that. None if it’s not being recorded, or it’s too soon to know (e.g. for the first item).

pub fn exp_average_rate(&self) -> Option<f64>

Exponential average number of items per second this iterator is processing if it is recording that. None if it’s not being recorded, or it’s too soon to know (e.g. for the first item).

pub fn eta(&self) -> Option<Duration>

If the total size is know (i.e. we know the .fraction()), calculate the estimated time to arrival, i.e. how long before this is finished.

pub fn estimated_total_time(&self) -> Option<Duration>

If the total size is know (i.e. we know the .fraction()), calculate how long, in total, this iterator would run for. i.e. how long it’s run plus how much longer it has left

Trait Implementations

impl Debug for ProgressRecord

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

Formats the value using the given formatter.