bdljsn_numberutil

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Interpreting a JSON Number String

Purpose

Provide utilities converting between JSON text and numeric types.

Classes

• bdljsn::NumberUtil: conversion between JSON text and numeric types

Description

This component provides a struct, bdljsn::NumberUtil, that is a namespace for a suite of functions for working with the JSON number text format. bdljsn::NumberUtil provides a function isValidNumber to determine whether a string is a valid JSON number. Many of the other operations in this component have, as a precondition, that isValidNumber is true for the text. For information about the JSON number specification and additional background on the behavior of numbers in bdljsn see {bdljsn_jsonnumber}.

Many of the operations in this component have isValidNumber as a precondition in order to provide simpler and more efficient implementations. In the context of JsonNumber, the text will always be validated prior to performing other operations.

Usage

This section illustrates intended use of this component.

Example 1: Interpreting a JSON Number String

This example demonstrates using bdljsn::NumberUtil to work with a JSON number string. Imagine we are given and array of strings for numbers we expect to be integers, for each string we want to render some properties for that number.

First, we define an interesting set of example data:

const char *EXAMPLE_DATA[] = {
   // value                               converted int value & notes
   // -----                               ---------------------------
   "NaN",                                // invalid number
   "INF",                                // invalid number
   "1",                                  // 1,         exact
   "1.5",                                // 1,         not an integer
   "-9223372036854775809",               // INT64_MIN, underflow
   "1.5e27",                             // INT64_MAX, overflow
};
const int NUM_DATA = sizeof(EXAMPLE_DATA) / sizeof(*EXAMPLE_DATA);

Then, for each number, we first check whether it is a valid JSON Number (note that the behavior for the other methods is undefined unless the text is a valid JSON Number):

for (int i = 0; i < NUM_DATA; ++i) {
    const char *EXAMPLE = EXAMPLE_DATA[i];
    bsl::cout << "\"" << EXAMPLE << "\": " << bsl::endl;
    if (!bdljsn::NumberUtil::isValidNumber(EXAMPLE)) {
        bsl::cout << "  * is NOT a JSON Number" << bsl::endl;
        continue;                                               // CONTINUE
    }

Next we verify that the number is an integer. This will return an accurate result even when the integer cannot be represented.

    if (bdljsn::NumberUtil::isIntegralNumber(EXAMPLE)) {
        bsl::cout << "  * is an integer" << bsl::endl;
    }
    else {
        bsl::cout << "  * is not an integer" << bsl::endl;
    }

Finally, we convert that number to an integer:

    bsls::Types::Int64 value;
    int rc = bdljsn::NumberUtil::asInt64(&value, EXAMPLE);
 
    bsl::cout << "  * value: " << value;
 
    if (bdljsn::NumberUtil::k_NOT_INTEGRAL == rc) {
        bsl::cout << "  (truncated)";
    }
    if (bdljsn::NumberUtil::k_OVERFLOW == rc) {
        bsl::cout << "  (overflow)";
    }
    if (bdljsn::NumberUtil::k_UNDERFLOW == rc) {
        bsl::cout << "  (underflow)";
    }
    bsl::cout << bsl::endl;
}

This will output the text:

"NaN":
  * is NOT a JSON Number
"INF":
  * is NOT a JSON Number
"1":
  * is an integer
  * value: 1
"1.5":
  * is not an integer
  * value: 1  (truncated)
"-9223372036854775809":
  * is an integer
  * value: -9223372036854775808  (underflow)
"1.5e27":
  * is an integer
  * value: 9223372036854775807  (overflow)