Error

#include <Ultralight/dom/Error.h>

Overview

The reason a DOM operation failed.

dom::Error holds the details of a failed DOM operation, such as a DOM exception or a handle whose page is gone.

Passing dom::Checked returns a dom::Result you can inspect on failure:

dom::Result<dom::Element> total =
    document.querySelector("#scores td.total", dom::Checked);
if (!total) {
  if (total.error().is_page_gone())
    return;                          // the page went away (nothing to report)
  Log(total.error().message());      // eg, a malformed selector
}

Getting an Error

DOM operations return an empty value on failure instead of throwing C++ exceptions. Most code never needs dom::Error because operations on empty values fail safely without extra checks.

To inspect a failure, pass dom::Checked as an extra argument to receive a dom::Result holding either the value or a dom::Error.

When you've inspected the error and want to continue with an empty value, pass the dom::Result to dom::OrEmpty().

Kinds of Errors

Specific query methods identify each failure condition:

Kind	How to Check
DOM exception	is_dom_exception() is true, and type() gives the code
Empty handle	is_empty() is true
Page gone	is_page_gone() is true
Native error	Created by Make() or the library, other checks return false

How you handle an error depends on its condition:

• Ignore page-gone errors in routine code. A page can navigate away at any moment, leaving nothing to report.
• Treat empty-handle errors as application bugs. They indicate that native code operated on an unassigned handle, a moved-from handle, or a lookup that found nothing.
• Inspect type() rather than message() in code. The message text is meant for human diagnostics and can change between releases, while type() returns stable dom::ErrorType values.

Note

An error you get through dom::Checked isn't logged by DOM diagnostics.

See also

dom::Checked, dom::Result, dom::ErrorType, dom::OrEmpty()

Static Public Member Functions
static Error	PageGone ()
	Create a page-gone error (is_page_gone() returns true).
static Error	AdoptDOMException (ULDOMError &error)
	Create an error from a DOM exception reported by the C API.
static Error	Make (ErrorType type, std::string message)
	Create a native error.

Public Member Functions
bool	is_page_gone () const
	Whether or not this error means the handle's page is gone.
bool	is_empty () const
	Whether or not this error means a handle holds nothing (see the class notes).
bool	is_dom_exception () const
	Whether or not this error holds a DOM exception.
ErrorType	type () const
	Get the error's type.
std::string	message () const
	Get a readable description of the error.

Member Function Documentation

AdoptDOMException()

Error AdoptDOMException ( ULDOMError & error )

inlinestatic

Create an error from a DOM exception reported by the C API.

Parameters

error

The ULDOMError a C function filled in. The new Error takes its message, and error is reset to zero (so don't destroy the message yourself).

Returns

Returns the new Error (is_dom_exception() returns true).

is_dom_exception()

bool is_dom_exception ( ) const

inline

Whether or not this error holds a DOM exception.

is_empty()

bool is_empty ( ) const

inline

Whether or not this error means a handle holds nothing (see the class notes).

is_page_gone()

bool is_page_gone ( ) const

inline

Whether or not this error means the handle's page is gone.

Make()

Error Make ( ErrorType type, std::string message )

inlinestatic

Create a native error.

Parameters

type	The error type, returned by type().
message	The description, returned by message().

Returns

Returns the new Error.

message()

std::string message ( ) const

inline

Get a readable description of the error.

A DOM exception without a message of its own reads as its type (eg, SyntaxError). The text is written for people and can change in any release, so check type() in code instead.

PageGone()

Error PageGone ( )

inlinestatic

Create a page-gone error (is_page_gone() returns true).

Returns

Returns the new Error.

type()

ErrorType type ( ) const

inline

Get the error's type.

Returns

Returns the kind of DOM exception, the type passed to Make(), or ErrorType::None for a page-gone or empty-handle error.

---

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

• Ultralight/dom/Error.h