Function progress 

pub fn progress(message: impl Into<String>) -> ProgressBarBuilder

Available on crate feature print only.

Progress Bars

Progress bars are a feature in the print system. It is aware of the printing/prompting going on in the console and will keep the bars at the bottom of the console without interferring with the other outputs.

Components

A bar has the following display components

• Step display: Displays the current and total steps. For example, [42/100]. Will not display for bars that are unbounded. Bars that are not unbounded but the total is not set will show total as ?. The step display can also be configured to a style more suitable for displaying bytes (for example downloading or processing file), like 10.0K / 97.3M
• Prefix: A string configured once when launching the progress bar
• Percentage: Percentage display for the current and total steps, For example 42.00%. This can be turned off if not needed
• ETA: Estimated remaining time. This can be turned off if not needed
• Message: A message that can be set while the progress bar is showing. For example, this can be the name of the current file being processed, etc.

With everything displayed, it will look something like this:

X][42/100] prefix: 42.00% ETA 32.35s processing the 42th item

(X) is where the animated spinner is

Progress Tree

You can display progress bars with a hierarchy if desired. The progress bars will be organized as an directed acyclic graph (i.e. a tree). Special characters will be used to draw the tree in the terminal.

Each progress bar holds a strong ref to its parent, and weak refs to all of its children. The printer keeps weak refs to all root progress bars (i.e. one without a parent).

State and Output

Each progress bar can have 3 states: progress, done, and interrupted.

When in progress, the bar will be animated if the output is a terminal. Otherwise, updates will be ignored.

The bar will be done when all handles are dropped if 1 of the following is true:

• The bar has finite total, and current step equals total step
• The bar is unbounded, and .done() is called on any handle

If neither is true when all handles are dropped, the bar becomes interrupted. This makes the bar easier to use with control flows. When the bar is in this state, it will print an interrupted message to the regular print stream, like

X][42/100] prefix: interrupted

This message is customizable when building the progress bar. All of its children that are interrupted will also be printed. All children that are done will only be printed if keep is true for that children (see below). The interrupted message is printed regardless if the output is terminal or not.

When the progress bar is done, it may print a “done message” depending on if it has a parent and the keep option:

Has parent (i.e. is child)	Keep	Behavior
Yes	Yes	Done message will be displayed under the parent, but the bar will disappear completely when the parent is done
Yes	No	The bar will disappear after it’s done
No	Yes	The bar will print a done message to the regular print stream when done, no children will be printed
No	No	The bar will disappear after done, no children will be printed

The done message is also customizable when building the bar. Note (from the table) that it will be effective in some way if the keep option is true. Setting a done message does not automatically set keep to true.

The default done message is something like below, will be displayed in green.

X][100/100] prefix: done

Updating the bar

The progress macro is used to update the progress bar. For example:

let bar = cu::progress("doing something").total(10).spawn();
for i in 0..10 {
    cu::progress!(bar = i, "doing {i}th step");
}
drop(bar);

Building the bar

This function cu::progress will make a ProgressBarBuilder with these default configs:

• Total steps: unbounded
• Keep after done: true
• Show ETA: true (only effective if steps is finite)
• Finish message: Default
• Interrupted message: Default

See ProgressBarBuilder for builder methods

Print Levels

The bar final messages are suppressed at -q and the bar animations are suppressed at -qq

Other considerations

If the progress bar print section exceeds the terminal height, it will probably not render properly. Keep in mind when you are displaying a large number of progress bars.

You can use .max_display_children() to set the maximum number of children to display at a time. However, there is no limit on the number of root progress bars.