Exceptions

pni::exception_record

class exception_record

exception record

Contains the basic information where an exception has been thrown. This information consists of the source file, the line in the file, and the signature of the function where the error occurred. Using the BOOST_CURRENT_FUNCTION macro defined in boost/current_function.hpp such a record can easily be constructed with

exception_record r(__FILE__,__LINE__,BOOST_CURRENT_FUNCTION);

Public Functions

exception_record() = delete

no default constructor

inline exception_record(const string &file, size_t line, const string &func)

constructor

inline const string &file() const

get file name

inline size_t line() const

get file line number

inline const string &function() const

get function

PNINEXUS_EXPORT std::ostream &pni::operator<<(std::ostream &o, const exception_record &rec)

error record output operator

pni::exception

class exception : public std::exception

Exceptions base class.

This is the base class for all exceptions used in this library.

Subclassed by pni::cli_argument_error, pni::cli_error, pni::cli_help_request, pni::cli_option_error, pni::file_error, pni::filter_not_available, pni::index_error, pni::invalid_object_error, pni::io_error, pni::iterator_error, pni::key_error, pni::link_error, pni::memory_allocation_error, pni::memory_not_allocated_error, pni::not_implemented_error, pni::object_error, pni::parser_error, pni::range_error, pni::shape_mismatch_error, pni::size_mismatch_error, pni::tiff::tiff_read_error, pni::type_error, pni::value_error

Public Types

typedef std::list<exception_record>::const_iterator const_iterator

const iterator over the error record

Public Functions

exception()

default constructor

exception(const string &n)

constructor

Parameters:

n – name of the exception

exception(const string &n, const exception_record &rec)

constructor

Parameters:

• n – name of the exception

• rec – Exception record of the initial location where the error occured

exception(const string &n, const exception_record &rec, const string &d)

constructor

Parameters:

• n – name of the exception

• rec – exception record describing the location of the first occurrence of the error

• d – description of the exception

inline virtual ~exception()

virtual destructor

inline void name(const std::string &name)

set the exception name

Parameters:

name – exception name

inline const string &name() const

get the exceptions name

Returns:

reference to the string object holding the name

inline void append(const exception_record &n)

add a new issuer

Use this method to add a new issuer in the case that the exception is re-thrown by an other function or class method.

...
catch(exception &error)
{
    error.append(PNINEXUS_EXCEPTION_RECORD);
    throw error;
}

With this a particular exception can be traced througout the entire code.

Parameters:

n – exception_record to append

inline void description(const std::string &desc)

set exception desccription

Parameters:

desc – description of the exception

inline const string &description() const

get the exceptions description

Returns:

reference to the string object with the exceptions description

inline size_t size() const

get number of record

Returns the number of records associated with this exception.

Returns:

number of records

inline const_iterator begin() const

get iterator to first error record

Return get a const iterator to the first error record in the class.

Returns:

iterator to first exception record

inline const_iterator end() const

get iterator to the last error record

Return a const iterator pointing to the last+1 element in the exception record list.

Returns:

iterator to last+1 exception record

Friends

PNINEXUS_EXPORT friend std::ostream &operator<<(std::ostream&, const exception&)

output operator for exceptions

Exception classes

These classes have the same interface as pni::exception but denote different failure situations.

class memory_allocation_error : public pni::exception

memory allocation error

This exception is typically raised when allocation of memory on the heap fails. In other words when a call to new leads to a nullptr.

class memory_not_allocated_error : public pni::exception

memory not allocated error

This exception is usually thrown if one tries to access not allocated memory.

class shape_mismatch_error : public pni::exception

Shape mismatch error.

Raised in cases where the Shape objects of two objects are not equal.

class size_mismatch_error : public pni::exception

Size mismatch error.

This exception will be raised in cases where buffer sizes do not meet the requirements.

class index_error : public pni::exception

index error

Raised if the index passed to a [] operator exceeds the size of the container it belongs to.

class key_error : public pni::exception

key error

Raised in cases where a problem with the key of a hash map occurs.

class file_error : public pni::exception

file IO fails

Raised typically in cases of problems with files.

class type_error : public pni::exception

data type error

This exception is raised in cases of errors concerning data types.

class value_error : public pni::exception

data value error

This exception is raised in cases where a particular variable takes an inappropriate value.

class range_error : public pni::exception

data range error

This exception is raised in cases where data values exceed the range spanned by their data type.

class not_implemented_error : public pni::exception

not implemented exception

This exception can be used to mark methods of abstract or base classes as not implemented. Such an approach can be quite useful for debugging and development.

class iterator_error : public pni::exception

iterator error

Exception thrown in case of iterator errors.

class cli_argument_error : public pni::exception

command line argument error

Thrown in cases where a command line argument (do not confuse this with an option has an inapropriate value or is missing).

class cli_option_error : public pni::exception

command line option error

Exception thrown in cases where a command line option is missing or has an inapropriate value.

class cli_error : public pni::exception

general CLI error

Thrown in case of a general CLI error not related to arguments or options.

class filter_not_available : public pni::exception

filter not available error

Raised in cases where the filter is not available.

Macros

PNINEXUS_EXCEPTION_RECORD

macro creating an instance of ExceptionRecord

PNINEXUS_EXCEPTION_FORWARD(ExceptionT)

forward an exception

This macro can be used to forward an exception caught from another function. It appends the exception_record of the current function to the existing exception and throws the exception again. Consider the following examples

try { value = buffer.at(index); }
PNINEXUS_EXCEPTION_FORWARD(IndexError)
PNINEXUS_EXCEPTION_FORWARD(MemoryNotAllocatedError)

Please note that the MUST NOT BE a semicolon at the end of this macro.

Utility functions

template<typename ContainerAT, typename ContainerBT>
bool pni::check_equal_size(const ContainerAT &a, const ContainerBT &b)

check if two container have equal size

This helper function checks if two container instances have equal size and returns true if this is the case. Otherwise false will be returned. Both container types have to provide a size() method returning the number of elements the container can hold.

Template Parameters:

• ContainerAT – first container type

• ContainerBT – second container type

Parameters:

• a – reference to an instance of ContainerAT

• b – reference to an instance of ContainerBT

Returns:

true if a and b have same size, false otherwise

template<typename ContainerAT, typename ContainerBT>
void pni::check_equal_size(const ContainerAT &a, const ContainerBT &b, const exception_record &i)

check if two objects have different size

This utilty function can be used to check for the equality of the size of two objects. It is typically used to compare the size of a shape and a buffer or any other container object. If the sizes do not match an exception is thrown.

Throws:

size_mismatch_error – if sizes do not match

Template Parameters:

• ContainerAT – first container type

• ContainerBT – second container type

Parameters:

• a – instance of container type ContainerAT

• b – instance of container type ContainerBT

• i – exception_record for the location where to perform the check performed