Progress: progress.h File Reference


Typedefs
typedef ProgressInfo_struct	PInfo
Functions
PInfo *	P_new (long min, long max)
	Create a new PInfo object.
void	P_set_limits (PInfo *p, long min, long max)
	Set a new minimum and maximum for an existing bar.
void	P_set_width (PInfo *p, unsigned int width)
	Sets the width in characters of an existing bar.
void	P_set_sub_limits (PInfo *p, long submin, long submax)
	Set the sub bar's limits for the given bar.
void	P_set_bar (PInfo *p, char left, char right, char empty, char fill)
	Set the characters used to display the bar chart.
void	P_set_subchar (PInfo *p, char subchar)
	Set the sub-bar progress character.
void	P_set_title (PInfo p, char title)
	Sets the bar's title.
void	P_clear_title (PInfo *p)
	Clears any title previously set.
void	P_set_interval (PInfo *p, double interval)
	Set the interval between the bar being displayed.
void	P_freeze (PInfo *p)
	Freeze progress.
void	P_thaw (PInfo *p)
	Resume progress.
long	P_start (PInfo *p)
	Reset the bar to start now.
void	P_inc (PInfo *p)
	Increment the bar's current position.
void	P_subinc (PInfo *p)
	Increment the sub-bar's current position.
void	P_set (PInfo *p, long cur)
	Sets the progress bar's value directly.
void	P_subset (PInfo *p, long subcur)
	Sets the sub-bar's value directly.
void	P_reset (PInfo *p)
	Reset the bar's current value.
void	P_subreset (PInfo *p)
	Reset the sub-bar's current value.
void	P_finish (PInfo *p)
	Move the bar's current value to the maximum value.
void	P_subfinish (PInfo *p)
	Finish the progress of the sub-bar.
double	P_ratio (PInfo *p)
	Returns the ratio of completion (between 0 and 1).
double	P_subratio (PInfo *p)
	Returns the ratio of the sub-bar completion.
long	P_print (PInfo *p)
	Print the progress bar.
void	P_erase (PInfo *p)
	Erase the bar from the display.
double	P_elapsed (PInfo *p)
	Return the amount of elapsed time spent in processing so far.
double	P_persec (PInfo *p)
	Return the number of values progressed through per second.
double	P_remain (PInfo *p)
	Calculate the remaining number of seconds in processing.
void	P_destroy (PInfo *p)
	Destroy the given PInfo object.

Detailed Description

Typedef Documentation

typedef struct ProgressInfo_struct PInfo

Function Documentation

void P_clear_title ( PInfo * p )

Clears any title previously set.

The given bar object no longer displays a title, and any title that had been allocated to it is discarded.

Parameters:

Progress bar object.

void P_destroy ( PInfo * p )

Destroy the given PInfo object.

This is the destructor function of the PInfo 'object'. It closes any debugging file that had been opened and frees all memory allocated to the object. The object should not be used thereafter and this function attempts to make it so.

Parameters:

Progress bar object.

See also:: P_new

double P_elapsed ( PInfo * p )

Return the amount of elapsed time spent in processing so far.

The duration in seconds between when the bar was created or started, and now, is returned. If the bar has been frozen, any time elapsed since the freeze time is ignored.

Parameters:

Progress bar object.

Returns:: Number of seconds elapsed since the bar was created.

See also:

void P_erase ( PInfo * p )

Erase the bar from the display.

This function prints enough space to completely erase the bar from your display.

Parameters:

Progress bar object.

See also:: P_print

void P_finish ( PInfo * p )

Move the bar's current value to the maximum value.

This function is used to indicate that the work has been completed. If you're breaking out of a loop early because the work has been completed, then this allows that final printing of the progress bar to display completion.

Parameters:

Progress bar object.

See also:

void P_freeze ( PInfo * p )

Freeze progress.

This 'freezes' all progress on the bar. No time is deemed to elapse for the bar after this is called. This makes it useful for stopping the state of a bar after completion of the actual task but before calculations of its intervals per second and so forth. This has no effect if the bar is already frozen.

Parameters:

Progress bar object.

See also:: P_thaw
P_start

void P_inc ( PInfo * p )

Increment the bar's current position.

Calling this increments the bar's current value. It may go beyond the set maximum. This is usually called once per iteration; it saves setting the value of the bar explicitly.

Parameters:

Progress bar object.

See also:

P_set

P_start

P_set_limits

PInfo* P_new	(	long	min,
		long	max
	)

Create a new PInfo object.

Creates a new PInfo object that goes from min to max, and sets it up with the default bar configuration:

The bar characters are set to make the bar look like [==== ]
Bars have no title
Bars will try to fill the screen if possible.
Bars start with cur = min
Bars start counting time from when this object is created.
Bars will update every 0.5 seconds.
Bars will display the bar, and the ETA with fractional seconds, only.
Bars start with no sub-bar. If the bar cannot be set up with a character array to buffer the bar in before printing, or no memory was available to create a new progress bar, you get NULL. If the minimum value is greater than the maximum, they will be swapped.
Parameters:

[in] min Minimum value for the new bar.

[in] max Maximum value for the new bar.

Returns:
A new bar, or NULL if something failed.

double P_persec ( PInfo * p )

Return the number of values progressed through per second.

This function uses the elapsed time (qv P_elapsed()) and the current value, in relation to the minimum and maximum values, to give a calculation of how many 'values' (e.g. iterations) have been performed per second so far. If the bar has a sub-bar, the progress of this sub-bar through its own value range is taken into account in calculating the bar's position.

Parameters:

Progress bar object.

Returns:: The number of iterations per second done so far.

long P_print ( PInfo * p )

Print the progress bar.

Ah, the moment you've been waiting for. This function checks that more time than the print interval has passed; if not, it returns early. If not, it prints whatever components are currently enabled of the bar: the "cur of max" display, the title, the bar with its attendant sub-bar position if required, and the estimated time to completion. The ETC information is using a routine from the pwlib library to print the remaining duration in a short, fixed-length format - basically you get about four significant digits of time precision.

The bar is hard-limited to be between 0 and 100 percent full; while the progress meter itself can be outside these values, the bar will try to maintain a sane display.

The bar prints a carriage return (\r, ctrl-M) before any display in order to overwrite itself. Therefore, printing anything else to standard output while using a bar is discouraged and will cause the bar to appear once per line. Setting the bar's screen width to be too large for the current screen will also give this result.

The function returns the next value at which you should attempt to print the bar given the current estimates of how fast the process is working through the value range and the print interval. It uses P_next_val() or P_next_sub_val() as appropriate (qv). In other words, if the bar currently has sub-bar information, the next sub-bar value is returned, otherwise the next main bar value is returned.

Parameters:

Progress bar object.

See also:

P_set

P_next_val

P_next_sub_val

Returns:: The next value at which to print.

double P_ratio ( PInfo * p )

Returns the ratio of completion (between 0 and 1).

This function calculates the ratio $(cur - min) / (max - min)$ . The completion ratio of the sub-bar is taken into account - it's added as a fractional component to the current value. This will return values outside the range between 0 and 1 if the current value is correspondingly outside its minimum and maximum values.

Parameters:

Progress bar object.

Returns:: The completion ratio between 0 and 1.

double P_remain ( PInfo * p )

Calculate the remaining number of seconds in processing.

As opposed to the elapsed time in processing (qv P_elapsed()), this function uses the number of iterations per second (qv P_persec()) to calculate the estimated time left in processing, if processing continues at its current rate. This is, of course, highly variable in early stages and can still change significantly depending on processor load, data, and other external factors.

Parameters:

Progress bar object.

Returns:: The number of seconds remaining in processing.

void P_reset ( PInfo * p )

Reset the bar's current value.

Resets the current value to the minimum. If you have to restart the loop for some reason, this would be what you use. It does not reset the starting time - in other words, it assumes that you now have to do the work done to get thus far _and_ the rest of the iterations in order to complete the task.

Parameters:

Progress bar object.

See also:: P_start

void P_set	(	PInfo *	p,
		long	cur
	)

Sets the progress bar's value directly.

This sets the position of the bar directly. Use this if you are moving in increments greater than one. For instance, if you are reading a file, and the file's size is the maximum, then you keep a tally of the number of bytes read so far and set the bar's position after each read.

Parameters:

	p	Progress bar object.
	cur	The current position of the bar.

See also:: P_set_limits

void P_set_bar	(	PInfo *	p,
		char	left,
		char	right,
		char	empty,
		char	fill
	)

Set the characters used to display the bar chart.

Sets the characters used to set the left and right edges of the bar chart and the characters that make up the empty and full space within the bar.

Parameters:

	p	Progress bar object.
	left	The character to use at the left of the bar.
	right	The character to use at the right of the bar.
	empty	The character to fill empty (uncompleted) space with.
	fill	The chracter to fill competed space with.

void P_set_interval	(	PInfo *	p,
		double	interval
	)

Set the interval between the bar being displayed.

This sets the interval that the progress bar uses to determine at what iteration to next display the bar. See the working example on bar display for how this is controlled.

Parameters:

	p	Progress bar object.
	interval	The number of seconds between displays - can be fractional.

void P_set_limits	(	PInfo *	p,
		long	min,
		long	max
	)

Set a new minimum and maximum for an existing bar.

Sets a new minimum and maximum for the given bar, and resets the position in the bar to the minimum value. If the minimum value is greater than the maximum, they are swapped before the bar is updated.

Parameters:

	p	Progress bar object.
`[in]`	min	The new minimum value.
`[in]`	max	The new maximum value.

See also:

void P_set_sub_limits	(	PInfo *	p,
		long	submin,
		long	submax
	)

Set the sub bar's limits for the given bar.

This function starts a new sub-bar in the given bar, with the given minimum and maximum values. If the bar had sub-bar information set already, this is set to the new parameters. The sub-bar value is set to the given minimum value. If the minimum is greater than the maximum, they are swapped before the bar is updated.

Parameters:

	p	Progress bar object.
`[in]`	submin	New minimum sub-bar value
`[in]`	submax	New maximum sub-bar value

See also:: P_subreset

void P_set_subchar	(	PInfo *	p,
		char	subchar
	)

Set the sub-bar progress character.

The sub-bar progress is only given as a single character within the bar. This function allows you to set that character.

Parameters:

	p	Progress bar object.
	subchar	The character to put at the progress location of the sub-bar.

void P_set_title	(	PInfo *	p,
		char *	title
	)

Sets the bar's title.

Takes the given string as the new current title of the bar. This string is copied rather than use the original pointer, so you can free the string after it's been sent here if you want. This may change in the future. If a title has been previously allocated, it is overwritten. The title will be shown to the left of the bar chart.

Parameters:

	p	Progress bar object.
	title	The new string to put in the bar's title.

Returns:: ???

Todo:: Maybe this should just take a pointer to the original string rather than strdup'ing it?

void P_set_width	(	PInfo *	p,
		unsigned int	width
	)

Sets the width in characters of an existing bar.

Sets the total width of the bar including all the currently displayed elements.

Parameters:

	p	Progress bar object.
`[in]`	width	New width in characters.

long P_start ( PInfo * p )

Reset the bar to start now.

This starts progress again at the previously set minimum value, optionally thawing the object if it's frozen. Starting the bar is not necessary if it has just been created with P_new. As a side effect, it returns the next value to be iterated through; this is used for setting the next iteration to print.

Parameters:

Progress bar object.

Returns:: The next value at which to attempt printing.

See also:

void P_subfinish ( PInfo * p )

Finish the progress of the sub-bar.

See the P_finish function - this just does the same to the sub-bar.

Parameters:

Progress bar object.

See also:: P_set_sub_limits
P_subreset

void P_subinc ( PInfo * p )

Increment the sub-bar's current position.

This does for the sub-bar what P_inc does for the main bar.

Parameters:

Progress bar object.

See also:: P_inc
P_set_sub_limits

double P_subratio ( PInfo * p )

Returns the ratio of the sub-bar completion.

This function calculates the ratio $(cur - min) / (max - min)$ for the sub-bar alone. The P_ratio function also uses this in its ratio calculation.

Parameters:

Progress bar object.

Returns:: The sub-bar completion ratio between 0 and 1.

See also:: P_ratio

void P_subreset ( PInfo * p )

Reset the sub-bar's current value.

This does the same thing for the sub-bar that P_reset does for the main bar.

Parameters:

Progress bar object.

See also:: P_substart

void P_subset	(	PInfo *	p,
		long	subcur
	)

Sets the sub-bar's value directly.

As P_set sets the main bar's progress, so P_subset sets the sub-bar's progress.

Parameters:

	p	Progress bar object.
	subcur	The current position of the sub-bar.

See also:: P_set
P_set_sub_limits

void P_thaw ( PInfo * p )

Resume progress.

If the bar is currently frozen, the state is 'thawed'. Any time elapsed between the call to freeze the bar and now is added to the start time, thus moving the start time 'later' and thus cancelling out the time spent 'frozen'. If the bar is not frozen, this has no effect.

Parameters:

Progress bar object.

See also:: P_freeze
P_start

`[in]`	min	Minimum value for the new bar.
`[in]`	max	Maximum value for the new bar.

progress.h File Reference

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation