az_span.h

Go to the documentation of this file.

// Copyright (c) Microsoft Corporation. All rights reserved.
// SPDX-License-Identifier: MIT
 
#ifndef _az_SPAN_H
#define _az_SPAN_H
 
#include <azure/core/az_result.h>
 
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <string.h>
 
#include <azure/core/_az_cfg_prefix.h>
 
typedef struct
{
  struct
  {
    uint8_t* ptr;
    int32_t size; // size must be >= 0
  } _internal;
} az_span;
 
/********************************  SPAN GETTERS */
 
AZ_NODISCARD AZ_INLINE uint8_t* az_span_ptr(az_span span) { return span._internal.ptr; }
 
AZ_NODISCARD AZ_INLINE int32_t az_span_size(az_span span) { return span._internal.size; }
 
/********************************  CONSTRUCTORS */
 
// Note: If you are modifying this function, make sure to modify the non-inline version in the
// az_span.c file as well, and the _az_ version right below.
#ifdef AZ_NO_PRECONDITION_CHECKING
AZ_NODISCARD AZ_INLINE az_span az_span_create(uint8_t* ptr, int32_t size)
{
  return (az_span){ ._internal = { .ptr = ptr, .size = size } };
}
#else
AZ_NODISCARD az_span az_span_create(uint8_t* ptr, int32_t size);
#endif // AZ_NO_PRECONDITION_CHECKING
 
#define AZ_SPAN_LITERAL_EMPTY              \
  {                                        \
    ._internal = {.ptr = NULL, .size = 0 } \
  }
 
#define AZ_SPAN_EMPTY (az_span) AZ_SPAN_LITERAL_EMPTY
 
// Returns the size (in bytes) of a literal string.
// Note: Concatenating "" to S produces a compiler error if S is not a literal string
//       The stored string's length does not include the \0 terminator.
#define _az_STRING_LITERAL_LEN(S) (sizeof(S "") - 1)
 
#define AZ_SPAN_LITERAL_FROM_STR(STRING_LITERAL)      \
  {                                                   \
    ._internal = {                                    \
      .ptr = (uint8_t*)(STRING_LITERAL),              \
      .size = _az_STRING_LITERAL_LEN(STRING_LITERAL), \
    },                                                \
  }
 
#define AZ_SPAN_FROM_STR(STRING_LITERAL) (az_span) AZ_SPAN_LITERAL_FROM_STR(STRING_LITERAL)
 
// Returns 1 if the address of the array is equal to the address of its 1st element.
// Returns 0 for anything that is not an array (for example any arbitrary pointer).
#define _az_IS_ARRAY(array) (((void*)&(array)) == ((void*)(&(array)[0])))
 
// Returns 1 if the element size of the array is 1 (which is only true for byte arrays such as
// uint8_t[] and char[]).
// Returns 0 for any other element size (for example int32_t[]).
#define _az_IS_BYTE_ARRAY(array) ((sizeof((array)[0]) == 1) && _az_IS_ARRAY(array))
 
// Force a division by 0 that gets detected by compilers for anything that isn't a byte array.
#define AZ_SPAN_FROM_BUFFER(BYTE_BUFFER) \
  az_span_create(                        \
      (uint8_t*)(BYTE_BUFFER), (sizeof(BYTE_BUFFER) / (_az_IS_BYTE_ARRAY(BYTE_BUFFER) ? 1 : 0)))
 
AZ_NODISCARD az_span az_span_create_from_str(char* str);
 
/******************************  SPAN MANIPULATION */
 
AZ_NODISCARD az_span az_span_slice(az_span span, int32_t start_index, int32_t end_index);
 
AZ_NODISCARD az_span az_span_slice_to_end(az_span span, int32_t start_index);
 
AZ_NODISCARD AZ_INLINE bool az_span_is_content_equal(az_span span1, az_span span2)
{
  int32_t span1_size = az_span_size(span1);
  int32_t span2_size = az_span_size(span2);
 
  // Make sure to avoid passing a null pointer to memcmp, which is considered undefined.
  // We assume that if the size is non-zero, then the pointer can't be null.
  if (span1_size == 0)
  {
    // Two empty spans are considered equal, even if their pointers are different.
    return span2_size == 0;
  }
 
  // If span2_size == 0, then the first condition which compares sizes will be false, since we
  // checked the size of span1 above. And due to short-circuiting we won't be calling memcmp anyway.
  // Therefore, we don't need to check for that explicitly.
  return span1_size == span2_size
      && memcmp(az_span_ptr(span1), az_span_ptr(span2), (size_t)span1_size) == 0;
}
 
AZ_NODISCARD bool az_span_is_content_equal_ignoring_case(az_span span1, az_span span2);
 
void az_span_to_str(char* destination, int32_t destination_max_size, az_span source);
 
AZ_NODISCARD int32_t az_span_find(az_span source, az_span target);
 
/******************************  SPAN COPYING */
 
az_span az_span_copy(az_span destination, az_span source);
 
az_span az_span_copy_u8(az_span destination, uint8_t byte);
 
AZ_INLINE void az_span_fill(az_span destination, uint8_t value)
{
  // NOLINTNEXTLINE(clang-analyzer-security.insecureAPI.DeprecatedOrUnsafeBufferHandling)
  memset(az_span_ptr(destination), value, (size_t)az_span_size(destination));
}
 
/******************************  SPAN PARSING AND FORMATTING */
 
AZ_NODISCARD az_result az_span_atou64(az_span source, uint64_t* out_number);
 
AZ_NODISCARD az_result az_span_atoi64(az_span source, int64_t* out_number);
 
AZ_NODISCARD az_result az_span_atou32(az_span source, uint32_t* out_number);
 
AZ_NODISCARD az_result az_span_atoi32(az_span source, int32_t* out_number);
 
AZ_NODISCARD az_result az_span_atod(az_span source, double* out_number);
 
AZ_NODISCARD az_result az_span_i32toa(az_span destination, int32_t source, az_span* out_span);
 
AZ_NODISCARD az_result az_span_u32toa(az_span destination, uint32_t source, az_span* out_span);
 
AZ_NODISCARD az_result az_span_i64toa(az_span destination, int64_t source, az_span* out_span);
 
AZ_NODISCARD az_result az_span_u64toa(az_span destination, uint64_t source, az_span* out_span);
 
AZ_NODISCARD az_result
az_span_dtoa(az_span destination, double source, int32_t fractional_digits, az_span* out_span);
 
/******************************  NON-CONTIGUOUS SPAN  */
 
typedef struct
{
  void* user_context;
 
  int32_t bytes_used;
 
  int32_t minimum_required_size;
} az_span_allocator_context;
 
typedef az_result (*az_span_allocator_fn)(
    az_span_allocator_context* allocator_context,
    az_span* out_next_destination);
 
#include <azure/core/_az_cfg_suffix.h>
 
#endif // _az_SPAN_H