=====================
Errors and Exceptions
=====================

Errors
======

In any application, error situations will inevitably arise. When an error occurs, Visualize takes measures to respond to it internally. Part of that response is to create and dispatch an associated event. There are two types of problems for which Visualize will issue an event: warnings and errors. A warning will be issued when Visualize detects a *potential* problem scenario. For example, data of an unexpected size or format would cause a warning. If Visualize can safely guess at the solution by constraining the data within a certain limit, or perhaps ignoring trailing elements from an array that is too long, it will do so with a warning. However, warnings should not be ignored by your application because the results of an operation may be different than you expect.

An error event is similar to a warning, but more important. It indicates that Visualize detected a situation that could not be handled. An example of this would be a "file not found" error. If an error condition is detected resulting from a user request, such as a Database access, that request is aborted. It is left to the programmer to take action in the case of an error. If no action is taken, Visualize will simply continue execution as long as possible.

Error and warning events are handled in the same way as other events. For the most robust performance, your application should catch and respond to these events. The event code and description can be determined using the ``Event::code`` and ``Event::message`` members, respectively.

**NOTE:** For information on handling errors related to memory exhaustion, see the section on :doc:`memory management <0704_memory_management>`.


Exceptions
==========

Exceptions are entirely different from events and the event handling system. While event handling is used for any problem that occurs asynchronously, exceptions are thrown when a problematic condition is immediately apparent. Visualize uses the underlying language's standard exception mechanism to alert the client application of an exceptional event.

There are two types of exceptions that Visualize will throw:

``HPS::InvalidObjectException``

* upon attempt to use an uninitialized ``Database`` object
* upon attempt to use an object that has been deleted

``HPS::IndexOutOfRangeException``

* upon attempt to access out of bounds character in a ``UTF8`` string object
* upon attempt to access a character of a text object using an invalid column or row
