AutoSizes Class Reference

Collaboration diagram for AutoSizes:

Class 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 autosizes any more.
• If a subsequent session contains the very same log-output (aka the same 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 a software changes (or logging verbosity setting is changed), adjustments are performed.

To preserve the information across sessions, this class provides methods to transform it's 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, this class is exposed as a general utility class of ALib strings.

Inner Classes
class	Entry
enum	Types

Public Fields
int	actualIndex

Public Methods
int	actual (Types type, int requestedSize, int growthPadding)
void	consolidate ()
void	exportValues (AString target)
void	importValues (AString source)
void	importValues (AString source, CurrentData session)
void	importValues (Substring source)
void	importValues (Substring source, CurrentData session)
int	next (Types type, int requestedSize, int growthPadding)
void	reset ()
void	start ()
String	toString ()

Protected Fields
ArrayList< Entry >	data = new ArrayList<Entry>()
int	dataSize = 0

Member Function Documentation

actual()

int actual	(	Types	type,
		int	requestedSize,
		int	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.

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.

consolidate()

void consolidate

(

)

---

Consolidates the values. This method is usually not invoked directly. Instead, it is invoked with method importValues.

The method loops through all values and copies the 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".

exportValues()

void exportValues

(

AString

target

)

---

Exports the current session values by converting the stored values to a string representation and appending them to the given AString object.

The format of the entries written into the string is "(T|F,Actual,Measured) which should be self-explanatory.

Parameters

target

The AString to receive the our values

importValues() [1/4]

void importValues

(

AString

source

)

---

Imports values from the given AString using overloaded method importValues.

Parameters

source

The AString that is parsed for the numbers

importValues() [2/4]

void importValues	(	AString	source,
		CurrentData	session
	)

---

Imports values from the given AString using overloaded method importValues.

Parameters

source	The AString that is parsed for the numbers
session	If CurrentData.KEEP the current values are stored to be the last sessions' data and current values are set to 0. If CurrentData.CLEAR, which is the default, both, current values and session values are taken from the string.

importValues() [3/4]

void importValues

(

Substring

source

)

---

Imports values from the given substring by parsing it. The numbers in the string have to be separated by ' ' characters (space). If the provided boolean parameter newSession is set to true, then the current session values are set to 0. Else they are set to be the same as the imported values.

Parameters

source

The Substring that is parsed for the numbers

importValues() [4/4]

void importValues	(	Substring	source,
		CurrentData	session
	)

---

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

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 exportValues), 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.
In debug compilations, an ALIB_DBG.WARNING is written.

Parameters

source	The String that is parsed for the exported data.
session	Denotes if consolidate is to be invoked after import. Defaults to CLEAR.

next()

int next	(	Types	type,
		int	requestedSize,
		int	growthPadding
	)

---

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.

reset()

void reset

(

)

---

Resets the all values, current ones and the once of the currently measured session.

start()

void start

(

)

---

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

toString()

String toString

(

)

---

This is for debugging purposes. E.g. this enables the Eclipse IDE to display object descriptions in the debugger.

Returns

A human readable string representation of this object.

Member Data Documentation

actualIndex

int actualIndex

The actual index requested by next. This is reset to 0 with every invocation of start.

data

ArrayList<Entry> data = new ArrayList<Entry>()

protected

The current and measured sizes.

dataSize

int dataSize = 0

protected

The number of entries used in data. (The list is never cleared, instead entries are reused after a reset).

---

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

• AutoSizes.java