bdljsn_error

Detailed Description

Provide a description of an error processing a document.

Outline

• Purpose
• Classes
• Description
  • Attributes
  • Usage
    • Example 1: Populating an bdljsn::Error Object

Purpose

Provide a description of an error processing a document.

Classes

• bdljsn::Error: a description of a document processing error

See also

bdljsn_jsonutil, bdljsn_json

Description

This component provides a single, un-constrained (value-semantic) attribute class, bdljsn::Error, that is used to describe an error in the occured processing a (JSON) document.

Attributes

Name                Type          Default
------------------  -----------   -------
location            Location      Location(0)
message             string        ""

• location: the location in the document where the error occured
• message: a description of the error that occured

Usage

This section illustrates intended use of this component.

Example 1: Populating an bdljsn::Error Object

This component is designed to describe an error that occured when processing a (JSON) document. Suppose we are implementing a function, extractIntegerToken, that parses a numeric token and obtains an int value:

First, we define the function signature:

/// Load to the specified `value` the `int` value represented by the
/// specified `inputText`.  Return 0 on success, and a non-zero value
/// otherwise with no effect on `*value` and the specified `error` is set.
int extractIntegerToken(int              *value,
                        bdljsn::Error    *error,
                        bsl::string_view  inputText)
{
    BSLS_ASSERT(value);
    BSLS_ASSERT(error);
 
    enum { e_SUCCESS, e_FAILURE };
    // ...

Then, we attempt to exact a int value from the inputText:

    int                                      result;
    bsl::pair<MyParseStatus::Enum, unsigned> status =
                               MyNumericUtil::parseInt(&result, inputText);

Now, we check the parse status and if unsuccessful, we use the status information to set the bsljsn::Error object expected by our caller:

    if (MyParseStatus::e_OK != status.first) {
        unsigned position = status.second;
        error->setLocation(bdljsn::Location(static_cast<bsl::uint64_t>(
                                                               position)));
        error->setMessage(MyParseStatus::toAscii(status.first));
        return e_FAILURE;                                         // RETURN
    }

Finally, if the parse was successful, set the output parameter and return with status value that indicates success.

    *value = result;
    return e_SUCCESS;
}