Description:

This class is used to format textual output, like console output.

One central static method is Format, which formats a "paragraph" that starts at a certain index of the managed AString buffer and reaches to its end.

When an instance of the class is created, the members of the class provide the text buffer as well as the other parameters which are needed for the static method. With methods Add, member Formatter is used to append the given parameters and then the new paragraph is formatted using the static method Format.
This way, a longer text might be built by repetitive calls.

Definition at line 22 of file paragraphs.inl.

Collaboration diagram for alib::format::Paragraphs:

[legend]

Public Static Method Index:
static ALIB_DLL void	Format (AString &text, integer startIdx, integer lineWidth, character justifyChar, integer &maxLineWidth, const String &indentFirstLine=nullptr, const String &indentOtherLines=nullptr)

Public Field Index:
AString &	Buffer

integer	DetectedMaxLineWidth =0

SPFormatter	Formatter

AStringMA	IndentFirstLine

AStringMA	IndentOtherLines

std::stack< integer, StdDequeMono< integer > >	IndentSizesFirstLine

std::stack< integer, StdDequeMono< integer > >	IndentSizesOtherLines

character	JustifyChar = '\0'

integer	LineWidth = 0
	Used as parameter lineWidth of static method invocations.

StdVectorMono< character >	MarkerBullets

character	MarkerChar = '@'

Public Method Index:
ALIB_DLL	Paragraphs ()

ALIB_DLL	Paragraphs (AString &externalBuffer)

template<typename TAllocatorArgs>
void	Add (boxing::TBoxes< TAllocatorArgs > &args)

template<typename... BoxedObjects>
Paragraphs &	Add (const BoxedObjects &... args)

template<typename TAllocatorArgs>
void	AddMarked (boxing::TBoxes< TAllocatorArgs > &args)

template<typename... BoxedObjects>
Paragraphs &	AddMarked (const BoxedObjects &... args)

ALIB_DLL Paragraphs &	Clear ()

ALIB_DLL Paragraphs &	PopIndent ()

ALIB_DLL Paragraphs &	PushIndent (const String &indentFirstLine, const String &indentOtherLines=nullptr)

ALIB_DLL Paragraphs &	PushIndent (uinteger qty, character fillChar=' ')

AString &	RemoveLastNewLine ()

Protected Field Index:
MonoAllocator	allocator
	Allocator used for internal container types.

BoxesMA	boxes
	Internally reused list of boxes.

AString	markedBuffer
	Buffer for processing marked text.

size_t	markerBulletLevel =0
	Buffer for processing marked text.

AString	text
	Internal buffer, used for field Paragraphs, if no external string object was given.

Field Details:

◆ allocator

MonoAllocator alib::format::Paragraphs::allocator

protected

Allocator used for internal container types.

Definition at line 29 of file paragraphs.inl.

◆ boxes

BoxesMA alib::format::Paragraphs::boxes

protected

Internally reused list of boxes.

Definition at line 96 of file paragraphs.inl.

◆ Buffer

AString& alib::format::Paragraphs::Buffer

A reference to the text buffer. Either refers to otherwise protected field text or to what was given in alternative construction.

Definition at line 37 of file paragraphs.inl.

◆ DetectedMaxLineWidth

integer alib::format::Paragraphs::DetectedMaxLineWidth =0

This field is increased whenever a line of text added is longer than its current value. Might be used by to detect the maximum line width when field LineWidth is set to 0 and hence no auto wrap is done.

Definition at line 91 of file paragraphs.inl.

◆ Formatter

SPFormatter alib::format::Paragraphs::Formatter

The formatter to use. In the constructor, this shared pointer is initialized with the

ALib Default Formatter, in the case that this object's template character type equals alib::character, or
A shared pointer to a newly created formatter object of a corresponding character type otherwise.

Definition at line 45 of file paragraphs.inl.

◆ IndentFirstLine

AStringMA alib::format::Paragraphs::IndentFirstLine

Used as parameter indent of static method invocations.
The indent string of the first line.

This field can either be manipulated by direct access or preferably with overloaded methods PushIndent and PopIndent.

Definition at line 70 of file paragraphs.inl.

◆ IndentOtherLines

AStringMA alib::format::Paragraphs::IndentOtherLines

Used as parameter indent of static method invocations.
The indent string of text lines, excluding the first line.

This field can either be manipulated by direct access or preferably with overloaded methods PushIndent and PopIndent.

Definition at line 77 of file paragraphs.inl.

◆ IndentSizesFirstLine

std::stack<integer, StdDequeMono<integer> > alib::format::Paragraphs::IndentSizesFirstLine

The stack of indent substring sizes in string IndentFirstLine. Used with PushIndent and PopIndent.

Definition at line 81 of file paragraphs.inl.

◆ IndentSizesOtherLines

std::stack<integer, StdDequeMono<integer> > alib::format::Paragraphs::IndentSizesOtherLines

The stack of indent substring sizes in string IndentOtherLines. Used with PushIndent and PopIndent.

Definition at line 85 of file paragraphs.inl.

◆ JustifyChar

character alib::format::Paragraphs::JustifyChar = '\0'

Used as parameter justifyChar of static method invocations. Usually set to ' ' to enable paragraph width justification.
Defaults to '\0' which disables it.

Definition at line 53 of file paragraphs.inl.

◆ LineWidth

integer alib::format::Paragraphs::LineWidth = 0

Used as parameter lineWidth of static method invocations.

Definition at line 48 of file paragraphs.inl.

◆ markedBuffer

AString alib::format::Paragraphs::markedBuffer

protected

Buffer for processing marked text.

Definition at line 99 of file paragraphs.inl.

◆ markerBulletLevel

size_t alib::format::Paragraphs::markerBulletLevel =0

protected

Buffer for processing marked text.

Definition at line 102 of file paragraphs.inl.

◆ MarkerBullets

StdVectorMono<character> alib::format::Paragraphs::MarkerBullets

The bullet used with increasing bullet depths. Defaults to '*', '-', '*', '-', '*', '-'.

Definition at line 63 of file paragraphs.inl.

◆ MarkerChar

character alib::format::Paragraphs::MarkerChar = '@'

Used to detect special commands given with format strings.

See also: Method AddMarked for more information.

Defaults to '@'.

Definition at line 59 of file paragraphs.inl.

◆ text

AString alib::format::Paragraphs::text

protected

Internal buffer, used for field Paragraphs, if no external string object was given.

Definition at line 32 of file paragraphs.inl.

Constructor(s) / Destructor Details:

◆ Paragraphs() [1/2]

alib::format::Paragraphs::Paragraphs ( )

Parameterless constructor. Internal buffer text will be used with reference Buffer. For field Formatter, Formatter::Default will be used.

Definition at line 40 of file paragraphs.cpp.

◆ Paragraphs() [2/2]

alib::format::Paragraphs::Paragraphs ( AString & externalBuffer )

Alternative constructor that accepts an external buffer to use.

Parameters

externalBuffer The external buffer to use and fill.

Definition at line 57 of file paragraphs.cpp.

Method Details:

◆ Add() [1/2]

template<typename TAllocatorArgs>

void alib::format::Paragraphs::Add ( boxing::TBoxes< TAllocatorArgs > & args )

Appends the given objects args to the internal Buffer with the help of member Formatter. Then, static method Format is invoked, providing our public members as parameters. Finally, a newline sequence is added to Buffer, but only if the buffer is not empty and if it does not already end with a newline sequence.

Exceptions

alib::format::FMTExceptions Rethrows exceptions from the formatter caused by errors in provided args.

Parameters

args	The list of arguments to add.

◆ Add() [2/2]

template<typename... BoxedObjects>

Paragraphs & alib::format::Paragraphs::Add ( const BoxedObjects &... args )

inline

Variadic template argument version of Add.

Parameters

args	The variadic list of arguments to add.

Returns: A reference to ourselves to allow concatenated calls.

Definition at line 184 of file paragraphs.inl.

Here is the call graph for this function:

◆ AddMarked() [1/2]

template<typename TAllocatorArgs>

void alib::format::Paragraphs::AddMarked ( boxing::TBoxes< TAllocatorArgs > & args )

This method implements a pre-processing of the text before Add paragraphs found in the text.

The pre-processing is quite simple. Its purpose is to allow longer strings (e.g., loaded from a resource pool) with multiple paragraphs to be formatted by embedded escape sequences to include indents and nested bullet schemes.

The escape sequences begin with the character stored in field MarkerChar, which defaults to '@'. The following table documents the sequences:

Sequence	Description
@@	Inserts the marker character itself.
@>>	Indent text by two spaces
@<<	Un-indent text by two spaces
@*>	Increases bullet level.
@<*	Decreases bullet level
@P	Inserts a new line (like ' ') but without ending the current and starting a new bullet point.
@HLc	Inserts a horizontal line of width LineWidth using c as fill character.

The nested bullet point characters are received from vector MarkerBullets.

Exceptions

alib::format::FMTExceptions

UnknownMarker
EndmarkerWithoutStart
Rethrows formatter exceptions occurring due to errors in provided args.

Parameters

args	The list of arguments to add.

◆ AddMarked() [2/2]

template<typename... BoxedObjects>

Paragraphs & alib::format::Paragraphs::AddMarked ( const BoxedObjects &... args )

inline

Variadic template argument version of AddMarked.

Exceptions

alib::format::FMTExceptions

Parameters

args	The variadic list of arguments to add.

Returns: A reference to ourselves to allow concatenated calls.

Definition at line 236 of file paragraphs.inl.

Here is the call graph for this function:

◆ Clear()

Paragraphs & alib::format::Paragraphs::Clear ( )

Clears field Buffer.

Returns: A reference to ourselves to allow concatenated calls.

Definition at line 115 of file paragraphs.cpp.

Here is the call graph for this function:

◆ Format()

void alib::format::Paragraphs::Format	(	AString &	text,
		integer	startIdx,
		integer	lineWidth,
		character	justifyChar,
		integer &	maxLineWidth,
		const String &	indentFirstLine = nullptr,
		const String &	indentOtherLines = nullptr )

static

Formats one or more paragraphs (separated by NewLine symbols) with three optional features:

Wrapping of lines longer than lineWidth (word wrap)
Justify the text, which here means "full justification", i.e., format the text to have lines of the exact same width.
Adding an indentation to each line with an optionally different indentation for the first line after a NewLine symbol and subsequent ones.

The paragraph starts at startIdx and all of the rest of the string is treated as one paragraph. New-line character sequences found within the paragraph are considered manual line ends. Hence, no block formatting for lines ending with a new line character is performed.

The method is static and hence can be used with arbitrary buffers. Non-static methods Add invoke this method after adding the given content to the internal buffer. Furthermore, convenience functions and corresponding member variables, simplify the use of this method, when indirectly used through an instance of the class.

Parameters

	text	The text containing the paragraph to format.
	startIdx	The start of the paragraph.
	lineWidth	The width of the line. If `0` or negative, no line wrap is performed.
	justifyChar	If this is unequal to `'\0'` it denotes the fill character used to justify the paragraph. Defaults to `'\0'`, which disables justification.
[out]	maxLineWidth	Provides the maximum width of all text lines written.
	indentFirstLine	The indent string of the first line. Defaults to `nullptr`.
	indentOtherLines	The indent string of subsequent lines. Defaults to `nullptr`.

Definition at line 306 of file paragraphs.cpp.

Here is the call graph for this function:

◆ PopIndent()

Paragraphs & alib::format::Paragraphs::PopIndent ( )

Removes the most recently added indent.

Returns: A reference to ourselves to allow concatenated calls.

Definition at line 100 of file paragraphs.cpp.

Here is the call graph for this function:

◆ PushIndent() [1/2]

Paragraphs & alib::format::Paragraphs::PushIndent	(	const String &	indentFirstLine,
		const String &	indentOtherLines = nullptr )

Add the given strings to members IndentFirstLine and IndentOtherLines.

Parameters

indentFirstLine	The string to add to the current indentation stored in IndentFirstLine.
indentOtherLines	The string to add to the current indentation stored in IndentOtherLines. Defaults to NULL_STRING, which sets it to the same value as indentFirstLine.

Returns: A reference to ourselves to allow concatenated calls.

Definition at line 75 of file paragraphs.cpp.

Here is the call graph for this function:

◆ PushIndent() [2/2]

Paragraphs & alib::format::Paragraphs::PushIndent	(	uinteger	qty,
		character	fillChar = ' ' )

Add a given number of characters (default is spaces) to the indentation strings IndentFirstLine and IndentOtherLines.

Use PopIndent to remove the indent.

Parameters

qty	The quantity of characters to add or remove
fillChar	The character (used only if qty is positive).

Returns: A reference to ourselves to allow concatenated calls.

Definition at line 90 of file paragraphs.cpp.

Here is the call graph for this function:

◆ RemoveLastNewLine()

AString & alib::format::Paragraphs::RemoveLastNewLine ( )

inline

Removes the last new line character at the end of the Buffer.

Returns: A reference to the text object.

Definition at line 249 of file paragraphs.inl.

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

Description:

Public Static Method Index:

Public Field Index:

Public Method Index:

Protected Field Index:

Field Details:

◆ allocator

◆ boxes

◆ Buffer

◆ DetectedMaxLineWidth

◆ Formatter

◆ IndentFirstLine

◆ IndentOtherLines

◆ IndentSizesFirstLine

◆ IndentSizesOtherLines

◆ JustifyChar

◆ LineWidth

◆ markedBuffer

◆ markerBulletLevel

◆ MarkerBullets

◆ MarkerChar

◆ text

Constructor(s) / Destructor Details:

◆ Paragraphs() [1/2]

◆ Paragraphs() [2/2]

Method Details:

◆ Add() [1/2]

◆ Add() [2/2]

◆ AddMarked() [1/2]

◆ AddMarked() [2/2]

◆ Clear()

◆ Format()

◆ PopIndent()

◆ PushIndent() [1/2]

◆ PushIndent() [2/2]

◆ RemoveLastNewLine()