az_json.h

Go to the documentation of this file.

// Copyright (c) Microsoft Corporation. All rights reserved.
// SPDX-License-Identifier: MIT
 
#ifndef _az_JSON_H
#define _az_JSON_H
 
#include <azure/core/az_result.h>
#include <azure/core/az_span.h>
 
#include <stdbool.h>
#include <stdint.h>
 
#include <azure/core/_az_cfg_prefix.h>
 
typedef enum
{
  AZ_JSON_TOKEN_NONE, 
  AZ_JSON_TOKEN_BEGIN_OBJECT, 
  AZ_JSON_TOKEN_END_OBJECT, 
  AZ_JSON_TOKEN_BEGIN_ARRAY, 
  AZ_JSON_TOKEN_END_ARRAY, 
  AZ_JSON_TOKEN_PROPERTY_NAME, 
  AZ_JSON_TOKEN_STRING, 
  AZ_JSON_TOKEN_NUMBER, 
  AZ_JSON_TOKEN_TRUE, 
  AZ_JSON_TOKEN_FALSE, 
  AZ_JSON_TOKEN_NULL, 
} az_json_token_kind;
 
typedef struct
{
  struct
  {
    // This uint64_t container represents a tiny stack to track the state during nested transitions.
    // The first bit represents the state of the current depth (1 == object, 0 == array).
    // Each subsequent bit is the parent / containing type (object or array).
    uint64_t az_json_stack;
    int32_t current_depth;
  } _internal;
} _az_json_bit_stack;
 
typedef struct
{
  az_span slice;
 
  // Avoid using enum as the first field within structs, to allow for { 0 } initialization.
  // This is a workaround for IAR compiler warning [Pe188]: enumerated type mixed with another type.
 
  az_json_token_kind kind;
 
  int32_t size;
 
  struct
  {
    bool is_multisegment;
 
    bool string_has_escaped_chars;
 
    az_span* pointer_to_first_buffer;
 
    int32_t start_buffer_index;
 
    int32_t start_buffer_offset;
 
    int32_t end_buffer_index;
 
    int32_t end_buffer_offset;
  } _internal;
} az_json_token;
 
// TODO: Should the parameters be reversed?
az_span az_json_token_copy_into_span(az_json_token const* json_token, az_span destination);
 
AZ_NODISCARD az_result az_json_token_get_boolean(az_json_token const* json_token, bool* out_value);
 
AZ_NODISCARD az_result
az_json_token_get_uint64(az_json_token const* json_token, uint64_t* out_value);
 
AZ_NODISCARD az_result
az_json_token_get_uint32(az_json_token const* json_token, uint32_t* out_value);
 
AZ_NODISCARD az_result az_json_token_get_int64(az_json_token const* json_token, int64_t* out_value);
 
AZ_NODISCARD az_result az_json_token_get_int32(az_json_token const* json_token, int32_t* out_value);
 
AZ_NODISCARD az_result az_json_token_get_double(az_json_token const* json_token, double* out_value);
 
AZ_NODISCARD az_result az_json_token_get_string(
    az_json_token const* json_token,
    char* destination,
    int32_t destination_max_size,
    int32_t* out_string_length);
 
AZ_NODISCARD bool az_json_token_is_text_equal(
    az_json_token const* json_token,
    az_span expected_text);
 
/************************************ JSON WRITER ******************/
 
typedef struct
{
  struct
  {
    bool unused;
  } _internal;
} az_json_writer_options;
 
AZ_NODISCARD AZ_INLINE az_json_writer_options az_json_writer_options_default()
{
  az_json_writer_options options = (az_json_writer_options) {
    ._internal = {
      .unused = false,
    },
  };
 
  return options;
}
 
typedef struct
{
  struct
  {
    az_span destination_buffer;
    int32_t bytes_written;
    // For single contiguous buffer, bytes_written == total_bytes_written
    int32_t total_bytes_written; // Currently, this is primarily used for testing.
    az_span_allocator_fn allocator_callback;
    void* user_context;
    bool need_comma;
    az_json_token_kind token_kind; // needed for validation, potentially #if/def with preconditions.
    _az_json_bit_stack bit_stack; // needed for validation, potentially #if/def with preconditions.
    az_json_writer_options options;
  } _internal;
} az_json_writer;
 
AZ_NODISCARD az_result az_json_writer_init(
    az_json_writer* out_json_writer,
    az_span destination_buffer,
    az_json_writer_options const* options);
 
AZ_NODISCARD az_result az_json_writer_chunked_init(
    az_json_writer* out_json_writer,
    az_span first_destination_buffer,
    az_span_allocator_fn allocator_callback,
    void* user_context,
    az_json_writer_options const* options);
 
AZ_NODISCARD AZ_INLINE az_span
az_json_writer_get_bytes_used_in_destination(az_json_writer const* json_writer)
{
  return az_span_slice(
      json_writer->_internal.destination_buffer, 0, json_writer->_internal.bytes_written);
}
 
AZ_NODISCARD az_result az_json_writer_append_string(az_json_writer* ref_json_writer, az_span value);
 
AZ_NODISCARD az_result
az_json_writer_append_json_text(az_json_writer* ref_json_writer, az_span json_text);
 
AZ_NODISCARD az_result
az_json_writer_append_property_name(az_json_writer* ref_json_writer, az_span name);
 
AZ_NODISCARD az_result az_json_writer_append_bool(az_json_writer* ref_json_writer, bool value);
 
AZ_NODISCARD az_result az_json_writer_append_int32(az_json_writer* ref_json_writer, int32_t value);
 
AZ_NODISCARD az_result az_json_writer_append_double(
    az_json_writer* ref_json_writer,
    double value,
    int32_t fractional_digits);
 
AZ_NODISCARD az_result az_json_writer_append_null(az_json_writer* ref_json_writer);
 
AZ_NODISCARD az_result az_json_writer_append_begin_object(az_json_writer* ref_json_writer);
 
AZ_NODISCARD az_result az_json_writer_append_begin_array(az_json_writer* ref_json_writer);
 
AZ_NODISCARD az_result az_json_writer_append_end_object(az_json_writer* ref_json_writer);
 
AZ_NODISCARD az_result az_json_writer_append_end_array(az_json_writer* ref_json_writer);
 
/************************************ JSON READER ******************/
 
typedef struct
{
  struct
  {
    bool unused;
  } _internal;
} az_json_reader_options;
 
AZ_NODISCARD AZ_INLINE az_json_reader_options az_json_reader_options_default()
{
  az_json_reader_options options = (az_json_reader_options) {
    ._internal = {
      .unused = false,
    },
  };
 
  return options;
}
 
typedef struct
{
  az_json_token token;
 
  struct
  {
    az_span json_buffer;
 
    az_span* json_buffers;
 
    int32_t number_of_buffers;
 
    int32_t buffer_index;
 
    int32_t bytes_consumed;
 
    int32_t total_bytes_consumed;
 
    bool is_complex_json;
 
    _az_json_bit_stack bit_stack;
 
    az_json_reader_options options;
  } _internal;
} az_json_reader;
 
AZ_NODISCARD az_result az_json_reader_init(
    az_json_reader* out_json_reader,
    az_span json_buffer,
    az_json_reader_options const* options);
 
AZ_NODISCARD az_result az_json_reader_chunked_init(
    az_json_reader* out_json_reader,
    az_span json_buffers[],
    int32_t number_of_buffers,
    az_json_reader_options const* options);
 
AZ_NODISCARD az_result az_json_reader_next_token(az_json_reader* ref_json_reader);
 
AZ_NODISCARD az_result az_json_reader_skip_children(az_json_reader* ref_json_reader);
 
#include <azure/core/_az_cfg_suffix.h>
 
#endif // _az_JSON_H