Component bdljsn_error [Package bdljsn]

Provide a description of an error processing a document. More...

Namespaces
namespace	bdljsn

---

Detailed Description

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:

Component bdljsn_jsonutil, Component 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:

  int extractIntegerToken(int              *value,
                          bdljsn::Error    *error,
                          bsl::string_view  inputText)
      // 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.
  {
      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;
  }