Description:

This class stores and manages tabulator positions and field sizes. The class supports a simple session handling, by storing each value once for the actual output session and a second time for a future session. The motivation for writing this class came from the requirements of logging library ALox. The goals here are:

During a logging session, log output should be as much tabular as possible.
On the same time, the log output should be as "narrow" as possible.

If used correctly, this class helps to achieve the following:

A new log-output session increases tab stops and field widths during execution as needed.
If values need to be increased, a certain amount of "extra padding" might be added to avoid too many small increments.
Once all tab stops or fields have been logged with values of their maximum size, the log output will not vary in respect to tab stops and auto-sizes anymore.
If a subsequent session contains the very same log-output (aka the same maximum of requested tab positions and field width), all extra space is removed and the log output is 100% tabular beginning with the session start.
If a subsequent session contains smaller values, then this session is formatted with the (still larger) width of the previous session. After that, the next session will use the smaller sizes.

This approach very well guarantees stable log output widths across sessions. Only if the execution path of software changes (or logging verbosity setting is changed), adjustments are performed.

To preserve the information across sessions, this class provides methods to transform its information from and to string representations which can be stored in configuration files.

As the use case of this class is not restricted to log output, but can be used in general when working with strings, it became a utility class of module ALib Strings.

See also

The use of this class with field FormatterPythonStyle::Sizes.
The use of this class within ALox configuration variable FormatAutoSizes.

Definition at line 53 of file autosizes.hpp.

#include <autosizes.hpp>

Collaboration diagram for AutoSizes:

[legend]

Inner Type Index:
struct	Entry
	Actual and current session entries of tab stop indexes, respectively field widths. More...

Public Type Index:
enum class	Types { Tabstop , Field }
	The entry type, tab stop or field width. More...

Public Field Index:
unsigned int	ActualIndex

bool	WriteProtected = false

Public Method Index:
ALIB_API integer	Actual (Types type, integer requestedSize, integer growthPadding)

ALIB_API void	Consolidate ()

ALIB_API void	Export (AString &target)

ALIB_API void	Import (const String &source, lang::CurrentData session=lang::CurrentData::Clear)

bool	IsChanged () const

integer	Next (Types type, integer requestedSize, integer growthPadding)

void	Reset ()

void	Restart (unsigned int startIdx=0)

bool	SetUnchanged ()

Protected Field Index:
std::vector< Entry >	data
	The current and measured sizes.

bool	dirty
	Determines whether any value was changed sincel last Reset.

Enumeration Details:

◆ Types

enum class Types

strong

The entry type, tab stop or field width.

Enumerator
Tabstop	denotes a tab stop entry.
Field	denotes a field width entry.

Definition at line 61 of file autosizes.hpp.

Field Details:

◆ ActualIndex

unsigned int ActualIndex

The actual index requested by Next. This field is reset to 0 with every invocation of Start. The field is public and may be read and manipulated, which is considered "expert use".

Definition at line 70 of file autosizes.hpp.

◆ data

std::vector<Entry> data

protected

The current and measured sizes.

Definition at line 93 of file autosizes.hpp.

◆ dirty

bool dirty

protected

Determines whether any value was changed sincel last Reset.

Definition at line 96 of file autosizes.hpp.

◆ WriteProtected

bool WriteProtected = false

If set, method Actual will not update the values, but instead return the requested value.
Defaults to false.

Definition at line 105 of file autosizes.hpp.

Method Details:

◆ Actual()

integer Actual	(	Types	type,
		integer	requestedSize,
		integer	growthPadding )

Returns the actual auto value stored, respectively, if the given requested size is higher than what is stored, stores and returns the requested size.

In the latter case, the given extra growth is added to the requested size, but only if the value was set at least once before. In other words, the extra size is added only with the second growth and each subsequent one.

The requested size in addition replaces the current "session" value if it is higher than the currently stored value. To this value, the growth padding is not added.

The whole mechanism can be disabled by setting flag WriteProtected. If so, this method just returns requestedSize

If any of the values are changed, a call to IsChanged will return true.

Parameters

type	The type of entry.
requestedSize	The minimum size that is requested.
growthPadding	Added to the new size, if the requested size is greater than the stored size and if the stored size does not equal `-1`.

Returns: The (new) size of the auto field.

Definition at line 19 of file autosizes.cpp.

◆ Consolidate()

void Consolidate ( )

Consolidates the values. This method is usually not invoked directly. Instead, it is invoked with method Import. The method loops through all values and copies the current session values to the actual ones. The difference of both values is summed up during the loop and entries of type Types::Tabstop are adjusted by that difference. As a result, the new values represent the smallest output format that fits all rows, if the same output is performed as in the previous "session".

Definition at line 130 of file autosizes.cpp.

◆ Export()

void Export ( AString & target )

Exports the current session values by serializing the stored values into to the given AString object.

For each current entry in this object, "T|F Actual[,session] is written, separated by a forward slash '/'. The session value is written only in case it differs from the actual value. Furthermore, if field WriteProtected is set, an exclamation mark '!' will be written as a first character. With that, the complete syntax is:

     [!] [ T|F Actual[,session] ]   [/ T|F Actual[,session] ]

This method clears the internal flag that tracks changes, hence after an invocation, IsChanged returns false.

Parameters

target The AString to receive the our values

Definition at line 58 of file autosizes.cpp.

Here is the call graph for this function:

◆ Import()

void Import	(	const String &	source,
		lang::CurrentData	session = lang::CurrentData::Clear )

Imports values from the given String by parsing it. Usually, string data are used for importing values was previously generated with method Export.

If parameter session equals Clear (which is the default), then after the import, method Consolidate is invoked.

Note: Parsing is 100% error-tolerant. If the given string does not contain what is expected (see method Export), then only a part or just nothing is imported. This is due to the purpose of this class, which is to allow nicer, tabbed output. If this is not possible due to import problems, the system should work normally still. With debug-builds, an ALIB_WARNING is written in this case.

This method clears the internal flag that tracks changes, hence after an invocation, IsChanged returns false.

Parameters

source	The String that is parsed for the exported data.
session	Denotes if Consolidate is to be invoked after import. Defaults to Clear, which performs consolidation.

Definition at line 88 of file autosizes.cpp.

Here is the call graph for this function:

◆ IsChanged()

bool IsChanged ( ) const

inline

Determines whether any value was changed since construction, or the last invocation of methods Import, Export or SetUnchanged.

Returns: true if any entry was changed, false otherwise.

Definition at line 114 of file autosizes.hpp.

◆ Next()

integer Next	(	Types	type,
		integer	requestedSize,
		integer	growthPadding )

inline

Invokes Actual and then increases the internal position counter.

Parameters

type	The type of entry.
requestedSize	The minimum size that is requested.
growthPadding	Added to the new size if the requested size is greater than the stored size and if the stored size does not equal `-1`.

Returns: The (new) size of the auto field.

Definition at line 174 of file autosizes.hpp.

Here is the call graph for this function:

◆ Reset()

void Reset ( )

inline

Resets all values, the current ones and the ones of the currently measured session, to 0 and invokes Restart().

Definition at line 109 of file autosizes.hpp.

Here is the call graph for this function:

◆ Restart()

void Restart ( unsigned int startIdx = 0 )

inline

Initializes a new query sequence, which is a series of invocations of method Next.

Parameters

startIdx The tab stop or field size position to continue with.

Definition at line 136 of file autosizes.hpp.

◆ SetUnchanged()

bool SetUnchanged ( )

inline

Same as IsChanged(), but clears the internal flag.

Returns: true if any entry was changed, false otherwise.

Definition at line 118 of file autosizes.hpp.

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

Description:

Inner Type Index:

Public Type Index:

Public Field Index:

Public Method Index:

Protected Field Index:

Enumeration Details:

◆ Types

Field Details:

◆ ActualIndex

◆ data

◆ dirty

◆ WriteProtected

Method Details:

◆ Actual()

◆ Consolidate()

◆ Export()

◆ Import()

◆ IsChanged()

◆ Next()

◆ Reset()

◆ Restart()

◆ SetUnchanged()