Isis Developer Reference
Isis::IException Class Reference

Isis exception class. More...

#include <IException.h>

Inheritance diagram for Isis::IException:
Inheritance graph
Collaboration diagram for Isis::IException:
Collaboration graph

Public Types

enum  ErrorType { Unknown = 1 , User , Programmer , Io }
 Contains a set of exception error types. More...
 

Public Member Functions

 IException ()
 The default constructor creates an IException instance with no message, previous exceptions, or file info.
 
 IException (ErrorType type, const char *message, const char *fileName, int lineNumber)
 This version of the constructor creates an IException instance with the given error type, message, and file info.
 
 IException (ErrorType type, const std::string &message, const char *fileName, int lineNumber)
 This version of the constructor creates an IException instance with the given error type, message, and file info.
 
 IException (ErrorType type, const QString &message, const char *fileName, int lineNumber)
 This version of the constructor creates an IException instance with the given error type, message, and file info.
 
 IException (const IException &caughtException, ErrorType newExceptionType, const char *message, const char *fileName, int lineNumber)
 This version of the constructor creates an IException instance with the given error type, message, file info.
 
 IException (const IException &caughtException, ErrorType newExceptionType, const std::string &message, const char *fileName, int lineNumber)
 This version of the constructor creates an IException instance with the given error type, message, file info.
 
 IException (const IException &caughtException, ErrorType newExceptionType, const QString &message, const char *fileName, int lineNumber)
 This version of the constructor creates an IException instance with the given error type, message, file info.
 
 IException (const IException &other)
 The copy constructor creates a copy of the given exception.
 
 ~IException () throw ()
 The destructor frees memory allocated for the message, filename, and list of previous exceptions.
 
const char * what () const throw ()
 Returns a string representation of this exception in its current state.
 
void append (const IException &exceptionSource)
 Appends the given exception (and its list of previous exceptions) to this exception's causational exception list.
 
ErrorType errorType () const
 Returns the source of the error for this exception.
 
void print () const
 Prints a string representation of this exception to stderr.
 
void print (bool printFileInfo) const
 Prints a string representation of this exception to stderr, including file info if specified.
 
Pvl toPvl () const
 Returns a PVL object representing the contents of this exception.
 
QString toString () const
 Returns a string representation of this exception.
 
QString toString (bool printFileInfo) const
 Returns a string representation of this exception, including file info if specified.
 
void swap (IException &other)
 Swaps the values of this instance's member data with other.
 
IExceptionoperator= (const IException &rhs)
 Assign the values of rhs to this instance.
 

Static Public Member Functions

static QString errorTypeToString (ErrorType t)
 Returns the source of the error in string format for the given ErrorType.
 

Detailed Description

Isis exception class.

This class represents a general Isis exception. It contains an enumeration for what type of error the exception represents, and can optionally track what exceptions caused the current exception. This class also provides access to string and PVL representations of the exception.

Instances of this class should be thrown by value and caught be reference. Please see the constructor documentation for code examples on how to create and throw exceptions.

All methods in this class are re-entrant.

Author
????-??-?? Jeff Anderson

Member Enumeration Documentation

◆ ErrorType

Contains a set of exception error types.

These types indicate the source of the error. For example, if the error type is User, this indicates that the exception was thrown due to something the user did wrong, such as provide a cube with no SPICE data to an application that needed a spiceinit'd cube as input.

Enumerator
Unknown 

A type of error that cannot be classified as any of the other error types.

This should be the most common error type.

If in doubt, always use this error type.

User 

A type of error that could only have occurred due to a mistake on the user's part (e.g.

bad input to the application). You must be able to guarantee that the user provided the input in the context that is throwing the error.

Programmer 

This error is for when a programmer made an API call that was illegal.

This includes: Making an API call with illegal input data that could and should have been checked before the call was made. For example, an out of array bounds exception is a programmer exception because the caller should have checked the size of the array.

Making an API call that requires a certain class state. For example, you need to call open before read.

These categories have a lot of overlap, but they are what you are looking for. A programmer exception is not appropriate if the caller has no way to validate their inputs to a method ahead of time, or if the caller is not expected to validate their inputs ahead of time.

Io 

A type of error that occurred when performing an actual I/O operation.

For example, fread/fwrite calls. This also includes files not existing, inter-processes socket communications, and network communications. This does not include a file not having the expected values inside of it (for example, reading a corrupted PVL).

Constructor & Destructor Documentation

◆ IException() [1/8]

Isis::IException::IException ( )

The default constructor creates an IException instance with no message, previous exceptions, or file info.

The exception error type is Unknown.

This default constructor exists so that IException instances can be stored in Qt containers such as lists. This is also used for cancelling a program run.

throw IException();
IException()
The default constructor creates an IException instance with no message, previous exceptions,...
Definition IException.cpp:38

References Unknown.

◆ IException() [2/8]

Isis::IException::IException ( ErrorType type,
const char * message,
const char * fileName,
int lineNumber )

This version of the constructor creates an IException instance with the given error type, message, and file info.

The IException instance will not have any previous exceptions associated with it initially (i.e. no exception caused this one to be thrown).

"While doing an important process, we could not do ... "
"because the data [" ... "] is invalid",
#define _FILEINFO_
Macro for the filename and line number.
Definition IException.h:24
@ Unknown
A type of error that cannot be classified as any of the other error types.
Definition IException.h:118
Parameters
typethe source of the error that this exception represents
messagethe string message containing details about the error, which may be displayed to the user
fileNamethe filename of the file that this exception was thrown in
lineNumberthe line in the source code file that threw this exception

◆ IException() [3/8]

Isis::IException::IException ( ErrorType type,
const std::string & message,
const char * fileName,
int lineNumber )

This version of the constructor creates an IException instance with the given error type, message, and file info.

The IException instance will not have any previous exceptions associated with it initially (i.e. no exception caused this one to be thrown). The QString version of this constructor is preferred over this one.

std::string message = "While doing an important process, we could not do .. "
"because the data [" ... "] is invalid";
Parameters
typethe source of the error that this exception represents
messagethe string message containing details about the error, which may be displayed to the user
fileNamethe filename of the file that this exception was thrown in
lineNumberthe line in the source code file that threw this exception

◆ IException() [4/8]

Isis::IException::IException ( ErrorType type,
const QString & message,
const char * fileName,
int lineNumber )

This version of the constructor creates an IException instance with the given error type, message, and file info.

The IException instance will not have any previous exceptions associated with it initially (i.e. no exception caused this one to be thrown).

tr("While doing an important process, we could not do ... "
"because the data [%1] is invalid").arg(...),
Parameters
typethe source of the error that this exception represents
messagethe string message containing details about the error, which may be displayed to the user
fileNamethe filename of the file that this exception was thrown in
lineNumberthe line in the source code file that threw this exception

◆ IException() [5/8]

Isis::IException::IException ( const IException & caughtException,
ErrorType type,
const char * message,
const char * fileName,
int lineNumber )

This version of the constructor creates an IException instance with the given error type, message, file info.

The IException instance will append the given exception to its list of previous exceptions (as well as any previous exceptions associated with the caught exception). Use this constructor when you want to rethrow a new exception after catching an exception and preserve the previous message(s).

try {
...
}
catch (IException &e) {
throw IException(e,
"While doing an important process, we could not do "
"... ",
}
Isis exception class.
Definition IException.h:91
Parameters
caughtExceptionthe previous exception that caused this exception to be thrown
typethe source of the error that this exception represents
messagethe string message containing details about the error, which may be displayed to the user
fileNamethe filename of the file that this exception was thrown in
lineNumberthe line in the source code file that threw this exception

References append().

◆ IException() [6/8]

Isis::IException::IException ( const IException & caughtException,
ErrorType type,
const std::string & message,
const char * fileName,
int lineNumber )

This version of the constructor creates an IException instance with the given error type, message, file info.

The IException instance will append the given exception to its list of previous exceptions (as well as any previous exceptions associated with the caught exception). Use this constructor when you want to rethrow a new exception after catching an exception and preserve the previous message(s). The QString version of this constructor is preferred over this one.

try {
...
}
catch (IException &e) {
string message = "While doing an important process, we could not do "
"... ";
}
Parameters
caughtExceptionthe previous exception that caused this exception to be thrown
typethe source of the error that this exception represents
messagethe string message containing details about the error, which may be displayed to the user
fileNamethe filename of the file that this exception was thrown in
lineNumberthe line in the source code file that threw this exception

References append().

◆ IException() [7/8]

Isis::IException::IException ( const IException & caughtException,
ErrorType type,
const QString & message,
const char * fileName,
int lineNumber )

This version of the constructor creates an IException instance with the given error type, message, file info.

The IException instance will append the given exception to its list of previous exceptions (as well as any previous exceptions associated with the caught exception). Use this constructor when you want to rethrow a new exception after catching an exception and preserve the previous message(s).

try {
...
}
catch (IException &e) {
QString message = "While doing an important process, we could not do "
"... ";
}
Parameters
caughtExceptionthe previous exception that caused this exception to be thrown
typethe source of the error that this exception represents
messagethe string message containing details about the error, which may be displayed to the user
fileNamethe filename of the file that this exception was thrown in
lineNumberthe line in the source code file that threw this exception

References append().

◆ IException() [8/8]

Isis::IException::IException ( const IException & other)

The copy constructor creates a copy of the given exception.

Parameters
otherthe exception to copy from

◆ ~IException()

Isis::IException::~IException ( )
throw ( )

The destructor frees memory allocated for the message, filename, and list of previous exceptions.

References Unknown.

Member Function Documentation

◆ append()

void Isis::IException::append ( const IException & exceptionSource)

Appends the given exception (and its list of previous exceptions) to this exception's causational exception list.

The passed in exception is the cause of this exception. Exceptions should be appended in the original order that they were thrown - earlier first.

This method causes the results of what() to be rebuilt, invalidating any previous results.

try {
...
}
catch (IException &error1) {
try {
...
}
catch (IException &error2) {
finalError.append(error1);
finalError.append(error2);
throw finalError;
}
}
Parameters
exceptionSourcethe exception that should be added to the list of previous exceptions

Referenced by Isis::ProjectionFactory::CreateForCube(), IException(), IException(), IException(), Isis::ProjectionFactory::RingsCreateForCube(), Isis::ProjectionFactory::RingsCreateForCube(), and Isis::ProgramLauncher::RunIsisProgram().

◆ errorType()

IException::ErrorType Isis::IException::errorType ( ) const

Returns the source of the error for this exception.

Returns
the source of the error (i.e. ErrorType)

◆ errorTypeToString()

QString Isis::IException::errorTypeToString ( ErrorType type)
static

Returns the source of the error in string format for the given ErrorType.

Parameters
typethe ErrorType enum to convert to a string
Returns
a string representation of the error type. For example, "USER ERROR" if the error type is User

References Io, Programmer, Unknown, and User.

Referenced by toPvl(), and toString().

◆ operator=()

IException & Isis::IException::operator= ( const IException & rhs)

Assign the values of rhs to this instance.

This is a deep copy and is exception-safe.

Parameters
rhsthe IException on the right-hand side of the equals operator
Returns
*this

References swap().

◆ print() [1/2]

void Isis::IException::print ( ) const

Prints a string representation of this exception to stderr.

File info (i.e. filename and line number) are only printed if the user has that option enabled in their preferences file. The printed exception will be either PVL-formatted or formatted as plain sentences according to the user's preferences file.

This should be the preferred method call in unit tests when testing exceptions thrown by your class.

References toString().

◆ print() [2/2]

void Isis::IException::print ( bool printFileInfo) const

Prints a string representation of this exception to stderr, including file info if specified.

The printed exception will be either PVL-formatted or formatted as plain sentences according to the user's preferences file.

Parameters
printFileInfowhether or not to include file info in the printed version of this exception. This ignores the option set in the user's preferences file regarding file info.

References toString().

◆ swap()

void Isis::IException::swap ( IException & other)

Swaps the values of this instance's member data with other.

This method is exception-safe.

Parameters
otherthe exception to swap member data with

Referenced by operator=().

◆ toPvl()

Pvl Isis::IException::toPvl ( ) const

Returns a PVL object representing the contents of this exception.

File info is included unless there is no filename or line number associated with an exception, regardless of the user's preferences file.

Returns
a PVL object representing this exception

References Isis::PvlObject::addGroup(), Isis::Pvl::append(), errorTypeToString(), Isis::Application::Name(), Isis::toString(), and Unknown.

Referenced by toString().

◆ toString() [1/2]

QString Isis::IException::toString ( ) const

Returns a string representation of this exception.

File info (i.e. filename and line number) are only included if the user has that option enabled in their preferences file. The string representation of the exception will be either PVL-formatted or formatted as plain sentences according to the user's preferences file.

Returns
a string representation of this exception

References Isis::Preference::Preferences(), and toString().

Referenced by print(), print(), and toString().

◆ toString() [2/2]

QString Isis::IException::toString ( bool includeFileInfo) const

Returns a string representation of this exception, including file info if specified.

The string representation of the exception will be either PVL-formatted or formatted as plain sentences according to the user's preferences file.

Parameters
includeFileInfowhether or not to include file info in the string representation of this exception. This ignores the option set in the user's preferences file regarding file info.
Returns
a string representation of this exception

References errorTypeToString(), Isis::PvlObject::groups(), Isis::Preference::Preferences(), toPvl(), Isis::toString(), and Unknown.

◆ what()

const char * Isis::IException::what ( ) const
throw ( )

Returns a string representation of this exception in its current state.

The results of this method are guaranteed to be valid until the instance is modified.

Returns
a C string representation of this exception

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