Produces a string showing the path through pages as tracked by a Path object. More...

#include <PathStringGenerator.hpp>

Collaboration diagram for duds::ui::PathStringGenerator:

Classes
struct	TrucatedTitle
	An internal data structure used to track the titles to include in the path string and the length of each string to use. More...

Public Member Functions
	PathStringGenerator ()=default
	Makes a PathStringGenerator with default values. More...

	PathStringGenerator (const std::string &separator, unsigned int mlen=-1)
	Makes a PathStringGenerator with the given title separator and maximum path length. More...

	PathStringGenerator (const std::string &separator, const std::string &ellipsis, unsigned int mlen=-1, unsigned int mtitle=-1)
	Makes a PathStringGenerator with the given title separator, ellipsis, and maximum path length. More...

const std::string &	currentFooter () const
	Returns the string appended to the end of the current page title. More...

void	currentFooter (const std::string &f)
	Changes the string appended to the end of the current page title. More...

const std::string &	currentHeader () const
	Returns the string prepended to the current page title. More...

void	currentHeader (const std::string &h)
	Changes the string prepended to the current page title. More...

const std::string &	ellipsis () const
	Returns the string appended to the end of page titles that are shortened to fit. More...

void	ellipsis (const std::string &e)
	Changes the string appended to the end of page titles that are shortened to fit. More...

std::string	generate (const Path &path) const
	Generates the path string for the given Path object. More...

unsigned int	maxLength () const
	Returns the maximum length of the generated path strings. More...

void	maxLength (unsigned int max)
	Changes the maximum total length of the generated path strings. More...

unsigned int	maxTitleLength () const
	Returns the maximum length allocated to a page title in the output path string. More...

void	maxTitleLength (unsigned int max)
	Changes the maximum length allocated to a page title in the output path string. More...

unsigned int	maxTitles () const
	Returns the maximum number of page titles that may be included in the output path string. More...

void	maxTitles (unsigned int max)
	Changes the maximum number of page titles that may be included in the output path string. More...

unsigned int	minTitleLength () const
	Returns the minimum length for a shortened page title in the output path string. More...

void	minTitleLength (unsigned int min)
	Changes the minimum length for a shortened page title in the output path string. More...

const std::string &	separator () const
	Returns the string used to separate the titles. More...

void	separator (const std::string &s)
	Changes the string used to separate the titles. More...

bool	showForwardPage () const
	True if the page in the forward direction may be included in the output path string. More...

void	showForwardPage (bool show=true)
	Changes if the page in the forward direction may be included in the output path string. More...

bool	showWholeCurrentPage () const
	True when the length of the current page title is not bound by the maximum title length (maxTitleLength()). More...

void	showWholeCurrentPage (bool show=true)
	Changes if the length of the current page title is bound by the maximum output length (true) or by the maximum title length (false; default). More...

Private Member Functions
void	decTitleLen (const TrucatedTitle &tt, int &total) const
	Removes the given title from the total path length, along with the length of the separator and ellipsis if used. More...

std::string::size_type	titleLength (const std::string &title, int &total, unsigned int max) const
	Finds the usable length of the given title and adjusts the total length of the path string. More...

Static Private Member Functions
static int	averageLength (int numtitles, int totalLen, int currLen)
	Computes the average length of the titles, excluding the current page title, and rounds up. More...

Private Attributes
bool	abruptSplit = false
	Break long titles without considering spaces within the title. More...

std::string	ellip
	Last character(s) to use when part of a title is not shown. More...

unsigned int	maxLen = -1
	The maximum length of the output string. More...

unsigned int	maxPageLen = -1
	The maximum length of any single title, with the possibile exception of the current page. More...

unsigned int	maxPages = -1
	The maximum number of titles to show. More...

unsigned int	minPageLen = 4
	The minimum length of any title; if fewer characters are availble, fewer titles will be shown. More...

std::string	postCur
	Marker string that follows the current page title. More...

std::string	preCur
	Marker string that preceds the current page title. More...

std::string	sep
	Separator between page titles. More...

bool	showFwd = true
	True to show one page forward past the current page if such a page exits. More...

bool	wholeCurrent = false
	True to show the entire title of the current page if it will fit within maxLen, and use more than maxTitleLen to fit it. More...

Detailed Description

Produces a string showing the path through pages as tracked by a Path object.

This object has a number of parameters that affect its output:

Function	Default value	Short description
separator()	empty string	put between page titles
ellipsis()	empty string	added to end of shortened titles
currentHeader()	empty string	precedes current title
currentFooter()	empty string	follows current title
maxLength()	-1 (huge maximum)	maximum output length
maxTitles()	-1 (huge maximum)	maximum number of titles
maxTitleLength()	-1 (huge maximum)	maximum length of a title
minTitleLength()	4	minimum length of a shortened title
showForwardPage()	true	allow title in forward direction
showWholeCurrentPage()	false	allow current title longer than maxTitleLength()

The algorithm, invoked by calling generate(), is an attempt to show a few page titles along the path, with priority given first to the current page, then to the page in the back (past) direction, then to the forward page, and finally to pages further in the back direction.

The current page title is bracketed with the currentHeader() and currentFooter() strings. These strings do not count against the title's maximum length. The separator() string is placed between each title, and also does not count toward a title's maximum. Any title that is shortened will have the ellipsis() string appended, which does count toward the title's maximum.

No more than maxTitles() page titles will be included in the path string. Each page title will not be longer than maxTitleLength(), including the ellipsis() string if shortened. The page titles will also not be shorter than minTitleLength() except when the whole title is shorter. The end result will not be longer than maxLength().

The algorithm first gathers all titles that could possibly be included and shortens them to fit within maxTitleLength() characters. It then removes titles until the remainder will more likely be able to fit. This is done considering the average length of the page titles, other than the current title, and removes starting from the farthest in the backwards (past) direction until either the titles may fit or there is only one ahead of the current title. If the titles are still too long, the title in the forward direction, if present, is removed.

After this, if the title string will still be too long, the algorithm will attempt to shorten or remove the remaining titles until they fit. Shortening is done with a preference to show whole words by breaking the title string at spaces. There is a stronger preference to keep the title longer than minTitleLength() so that the title will still offer enough context. Should the shortening method not be able to fit at least the minimum length for the title furthest in the back direction, the title in the opposite direction past the current page is removed, or if that page doesn't exist, the title furthest in the back direction is removed.

Finally, the output string is produced. During the above steps, no strings are copied or altered. Internal data references the strings and tracks the length of each string that will be included.

Note: The code is likely more complicated than required for decent results, and different results could simplify the algorithm.

Author: Jeff Jackowski

Examples:: bppmenu.cpp.

Definition at line 116 of file PathStringGenerator.hpp.

Constructor & Destructor Documentation

◆ PathStringGenerator() [1/3]

duds::ui::PathStringGenerator::PathStringGenerator ( )

default

Makes a PathStringGenerator with default values.

◆ PathStringGenerator() [2/3]

duds::ui::PathStringGenerator::PathStringGenerator	(	const std::string &	separator,
		unsigned int	mlen = `-1`
	)

inline

Makes a PathStringGenerator with the given title separator and maximum path length.

Parameters

separator	The string used in between each title.
mlen	The maximum length of the generated path string.

Definition at line 247 of file PathStringGenerator.hpp.

◆ PathStringGenerator() [3/3]

duds::ui::PathStringGenerator::PathStringGenerator	(	const std::string &	separator,
		const std::string &	ellipsis,
		unsigned int	mlen = `-1`,
		unsigned int	mtitle = `-1`
	)

Makes a PathStringGenerator with the given title separator, ellipsis, and maximum path length.

Parameters

separator	The string used in between each title.
ellipsis	The string put at the end of any title that is shortened to fit in the path string.
mlen	The maximum length of the generated path string.
mtitle	The maximum length of a single title.

Exceptions

PathStringGeneratorParameterError The ellipsis is as long as or longer than the maximum title length.

Definition at line 16 of file PathStringGenerator.cpp.

Member Function Documentation

◆ averageLength()

int duds::ui::PathStringGenerator::averageLength	(	int	numtitles,
		int	totalLen,
		int	currLen
	)

staticprivate

Computes the average length of the titles, excluding the current page title, and rounds up.

Parameters

numtitles	Total number of titles being considered.
totalLen	The total path string length.
currLen	The current page title length.

Returns: The average length of the page titles other than the current page.

Definition at line 144 of file PathStringGenerator.cpp.

Referenced by generate().

◆ currentFooter() [1/2]

const std::string& duds::ui::PathStringGenerator::currentFooter ( ) const

inline

Returns the string appended to the end of the current page title.

Examples:: bppmenu.cpp.

Definition at line 315 of file PathStringGenerator.hpp.

◆ currentFooter() [2/2]

void duds::ui::PathStringGenerator::currentFooter ( const std::string & f )

Changes the string appended to the end of the current page title.

Its length is not counted as part of the title's length.

Parameters

f	The new footer.

Exceptions

PathStringGeneratorParameterError The header and footer are as long as or longer than the maximum path string length.

Definition at line 46 of file PathStringGenerator.cpp.

◆ currentHeader() [1/2]

const std::string& duds::ui::PathStringGenerator::currentHeader ( ) const

inline

Returns the string prepended to the current page title.

Examples:: bppmenu.cpp.

Definition at line 300 of file PathStringGenerator.hpp.

◆ currentHeader() [2/2]

void duds::ui::PathStringGenerator::currentHeader ( const std::string & h )

Changes the string prepended to the current page title.

Its length is not counted as part of the title's length.

Parameters

h	The new header.

Exceptions

PathStringGeneratorParameterError The header and footer are as long as or longer than the maximum path string length.

Definition at line 35 of file PathStringGenerator.cpp.

◆ decTitleLen()

void duds::ui::PathStringGenerator::decTitleLen	(	const TrucatedTitle &	tt,
		int &	total
	)		const

private

Removes the given title from the total path length, along with the length of the separator and ellipsis if used.

Parameters

tt	The title record.
total	The total path length.

Definition at line 137 of file PathStringGenerator.cpp.

Referenced by generate().

◆ ellipsis() [1/2]

const std::string& duds::ui::PathStringGenerator::ellipsis ( ) const

inline

Returns the string appended to the end of page titles that are shortened to fit.

Definition at line 285 of file PathStringGenerator.hpp.

Referenced by PathStringGenerator().

◆ ellipsis() [2/2]

void duds::ui::PathStringGenerator::ellipsis ( const std::string & e )

Changes the string appended to the end of page titles that are shortened to fit.

Parameters

e	The new ellipsis.

Exceptions

PathStringGeneratorParameterError The ellipsis is as long as or longer than the maximum title length.

Definition at line 25 of file PathStringGenerator.cpp.

◆ generate()

std::string duds::ui::PathStringGenerator::generate ( const Path & path ) const

Generates the path string for the given Path object.

This object retains no state information from the Path object. Details on the operation are in this class's documentation.

Precondition: The Path object will not be altered, nor will Page titles be changed, by another thread while this function is running.

Parameters

path	The Path object who's path will be represented in the string.

Returns: A string representing the path using titles from Page objects.

Examples:: bppmenu.cpp.

Definition at line 153 of file PathStringGenerator.cpp.

◆ maxLength() [1/2]

unsigned int duds::ui::PathStringGenerator::maxLength ( ) const

inline

Returns the maximum length of the generated path strings.

Definition at line 330 of file PathStringGenerator.hpp.

◆ maxLength() [2/2]

void duds::ui::PathStringGenerator::maxLength ( unsigned int max )

Changes the maximum total length of the generated path strings.

Parameters

max	The new maximum length.

Exceptions

PathStringGeneratorParameterError The new maximum is too small to accommodate the current header, footer, and separator strings.

Definition at line 57 of file PathStringGenerator.cpp.

◆ maxTitleLength() [1/2]

unsigned int duds::ui::PathStringGenerator::maxTitleLength ( ) const

inline

Returns the maximum length allocated to a page title in the output path string.

This length includes the ellipsis string for titles that are shortened.

Definition at line 361 of file PathStringGenerator.hpp.

◆ maxTitleLength() [2/2]

void duds::ui::PathStringGenerator::maxTitleLength ( unsigned int max )

Changes the maximum length allocated to a page title in the output path string.

This length includes the ellipsis string for titles that are shortened.

Parameters

max	The new maximum title length.

Exceptions

PathStringGeneratorParameterError The new maximum is too small to accommodate the ellipsis string, or is larger than the maximum output length, or is less than the minimum title length.

Definition at line 74 of file PathStringGenerator.cpp.

◆ maxTitles() [1/2]

unsigned int duds::ui::PathStringGenerator::maxTitles ( ) const

inline

Returns the maximum number of page titles that may be included in the output path string.

Definition at line 345 of file PathStringGenerator.hpp.

◆ maxTitles() [2/2]

void duds::ui::PathStringGenerator::maxTitles ( unsigned int max )

inline

Changes the maximum number of page titles that may be included in the output path string.

Parameters

max	The new maximum number of page titles.

Definition at line 353 of file PathStringGenerator.hpp.

◆ minTitleLength() [1/2]

unsigned int duds::ui::PathStringGenerator::minTitleLength ( ) const

inline

Returns the minimum length for a shortened page title in the output path string.

Full titles that are shorter will still be included. The length does not include the ellipsis string for titles that are shortened.

Definition at line 382 of file PathStringGenerator.hpp.

◆ minTitleLength() [2/2]

void duds::ui::PathStringGenerator::minTitleLength ( unsigned int min )

Changes the minimum length for a shortened page title in the output path string.

Full titles that are shorter will still be included. The length does not include the ellipsis string for titles that are shortened.

Parameters

min	The new minimum shortened title length.

Exceptions

PathStringGeneratorParameterError The new minimum is larger than either the maximum output length or the maximum title length.

Definition at line 92 of file PathStringGenerator.cpp.

◆ separator() [1/2]

const std::string& duds::ui::PathStringGenerator::separator ( ) const

inline

Returns the string used to separate the titles.

Definition at line 272 of file PathStringGenerator.hpp.

◆ separator() [2/2]

void duds::ui::PathStringGenerator::separator ( const std::string & s )

inline

Changes the string used to separate the titles.

Definition at line 278 of file PathStringGenerator.hpp.

◆ showForwardPage() [1/2]

bool duds::ui::PathStringGenerator::showForwardPage ( ) const

inline

True if the page in the forward direction may be included in the output path string.

Definition at line 400 of file PathStringGenerator.hpp.

◆ showForwardPage() [2/2]

void duds::ui::PathStringGenerator::showForwardPage ( bool show = true )

inline

Changes if the page in the forward direction may be included in the output path string.

The inclusion is a lower priority than for pages in the back direction, and it requires at least 3 page titles to be shown.

Parameters

show	True to allow showing a page title in the forward direction.

Definition at line 409 of file PathStringGenerator.hpp.

◆ showWholeCurrentPage() [1/2]

bool duds::ui::PathStringGenerator::showWholeCurrentPage ( ) const

inline

True when the length of the current page title is not bound by the maximum title length (maxTitleLength()).

The length is still bound by the maximum output length (maxLength()), in which the current page header and footer strings must also fit. The ellipsis string will also be included if the title must still be shortened to fit.

Definition at line 419 of file PathStringGenerator.hpp.

◆ showWholeCurrentPage() [2/2]

void duds::ui::PathStringGenerator::showWholeCurrentPage ( bool show = true )

inline

Changes if the length of the current page title is bound by the maximum output length (true) or by the maximum title length (false; default).

If bound by the maximum output length (maxLength()), that length will also include the current page header and footer strings, and if the title must be shortened, the ellipsis string as well.

Parameters

show	True to allow the current page title length to be longer than the maximum title length.

Definition at line 431 of file PathStringGenerator.hpp.

◆ titleLength()

std::string::size_type duds::ui::PathStringGenerator::titleLength	(	const std::string &	title,
		int &	total,
		unsigned int	max
	)		const

private

Finds the usable length of the given title and adjusts the total length of the path string.

If the title fits within the given maximum, the whole string is included. If it is too long and abruptSplit is set, it is as shortened to the maximum length. If abruptSplit is clear (default), then the rightmost space in the title that fits within the given maximum will be the length if such a space exists and does not make the title shorter than the minimum. Otherwise it is shortened to the maximum length.

In all cases, the length of the title (returned value) does not include the length of the ellipsis, but the total length adjustment does. If the title is shortened, its length plus the length of the ellipsis will fit within the maximum.

This function ignores the length of the separator and the pre & post current page markers.

Parameters

title	The title string to consider.
total	The total path length. This will be incremented to include the title length. If the whole title does not fit, it will also be incremented by the ellipsis length.
max	The maximum length of the title plus ellipsis.

Returns: The length of the title to use.

Definition at line 105 of file PathStringGenerator.cpp.

Referenced by generate().

Member Data Documentation

◆ abruptSplit

bool duds::ui::PathStringGenerator::abruptSplit = false

private

Break long titles without considering spaces within the title.

Definition at line 164 of file PathStringGenerator.hpp.

Referenced by generate(), and titleLength().

◆ ellip

std::string duds::ui::PathStringGenerator::ellip

private

Last character(s) to use when part of a title is not shown.

Definition at line 124 of file PathStringGenerator.hpp.

Referenced by currentFooter(), currentHeader(), decTitleLen(), ellipsis(), generate(), maxLength(), maxTitleLength(), and titleLength().

◆ maxLen

unsigned int duds::ui::PathStringGenerator::maxLen = -1

private

The maximum length of the output string.

Definition at line 136 of file PathStringGenerator.hpp.

Referenced by currentFooter(), currentHeader(), generate(), maxLength(), maxTitleLength(), and minTitleLength().

◆ maxPageLen

unsigned int duds::ui::PathStringGenerator::maxPageLen = -1

private

The maximum length of any single title, with the possibile exception of the current page.

The length includes the ellipsis if shown.

Definition at line 145 of file PathStringGenerator.hpp.

Referenced by ellipsis(), generate(), maxLength(), maxTitleLength(), and minTitleLength().

◆ maxPages

unsigned int duds::ui::PathStringGenerator::maxPages = -1

private

The maximum number of titles to show.

Definition at line 140 of file PathStringGenerator.hpp.

Referenced by generate(), and maxLength().

◆ minPageLen

unsigned int duds::ui::PathStringGenerator::minPageLen = 4

private

The minimum length of any title; if fewer characters are availble, fewer titles will be shown.

Definition at line 150 of file PathStringGenerator.hpp.

Referenced by generate(), maxTitleLength(), minTitleLength(), and titleLength().

◆ postCur

std::string duds::ui::PathStringGenerator::postCur

private

Marker string that follows the current page title.

Definition at line 132 of file PathStringGenerator.hpp.

Referenced by currentFooter(), currentHeader(), generate(), and maxLength().

◆ preCur

std::string duds::ui::PathStringGenerator::preCur

private

Marker string that preceds the current page title.

Definition at line 128 of file PathStringGenerator.hpp.

Referenced by currentFooter(), currentHeader(), generate(), and maxLength().

◆ sep

std::string duds::ui::PathStringGenerator::sep

private

Separator between page titles.

Definition at line 120 of file PathStringGenerator.hpp.

Referenced by decTitleLen(), generate(), and maxLength().

◆ showFwd

bool duds::ui::PathStringGenerator::showFwd = true

private

True to show one page forward past the current page if such a page exits.

Definition at line 155 of file PathStringGenerator.hpp.

Referenced by generate().

◆ wholeCurrent

bool duds::ui::PathStringGenerator::wholeCurrent = false

private

True to show the entire title of the current page if it will fit within maxLen, and use more than maxTitleLen to fit it.

Definition at line 160 of file PathStringGenerator.hpp.

Referenced by generate().

The documentation for this class was generated from the following files:

Classes

Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ PathStringGenerator() [1/3]

◆ PathStringGenerator() [2/3]

◆ PathStringGenerator() [3/3]

Member Function Documentation

◆ averageLength()

◆ currentFooter() [1/2]

◆ currentFooter() [2/2]

◆ currentHeader() [1/2]

◆ currentHeader() [2/2]

◆ decTitleLen()

◆ ellipsis() [1/2]

◆ ellipsis() [2/2]

◆ generate()

◆ maxLength() [1/2]

◆ maxLength() [2/2]

◆ maxTitleLength() [1/2]

◆ maxTitleLength() [2/2]

◆ maxTitles() [1/2]

◆ maxTitles() [2/2]

◆ minTitleLength() [1/2]

◆ minTitleLength() [2/2]

◆ separator() [1/2]

◆ separator() [2/2]

◆ showForwardPage() [1/2]

◆ showForwardPage() [2/2]

◆ showWholeCurrentPage() [1/2]

◆ showWholeCurrentPage() [2/2]

◆ titleLength()

Member Data Documentation

◆ abruptSplit

◆ ellip

◆ maxLen

◆ maxPageLen

◆ maxPages

◆ minPageLen

◆ postCur

◆ preCur

◆ sep

◆ showFwd

◆ wholeCurrent