Description:

The (one and only) "throwable" used with ALib C++ Library .

Please consult the Programmer's Manual of module ALib BaseCamp for detailed information about this class and its use.

In short, this class implements the following "exception paradigm":

There is only one exception type.
With creation, a first "message" is added to the list of messages.
While unwinding the stack new messages may be added to the list.
A new message may either add information to the previous entry or may change the meaning of the exception.
Messages contain IDs of arbitrary scoped enumeration types . This allows structured processing of Exceptions.

This type uses a smart memory model leveraging class MonoAllocator which places all internal data in MonoAllocator , even this object itself! With that, exceptions usually perform only one single dynamic allocation, even if various messages with various data objects (boxes ) are attached.

Although the footprint (sizeof) of the class is just the size of a pointer (One into the first chunk of memory of the monotonic allocator), objects of this type have to (can only) be caught by reference. Copy-construction and assignment is deleted.

Definition at line 129 of file exception.hpp.

#include <exception.hpp>

Inheritance diagram for Exception:

[legend]

Collaboration diagram for Exception:

[legend]

Inner Type Index:
class	IteratorType

Public Type Index:
using	ConstForwardIterator = IteratorType <const Message>

using	ForwardIterator = IteratorType < Message>

Public Method Index:
	Exception ()

template<typename TEnum , typename... TArgs>
	Exception (const NCString &file, int line, const NCString &func, TEnum type, TArgs &&... args)

	Exception (Exception &&src) noexcept

	Exception (Exception &)=delete

template<typename TIntegral >
	Exception (TIntegral initialChunkSize, int chunkGrowthInPercent=100)

	~Exception ()=default

template<typename TEnum , typename... TArgs>
Exception &	Add (const NCString &file, int line, const NCString &func, TEnum type, TArgs &&... args)

ALIB_API Message &	Back () const

ForwardIterator	begin ()

ConstForwardIterator	begin () const

ForwardIterator	end ()

ConstForwardIterator	end () const

AString	Format () const

ALIB_API AString &	Format (AString &target) const

ALIB_API strings::TAString< complementChar > &	Format (strings::TAString< complementChar > &target) const

Exception &	operator= (Exception &&)=delete

Exception	operator= (Exception &)=delete

ALIB_API int	Size () const

ALIB_API const Enum &	Type () const

Type Definition Details:

◆ ConstForwardIterator

using ConstForwardIterator = IteratorType <const Message>

The constant iterator exposed by this container.

Definition at line 457 of file exception.hpp.

◆ ForwardIterator

using ForwardIterator = IteratorType < Message>

The mutable iterator exposed by this container.

Definition at line 460 of file exception.hpp.

Constructor(s) / Destructor Details::

◆ Exception() [1/5]

Exception ( Exception & )

delete

Deleted copy constructor. Exceptions must be caught only as references.

◆ Exception() [2/5]

Exception ( Exception && src )

inlinenoexcept

Move constructor moves the entries and deletes them in source object.

Parameters

src	The object to move.

Definition at line 142 of file exception.hpp.

◆ Exception() [3/5]

Exception ( )

inline

Default constructor.

Note: If this constructor is used, one or more invocations of Add have be performed prior to throwing the exception. Otherwise, the exception does not contain any information. From this perspective, it could be said that this constructor is provided for the cases where either more than one entry is added in a loop or different types of entries are added in a later if statement after construction. Otherwise, this constructor should be avoided.

Definition at line 167 of file exception.hpp.

◆ Exception() [4/5]

template<typename TIntegral >

Exception	(	TIntegral	initialChunkSize,
		int	chunkGrowthInPercent = 100 )

inline

Constructor that allows to provide the size of the allocated chunk of memory in bytes. With other constructors, this size is fixed to 1024. A higher size may avoid a second allocation (which is not problematic in usual cases).

Note: The use of this constructor is advisable only in seldom cases. The same notes as given with the documentation of the default constructor apply.

Parameters

initialChunkSize	The initial allocation size of the internal MonoAllocator .
chunkGrowthInPercent	Optional growth faktor in percent (*100), applied to each allocation of a next chunk size. Values provided should be greater than 100.

Defaults to 100, which does not increase subsequent chunk allocations.

Definition at line 188 of file exception.hpp.

◆ Exception() [5/5]

template<typename TEnum , typename... TArgs>

Exception	(	const NCString &	file,
		int	line,
		const NCString &	func,
		TEnum	type,
		TArgs &&...	args )

inline

Constructs an exception and invokes Add to create the initial message entry.

In case that the enumeration type of given parameter type is equipped with ALib Enum Records according to record type ERException , the first argument added to the message entry is collected from the corresponding enum record. For more information consult the corresponding section of the Programmer's Manual.

Template Parameters

TEnum	Template type of the enumeration element.
TArgs	The variadic template argument types.

Parameters

file	File name of the place of entry creation.
line	Line number of the place of entry creation.
func	Function/method name of the place of entry creation.
type	An enum element denoting the message type.
args	The message arguments.

Definition at line 217 of file exception.hpp.

Here is the call graph for this function:

◆ ~Exception()

~Exception ( )

default

Destructor

Method Details:

◆ Add()

template<typename TEnum , typename... TArgs>

Exception & Add	(	const NCString &	file,
		int	line,
		const NCString &	func,
		TEnum	type,
		TArgs &&...	args )

inline

Adds a new message to this exception. The parameters of this method are exactly those that are expected by the constructor of class Message .

The message object itself is created in the monotonic allocator of this exception received by inherited method SelfContained::Allocator .

After the insertion, method CloneArguments is invoked, which creates "safe" copies of the arguments to guarantee their survival during this exception's lifespan.

If the enumeration type TEnum (which is deduced from parameter type ) is equipped with ALib Enum Records of type ERException , an additional message argument is prepended to the message This argument is of string type and is taken from field DescriptionOrItsResourceName of the associated enum record. As described in chapter alib_basecamp_message_exceptions_args of the Programmer's Manual, it is proposed that this argument of string type, is a formatter-string that is used to format the arguments of an exception into a human readable message.

If furthermore, TMP struct T_Resourced is specialized for enumeration type TEnum , then the value of DescriptionOrItsResourceName is not directly prepended, but interpreted as a resource name. In this case the resourced description is prepended instead.

For more information consult chapter 2.2.6 Resourced Exceptions of the Programmer's Manual.

Template Parameters

TEnum	The enumeration type used to define the message type.
TArgs	The variadic template argument types.

Parameters

file	File name of the place of entry creation.
line	Line number of the place of entry creation.
func	Function/method name of the place of entry creation.
type	An enum element denoting the message type.
args	The message arguments.

Returns: Return *this to allow concatenated operations or use with throw statement.

Definition at line 304 of file exception.hpp.

Here is the call graph for this function:

◆ allocMessageLink()

Message * allocMessageLink ( )

protected

Searches the last linked message and attaches a new, monotonically allocated list node.

Returns: A pointer to the message in the allocated link node.

Definition at line 58 of file exception.cpp.

Here is the call graph for this function:

◆ Back()

Message & Back ( ) const

Returns the last message in the list of stored messages.

Returns: The most recently added message.

Definition at line 130 of file exception.cpp.

Here is the call graph for this function:

◆ begin() [1/2]

ForwardIterator begin ( )

inline

Returns an iterator pointing to the first message entry.

Returns: A forward iterator to the first message entry.

Definition at line 467 of file exception.hpp.

Here is the call graph for this function:

◆ begin() [2/2]

ConstForwardIterator begin ( ) const

inline

Returns an iterator pointing to the first message entry.

Returns: A forward iterator to the first message entry.

Definition at line 485 of file exception.hpp.

Here is the call graph for this function:

◆ end() [1/2]

ForwardIterator end ( )

inline

Returns an iterator representing the end of the message entries.

Returns: The end of this exception's message entries.

Definition at line 476 of file exception.hpp.

◆ end() [2/2]

ConstForwardIterator end ( ) const

inline

Returns an iterator representing the end of the message entries.

Returns: The end of this exception's message entries.

Definition at line 494 of file exception.hpp.

◆ finalizeMessage()

void finalizeMessage	(	Message *	message,
		bool	hasRecord,
		ResourcePool *	pool,
		const NString &	category )

protected

Non-inlined portion of method Add. Clones arguments and prepends description argument, in case the enum element of the message has an enum record attached. If furthermore, the enum element's record was resourced, then the record's description value is interpreted as a resource string's name, which is prepended instead.

Parameters

message	The message to finalize.
hasRecord	Indicates if a record is assigned.
pool	If records are resourced, this is the resource pool to use.
category	If records are resourced, this is the category to use.

Definition at line 72 of file exception.cpp.

Here is the call graph for this function:

◆ Format() [1/3]

AString Format ( ) const

inline

Inline shortcut to Format(AString&) that creates, uses and returns an AString value for the exception's description.

Returns: The formatted description of the Exception.

Definition at line 351 of file exception.hpp.

Here is the call graph for this function:

◆ Format() [2/3]

AString & Format ( AString & target ) const

Uses class Paragraphs to write all entries of this exception into the given narrow target string. Entries are expected to have a format string set as their description meta information that corresponds (in respect to the placeholders within the string) to the arguments found in the entry.

Parameters

target The target string to format the entry description to.

Returns: Returns given AString target for convenience.

Definition at line 165 of file exception.cpp.

Here is the call graph for this function:

◆ Format() [3/3]

ALIB_API strings::TAString< complementChar > & Format ( strings::TAString< complementChar > & target ) const

inline

Same as Format(AString&) , but writing to a string of complement character width.

Parameters

target The target string to format the entry description to.

Returns: Returns given AString target for convenience.

Definition at line 339 of file exception.hpp.

Here is the call graph for this function:

◆ operator=() [1/2]

Exception & operator= ( Exception && )

delete

Deleted move assignment operator.

Returns: Nothing (deleted).

◆ operator=() [2/2]

Exception operator= ( Exception & )

delete

Deleted copy assignment operator.

Returns: Nothing (deleted).

◆ Size()

int Size ( ) const

Returns the number of message entries.

Returns: The number of messages added to this exception.

Definition at line 139 of file exception.cpp.

Here is the call graph for this function:

◆ Type()

const Enum & Type ( ) const

Returns field Message::Type of the last message in the list of messages that has a positive underlying enum element value.

The rationale here is explained in the Programmer's Manual. In short, positive and negative enum element values are used to separated "informational entries" (with a negative value) from message entries that change the type of the exception (positive value). Usually, only the latter ones are processed by exception handlers.

Returns: The most high level exception code.

Definition at line 152 of file exception.cpp.

Here is the call graph for this function:

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

Description:

Inner Type Index:

Public Type Index:

Public Method Index:

Type Definition Details:

◆ ConstForwardIterator

◆ ForwardIterator

Constructor(s) / Destructor Details::

◆ Exception() [1/5]

◆ Exception() [2/5]

◆ Exception() [3/5]

◆ Exception() [4/5]

◆ Exception() [5/5]

◆ ~Exception()

Method Details:

◆ Add()

◆ allocMessageLink()

◆ Back()

◆ begin() [1/2]

◆ begin() [2/2]

◆ end() [1/2]

◆ end() [2/2]

◆ finalizeMessage()

◆ Format() [1/3]

◆ Format() [2/3]

◆ Format() [3/3]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ Size()

◆ Type()