ApoCharmmError Class Reference

Represents a categorized native error with source metadata. More...

#include <ApoCharmmError.h>

Inheritance diagram for ApoCharmmError:

Public Member Functions
	ApoCharmmError (const ApoCharmmErrorCode code, const std::string_view message, const std::string_view sourceFile, const std::string_view sourceFunction, const int sourceLine)
	Constructs a categorized exception and renders its diagnostic.
ApoCharmmErrorCode	getCode (void) const noexcept
	Returns the retained failure category.
std::string_view	getMessage (void) const noexcept
	Returns the retained human-readable message.
std::string_view	getSourceFile (void) const noexcept
	Returns the normalized source-file spelling.
std::string_view	getSourceFunction (void) const noexcept
	Returns the retained source-function spelling.
int	getSourceLine (void) const noexcept
	Returns the retained source-line value.

Detailed Description

Represents a categorized native error with source metadata.

The exception owns copies of its human message, normalized source-file spelling, source function, and source line. The inherited what() diagnostic begins with the apoCHARMM ASCII banner and then reports the category, message, source location, and function. The exception remains catchable as std::runtime_error and std::exception.

Views returned by the string accessors borrow storage from this object. Copying the exception creates an independent logical copy of that metadata. Moving transfers the metadata, and may invalidate views into the moved-from exception.

Warning

Do not allow this C++ exception to cross a C ABI boundary. Use the apoCHARMM C ABI guards, which translate it to an apo_status and a thread-local diagnostic.

See also

apocharmm_error

Constructor & Destructor Documentation

ApoCharmmError()

ApoCharmmError::ApoCharmmError	(	const ApoCharmmErrorCode	code,
		const std::string_view	message,
		const std::string_view	sourceFile,
		const std::string_view	sourceFunction,
		const int	sourceLine
	)

Constructs a categorized exception and renders its diagnostic.

All character data is copied before the constructor returns. A source path beneath the configured apoCHARMM source root is stored relative to that root. Any other path containing / or \ is reduced to its final path component.

Parameters

[in]	code	Failure category to retain.
[in]	message	Human-readable diagnostic. The text may be empty or multiline and is copied without normalization.
[in]	sourceFile	Source-file spelling to normalize and copy.
[in]	sourceFunction	Source-function spelling to copy unchanged.
[in]	sourceLine	Source-line value to store unchanged.

Exceptions

std::bad_alloc	If owned diagnostic storage cannot be allocated.
std::length_error	If an input or rendered diagnostic exceeds an implementation-defined string limit.

Note

Prefer APOCHARMM_THROW or APOCHARMM_REQUIRE so the source metadata is captured at the failure site.

Member Function Documentation

getCode()

ApoCharmmErrorCode ApoCharmmError::getCode ( void  ) const

noexcept

Returns the retained failure category.

Returns

The category supplied at construction.

getMessage()

std::string_view ApoCharmmError::getMessage ( void  ) const

noexcept

Returns the retained human-readable message.

Returns

A borrowed read-only view into storage owned by this exception. The view remains valid until the exception is destroyed or assigned a new value. Moving from the exception may also invalidate the view.

getSourceFile()

std::string_view ApoCharmmError::getSourceFile ( void  ) const

noexcept

Returns the normalized source-file spelling.

Returns

A borrowed read-only view into storage owned by this exception. The view remains valid until the exception is destroyed or assigned a new value. Moving from the exception may also invalidate the view.

getSourceFunction()

std::string_view ApoCharmmError::getSourceFunction ( void  ) const

noexcept

Returns the retained source-function spelling.

Returns

A borrowed read-only view into storage owned by this exception. The view remains valid until the exception is destroyed or assigned a new value. Moving from the exception may also invalidate the view.

getSourceLine()

int ApoCharmmError::getSourceLine ( void  ) const

noexcept

Returns the retained source-line value.

Returns

The source-line value supplied at construction. The APOCHARMM_THROW macro supplies the compiler-provided __LINE__ value.