API  4.4
For C++ developers
List of all members | Public Member Functions | Protected Member Functions
OpenSim::Exception Class Reference

A class for basic exception functionality. More...

+ Inheritance diagram for OpenSim::Exception:

Public Member Functions

 Exception (const std::string &aMsg="", const std::string &aFile="", int aLine=-1)
 This constructor is for backward compatibility. More...
 
 Exception (const std::string &file, size_t line, const std::string &func)
 Call this constructor from derived classes to add file, line and function information to the error message. More...
 
 Exception (const std::string &file, size_t line, const std::string &func, const std::string &msg)
 Use this when you want to throw an Exception (with OPENSIM_THROW or OPENSIM_THROW_IF) and also provide a message. More...
 
 Exception (const std::string &file, size_t line, const std::string &func, const Object &obj)
 The message created by this constructor will contain the class name and instance name of the provided Object. More...
 
 Exception (const std::string &file, size_t line, const std::string &func, const Object &obj, const std::string &msg)
 The message created by this constructor will contain the class name and instance name of the provided Object, and also accepts a message. More...
 
template<typename... Args>
 Exception (const std::string &file, size_t line, const std::string &func, spdlog::string_view_t fmt, const Args &... args)
 Use this when you want to throw an Exception (with OPENSIM_THROW or OPENSIM_THROW_IF) and also provide a message that is formatted using fmt::format() syntax. More...
 
template<typename... Args>
 Exception (const std::string &file, size_t line, const std::string &func, const Object &obj, spdlog::string_view_t fmt, const Args &... args)
 The message created by this constructor will contain the class name and instance name of the provided Object, and also accepts a message formatted using fmt::format() syntax. More...
 
virtual ~Exception () throw ()
 
void setMessage (const std::string &aMsg)
 
const char * getMessage () const
 
virtual void print (std::ostream &aOut) const
 
const char * what () const noexcept override
 

Protected Member Functions

void addMessage (const std::string &msg)
 Add to the error message that will be returned for the exception. More...
 

Related Functions

(Note that these are not member functions.)

Macros to throw OpenSim exceptions

The purpose of these macros is to aid with consistent message formatting, include file/line/function information in all messages, and to make it easier for developers to produce good messages.

#define OPENSIM_THROW(EXCEPTION, ...)   throw EXCEPTION{__FILE__, __LINE__, __func__, __VA_ARGS__};
 
#define OPENSIM_THROW_IF(CONDITION, EXCEPTION, ...)
 This macro checks the given condition and throws the given exception if the condition is true. More...
 

Detailed Description

A class for basic exception functionality.

To create exception classes in OpenSim, use the following guidelines. If the intention is to derive from an exception named, for example, BaseException that is part of OpenSim, use the following blueprint:

class MyNewException : public BaseException {
public:
MyNewException(const std::string& file,
size_t line,
const std::string& func,
<more parameters as appropriate>) :
BaseException(file, line, func) {
std::string message = <create the desired message>;
addMessage(message);
}
};

Exception class manages the concatenation of error messages from all the derived classes. When creating new exceptions, remember to call addMessage() as shown above if the exception class does have any error message.

Examples:
exampleCustomImplicitAuxiliaryDynamics.cpp.

Constructor & Destructor Documentation

◆ Exception() [1/7]

OpenSim::Exception::Exception ( const std::string &  aMsg = "",
const std::string &  aFile = "",
int  aLine = -1 
)

This constructor is for backward compatibility.

Use the constructor taking file, line, func.

Referenced by OpenSim::AbstractInput::connect(), OpenSim::Component::constructInput(), OpenSim::Component::constructSocket(), OpenSim::AbstractSocket::finalizeConnection(), OpenSim::Component::findComponent(), OpenSim::Component::getConnectee(), OpenSim::Component::getInputValue(), OpenSim::Component::getMemberSubcomponent(), OpenSim::Model::getVisualizer(), OpenSim::Component::updMemberSubcomponent(), and OpenSim::Model::updVisualizer().

◆ Exception() [2/7]

OpenSim::Exception::Exception ( const std::string &  file,
size_t  line,
const std::string &  func 
)

Call this constructor from derived classes to add file, line and function information to the error message.

Use this when throwing Derived classes. Use OPENSIM_THROW_<> macros at throw sites.

◆ Exception() [3/7]

OpenSim::Exception::Exception ( const std::string &  file,
size_t  line,
const std::string &  func,
const std::string &  msg 
)

Use this when you want to throw an Exception (with OPENSIM_THROW or OPENSIM_THROW_IF) and also provide a message.

◆ Exception() [4/7]

OpenSim::Exception::Exception ( const std::string &  file,
size_t  line,
const std::string &  func,
const Object &  obj 
)

The message created by this constructor will contain the class name and instance name of the provided Object.

Use this when throwing derived classes. Use OPENSIM_THROW_<> macros at throw sites.

◆ Exception() [5/7]

OpenSim::Exception::Exception ( const std::string &  file,
size_t  line,
const std::string &  func,
const Object &  obj,
const std::string &  msg 
)

The message created by this constructor will contain the class name and instance name of the provided Object, and also accepts a message.

Use this when throwing Exception directly. Use OPENSIM_THROW_<> macros at throw sites.

◆ Exception() [6/7]

template<typename... Args>
OpenSim::Exception::Exception ( const std::string &  file,
size_t  line,
const std::string &  func,
spdlog::string_view_t  fmt,
const Args &...  args 
)
inline

Use this when you want to throw an Exception (with OPENSIM_THROW or OPENSIM_THROW_IF) and also provide a message that is formatted using fmt::format() syntax.

◆ Exception() [7/7]

template<typename... Args>
OpenSim::Exception::Exception ( const std::string &  file,
size_t  line,
const std::string &  func,
const Object &  obj,
spdlog::string_view_t  fmt,
const Args &...  args 
)
inline

The message created by this constructor will contain the class name and instance name of the provided Object, and also accepts a message formatted using fmt::format() syntax.

Use this when throwing an Exception directly. Use OPENSIM_THROW_FRMOBJ and OPENSIM_THROW_IF_FRMOBJ macros at throw sites.

◆ ~Exception()

virtual OpenSim::Exception::~Exception ( )
throw (
)
inlinevirtual

Member Function Documentation

◆ addMessage()

void OpenSim::Exception::addMessage ( const std::string &  msg)
protected

Add to the error message that will be returned for the exception.

Referenced by OpenSim::ComponentAlreadyPartOfOwnershipTree::ComponentAlreadyPartOfOwnershipTree(), OpenSim::ComponentHasNoName::ComponentHasNoName(), OpenSim::ComponentHasNoSystem::ComponentHasNoSystem(), OpenSim::ComponentIsAnOrphan::ComponentIsAnOrphan(), OpenSim::ComponentIsRootWithNoSubcomponents::ComponentIsRootWithNoSubcomponents(), OpenSim::ComponentNotFoundOnSpecifiedPath::ComponentNotFoundOnSpecifiedPath(), OpenSim::ConnecteeNotSpecified::ConnecteeNotSpecified(), OpenSim::DataAdapterAlreadyRegistered::DataAdapterAlreadyRegistered(), OpenSim::DataTypeMismatch::DataTypeMismatch(), OpenSim::EmptyFileName::EmptyFileName(), OpenSim::EmptyTable::EmptyTable(), OpenSim::FileDeletionThrowerException::FileDeletionThrowerException(), OpenSim::FileDoesNotExist::FileDoesNotExist(), OpenSim::FileExtensionNotFound::FileExtensionNotFound(), OpenSim::FileIsEmpty::FileIsEmpty(), OpenSim::IncorrectMetaDataLength::IncorrectMetaDataLength(), OpenSim::IncorrectNumColumnLabels::IncorrectNumColumnLabels(), OpenSim::IncorrectNumColumns::IncorrectNumColumns(), OpenSim::IncorrectNumMetaDataKeys::IncorrectNumMetaDataKeys(), OpenSim::IncorrectNumRows::IncorrectNumRows(), OpenSim::IncorrectNumTokens::IncorrectNumTokens(), OpenSim::IncorrectTableType::IncorrectTableType(), OpenSim::InputNotConnected::InputNotConnected(), OpenSim::InputNotFound::InputNotFound(), OpenSim::InvalidComponentName::InvalidComponentName(), OpenSim::InvalidPropertyValue::InvalidPropertyValue(), OpenSim::InvalidTimeRange::InvalidTimeRange(), OpenSim::JointFramesAreTheSame::JointFramesAreTheSame(), OpenSim::JointFramesHaveSameBaseFrame::JointFramesHaveSameBaseFrame(), OpenSim::JointHasNoCoordinates::JointHasNoCoordinates(), OpenSim::KeyExists::KeyExists(), OpenSim::KeyMissing::KeyMissing(), OpenSim::MetaDataLengthMismatch::MetaDataLengthMismatch(), OpenSim::MissingMetaData::MissingMetaData(), OpenSim::ModelHasNoSystem::ModelHasNoSystem(), OpenSim::MuscleCannotEquilibrate::MuscleCannotEquilibrate(), OpenSim::NoColumnLabels::NoColumnLabels(), OpenSim::NoRegisteredDataAdapter::NoRegisteredDataAdapter(), OpenSim::NoTableFound::NoTableFound(), OpenSim::OutputNotFound::OutputNotFound(), OpenSim::PhysicalOffsetFramesFormLoop::PhysicalOffsetFramesFormLoop(), OpenSim::RowLengthMismatch::RowLengthMismatch(), OpenSim::SocketNotFound::SocketNotFound(), OpenSim::STODataTypeNotSupported::STODataTypeNotSupported(), OpenSim::SubcomponentsWithDuplicateName::SubcomponentsWithDuplicateName(), OpenSim::TableMissingHeader::TableMissingHeader(), OpenSim::TableNotFoundException::TableNotFoundException(), OpenSim::TimeColumnNotIncreasing::TimeColumnNotIncreasing(), OpenSim::TimeOutOfRange::TimeOutOfRange(), OpenSim::TimestampGreaterThanEqualToNext::TimestampGreaterThanEqualToNext(), OpenSim::TimestampLessThanEqualToPrevious::TimestampLessThanEqualToPrevious(), OpenSim::UnexpectedColumnLabel::UnexpectedColumnLabel(), OpenSim::UnexpectedMetaDataKey::UnexpectedMetaDataKey(), and OpenSim::UnsupportedFileType::UnsupportedFileType().

◆ getMessage()

const char* OpenSim::Exception::getMessage ( ) const

◆ print()

virtual void OpenSim::Exception::print ( std::ostream &  aOut) const
virtual

◆ setMessage()

void OpenSim::Exception::setMessage ( const std::string &  aMsg)

◆ what()

const char* OpenSim::Exception::what ( ) const
overridenoexcept

Referenced by OpenSim::TableReporter_< InputT, ValueT >::implementReport().

Friends And Related Function Documentation

◆ OPENSIM_THROW

#define OPENSIM_THROW (   EXCEPTION,
  ... 
)    throw EXCEPTION{__FILE__, __LINE__, __func__, __VA_ARGS__};
related

Referenced by OpenSim::AbstractSocket::checkConnecteePathProperty(), OpenSim::Socket< T >::connect(), OpenSim::Input< T >::connect(), OpenSim::AbstractSocket::findAndConnect(), OpenSim::Component::getComponent(), OpenSim::Socket< T >::getConnectee(), OpenSim::AbstractSocket::getConnecteeAsObject(), OpenSim::AbstractDataTable::getTableMetaData(), OpenSim::Component::resetSubcomponentOrder(), and OpenSim::TimeSeriesTable_< SimTK::Vec3 >::TimeSeriesTable_().

◆ OPENSIM_THROW_IF

#define OPENSIM_THROW_IF (   CONDITION,
  EXCEPTION,
  ... 
)
related

This macro checks the given condition and throws the given exception if the condition is true.

Here's an example that throws an exception if some result is incorrect, and passes result and 5 to the constructor of the ResultIsIncorrect exception:

auto result = getSomeResult();
OPENSIM_THROW_IF(result != 5, ResultIsIncorrect, result, 5);

Referenced by OpenSim::AbstractDataTable::addTableMetaData(), OpenSim::AbstractSocket::appendConnecteePath(), OpenSim::TimeSeriesTable_< SimTK::Vec3 >::averageRow(), OpenSim::Component::constructInput(), OpenSim::Component::constructSocket(), OpenSim::Socket< T >::finalizeConnection(), OpenSim::Input< T >::finalizeConnection(), OpenSim::Socket< T >::findAndConnect(), OpenSim::Input< T >::getAlias(), OpenSim::Input< T >::getChannel(), OpenSim::AbstractSocket::getConnecteePath(), OpenSim::Input< T >::getLabel(), OpenSim::TimeSeriesTable_< SimTK::Vec3 >::getNearestRowIndexForTime(), OpenSim::TimeSeriesTable_< SimTK::Vec3 >::getRowIndexAfterTime(), OpenSim::TimeSeriesTable_< SimTK::Vec3 >::getRowIndexBeforeTime(), OpenSim::Input< T >::getValue(), OpenSim::Input< T >::setAlias(), OpenSim::AbstractSocket::setConnecteePath(), OpenSim::FileDeletionThrower::throwIfDeleted(), OpenSim::TimeSeriesTable_< SimTK::Vec3 >::TimeSeriesTable_(), OpenSim::TimeSeriesTable_< SimTK::Vec3 >::trim(), and OpenSim::TimeSeriesTable_< SimTK::Vec3 >::validateRow().

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