Progress Bar¶

1

import "std/io/progress-bar";

ProgressBar struct¶

A single-line CLI progress bar with percentage, counter, elapsed time and ETA.

The bar redraws itself in place by returning the cursor to the start of the line, so nothing else should be printed to stdout while it is active. Output looks like this:

Downloading [================> ] 42% 420/1000 00:12 ETA 00:17

Constructors¶

ctor¶

1

public p ProgressBar.ctor(unsigned long total, string label = "", unsigned int width = DEFAULT_PROGRESS_BAR_WIDTH)

Construct a progress bar

Parameters

Methods¶

setStyle¶

1

public p ProgressBar.setStyle(char fillChar, char headChar, char emptyChar)

Customize the characters the bar is drawn with

Parameters

setShowCounter¶

1

public p ProgressBar.setShowCounter(bool showCounter)

Show or hide the current/total counter, e.g. if the steps are no meaningful unit for the user

Parameters

setLabel¶

1

public p ProgressBar.setLabel(string label)

Change the label, printed in front of the bar. Takes effect with the next redraw.

Parameters

setTotal¶

1

public p ProgressBar.setTotal(unsigned long total)

Change the number of steps that make up 100 %, e.g. when more work is discovered on the way. The current progress is clamped to the new total.

Parameters

start¶

1

public p ProgressBar.start()

Start the progress bar. This resets the clock the ETA is calculated from and draws the initial bar. Calling it is optional, the first update starts the bar implicitly.

update¶

1

public p ProgressBar.update(unsigned long current)

Set the progress to an absolute value. Values above the total are clamped.

Parameters

setCurrent¶

1

public p ProgressBar.setCurrent(unsigned long current)

Set the progress to an absolute value without drawing the bar. Values above the total are clamped. Useful to render the bar yourself via format().

Parameters

tick¶

1

public p ProgressBar.tick(unsigned long steps = 1ul)

Advance the progress by the given number of steps

Parameters

finish¶

1

public p ProgressBar.finish()

Mark the progress bar as complete, draw it a last time and move the cursor to the next line

redraw¶

1

public p ProgressBar.redraw()

Draw the bar right away, e.g. after changing the label. Does nothing if the bar was not started yet or is finished.

clear¶

1

public p ProgressBar.clear()

Remove the bar from the console and return the cursor to the start of the line, e.g. to print something else. The next update draws the bar again.

getTotal¶

1

public inline f<unsigned long> ProgressBar.getTotal()

Retrieve the total number of steps

Returns: unsigned long — Total steps

getCurrent¶

1

public inline f<unsigned long> ProgressBar.getCurrent()

Retrieve the number of completed steps

Returns: unsigned long — Completed steps

getProgress¶

1

public f<double> ProgressBar.getProgress()

Retrieve the progress as fraction between 0 and 1

Returns: double — Progress fraction

getElapsedMicros¶

1

public f<long> ProgressBar.getElapsedMicros()

Retrieve the time elapsed since the bar was started

Returns: long — Elapsed time in microseconds

getEtaMicros¶

1

public f<long> ProgressBar.getEtaMicros(long elapsedMicros)

Estimate the remaining time, assuming the average rate so far stays constant

Parameters

Returns: long — Estimated remaining time in microseconds, or -1 if no estimate is possible yet

format¶

1

public f<String> ProgressBar.format(long elapsedMicros)

Build the progress bar line for a given elapsed time, without drawing it

Parameters

Returns: String — Formatted progress bar line

Functions¶

formatDuration¶

1

public f<String> formatDuration(long micros)

Format a duration as mm:ss, or hhss if it is one hour or longer

Parameters

Returns: String — Formatted duration, or --:-- if unknown

isStdoutTerminal¶

1

public f<bool> isStdoutTerminal()

Check whether stdout is attached to a terminal. A progress bar should usually only be shown if it is, because the carriage returns it uses to redraw itself clutter redirected output.

Returns: bool — Terminal or not