Azure SDK for Embedded C
Data Structures | Macros | Typedefs | Functions
az_span.h File Reference

An az_span represents a contiguous byte buffer and is used for string manipulations, HTTP requests/responses, reading/writing JSON payloads, and more. More...

#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>
#include <azure/core/_az_cfg_suffix.h>

Go to the source code of this file.

Data Structures

struct  az_span
 Represents a "view" over a byte buffer that represents a contiguous region of memory. It contains a pointer to the start of the byte buffer and the buffer's size. More...
 
struct  az_span_allocator_context
 Defines a container of required and user-defined fields that provide the necessary information and parameters for the implementation of the az_span_allocator_fn callback. More...
 

Macros

#define AZ_SPAN_LITERAL_EMPTY
 An empty az_span literal. More...
 
#define AZ_SPAN_EMPTY   (az_span) AZ_SPAN_LITERAL_EMPTY
 An empty az_span. More...
 
#define AZ_SPAN_LITERAL_FROM_STR(STRING_LITERAL)
 Returns a literal az_span over a literal string. The size of the az_span is equal to the length of the string. More...
 
#define AZ_SPAN_FROM_STR(STRING_LITERAL)   (az_span) AZ_SPAN_LITERAL_FROM_STR(STRING_LITERAL)
 Returns an az_span expression over a literal string. More...
 
#define AZ_SPAN_FROM_BUFFER(BYTE_BUFFER)
 Returns an az_span expression over an uninitialized byte buffer. More...
 

Typedefs

typedef az_result(* az_span_allocator_fn) (az_span_allocator_context *allocator_context, az_span *out_next_destination)
 Defines the signature of the callback function that the caller must implement to provide the potentially discontiguous destination buffers where output can be written into. More...
 

Functions

AZ_NODISCARD AZ_INLINE uint8_t * az_span_ptr (az_span span)
 Returns the az_span byte buffer's starting memory address. More...
 
AZ_NODISCARD AZ_INLINE int32_t az_span_size (az_span span)
 Returns the number of bytes within the az_span. More...
 
AZ_NODISCARD az_span az_span_create (uint8_t *ptr, int32_t size)
 Returns an az_span over a byte buffer. More...
 
AZ_NODISCARD az_span az_span_create_from_str (char *str)
 Returns an az_span from a 0-terminated array of bytes (chars). More...
 
AZ_NODISCARD az_span az_span_slice (az_span span, int32_t start_index, int32_t end_index)
 Returns a new az_span which is a sub-span of the specified span. More...
 
AZ_NODISCARD az_span az_span_slice_to_end (az_span span, int32_t start_index)
 Returns a new az_span which is a sub-span of the specified span. More...
 
AZ_NODISCARD AZ_INLINE bool az_span_is_content_equal (az_span span1, az_span span2)
 Determines whether two spans are equal by comparing their bytes. More...
 
AZ_NODISCARD bool az_span_is_content_equal_ignoring_case (az_span span1, az_span span2)
 Determines whether two spans are equal by comparing their characters, except for casing. More...
 
void az_span_to_str (char *destination, int32_t destination_max_size, az_span source)
 Copies a source az_span containing a string (that is not 0-terminated) to a destination char buffer and appends the 0-terminating byte. More...
 
AZ_NODISCARD int32_t az_span_find (az_span source, az_span target)
 Searches for target in source, returning an az_span within source if it finds it. More...
 
az_span az_span_copy (az_span destination, az_span source)
 Copies the content of the source az_span to the destination az_span. More...
 
az_span az_span_copy_u8 (az_span destination, uint8_t byte)
 Copies the uint8_t byte to the destination at its 0-th index. More...
 
AZ_INLINE void az_span_fill (az_span destination, uint8_t value)
 Fills all the bytes of the destination az_span with the specified value. More...
 
AZ_NODISCARD az_result az_span_atou64 (az_span source, uint64_t *out_number)
 Parses an az_span containing ASCII digits into a uint64_t number. More...
 
AZ_NODISCARD az_result az_span_atoi64 (az_span source, int64_t *out_number)
 Parses an az_span containing ASCII digits into an int64_t number. More...
 
AZ_NODISCARD az_result az_span_atou32 (az_span source, uint32_t *out_number)
 Parses an az_span containing ASCII digits into a uint32_t number. More...
 
AZ_NODISCARD az_result az_span_atoi32 (az_span source, int32_t *out_number)
 Parses an az_span containing ASCII digits into an int32_t number. More...
 
AZ_NODISCARD az_result az_span_atod (az_span source, double *out_number)
 Parses an az_span containing ASCII digits into a double number. More...
 
AZ_NODISCARD az_result az_span_i32toa (az_span destination, int32_t source, az_span *out_span)
 Converts an int32_t into its digit characters (base 10) and copies them to the destination az_span starting at its 0-th index. More...
 
AZ_NODISCARD az_result az_span_u32toa (az_span destination, uint32_t source, az_span *out_span)
 Converts an uint32_t into its digit characters (base 10) and copies them to the destination az_span starting at its 0-th index. More...
 
AZ_NODISCARD az_result az_span_i64toa (az_span destination, int64_t source, az_span *out_span)
 Converts an int64_t into its digit characters (base 10) and copies them to the destination az_span starting at its 0-th index. More...
 
AZ_NODISCARD az_result az_span_u64toa (az_span destination, uint64_t source, az_span *out_span)
 Converts a uint64_t into its digit characters (base 10) and copies them to the destination az_span starting at its 0-th index. More...
 
AZ_NODISCARD az_result az_span_dtoa (az_span destination, double source, int32_t fractional_digits, az_span *out_span)
 Converts a double into its digit characters (base 10 decimal notation) and copies them to the destination az_span starting at its 0-th index. More...
 

Detailed Description

An az_span represents a contiguous byte buffer and is used for string manipulations, HTTP requests/responses, reading/writing JSON payloads, and more.

Note
You MUST NOT use any symbols (macros, functions, structures, enums, etc.) prefixed with an underscore ('_') directly in your application code. These symbols are part of Azure SDK's internal implementation; we do not document these symbols and they are subject to change in future versions of the SDK which would break your code.

Macro Definition Documentation

◆ AZ_SPAN_EMPTY

#define AZ_SPAN_EMPTY   (az_span) AZ_SPAN_LITERAL_EMPTY

An empty az_span.

Remarks
There is no guarantee that the pointer backing this span will be NULL and the caller shouldn't rely on it. However, the size will be 0.

◆ AZ_SPAN_FROM_BUFFER

#define AZ_SPAN_FROM_BUFFER (   BYTE_BUFFER)
Value:
(uint8_t*)(BYTE_BUFFER), (sizeof(BYTE_BUFFER) / (_az_IS_BYTE_ARRAY(BYTE_BUFFER) ? 1 : 0)))

Returns an az_span expression over an uninitialized byte buffer.

For example:

uint8_t buffer[1024];

some_function(AZ_SPAN_FROM_BUFFER(buffer)); // Size = 1024

Remarks
BYTE_BUFFER MUST be an array defined like uint8_t buffer[10]; and not uint8_t* buffer

◆ AZ_SPAN_FROM_STR

#define AZ_SPAN_FROM_STR (   STRING_LITERAL)    (az_span) AZ_SPAN_LITERAL_FROM_STR(STRING_LITERAL)

Returns an az_span expression over a literal string.

For example:

some_function(AZ_SPAN_FROM_STR("Hello world"));

where

void some_function(const az_span span);

◆ AZ_SPAN_LITERAL_EMPTY

#define AZ_SPAN_LITERAL_EMPTY
Value:
{ \
._internal = {.ptr = NULL, .size = 0 } \
}

An empty az_span literal.

Remarks
There is no guarantee that the pointer backing this span will be NULL and the caller shouldn't rely on it. However, the size will be 0.

◆ AZ_SPAN_LITERAL_FROM_STR

#define AZ_SPAN_LITERAL_FROM_STR (   STRING_LITERAL)
Value:
{ \
._internal = { \
.ptr = (uint8_t*)(STRING_LITERAL), \
.size = _az_STRING_LITERAL_LEN(STRING_LITERAL), \
}, \
}

Returns a literal az_span over a literal string. The size of the az_span is equal to the length of the string.

For example:

static const az_span hw = AZ_SPAN_LITERAL_FROM_STR("Hello world");

Remarks
An empty ("") literal string results in an az_span with size set to 0.

Typedef Documentation

◆ az_span_allocator_fn

typedef az_result(* az_span_allocator_fn) (az_span_allocator_context *allocator_context, az_span *out_next_destination)

Defines the signature of the callback function that the caller must implement to provide the potentially discontiguous destination buffers where output can be written into.

Parameters
[in]allocator_contextA container of required and user-defined fields that provide the necessary information and parameters for the implementation of the callback.
[out]out_next_destinationA pointer to an az_span that can be used as a destination to write data into, that is at least the required size specified within the allocator_context.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKSuccess.
otherFailure.
Remarks
The caller must no longer hold onto, use, or write to the previously provided az_span after this allocator returns a new destination az_span.
There is no guarantee that successive calls will return the same or same-sized buffer. This function must never return an empty az_span, unless the requested buffer size is not available. In which case, it must return an error az_result.
The caller must check the return value using az_result_failed() before continuing to use the out_next_destination.

Function Documentation

◆ az_span_atod()

AZ_NODISCARD az_result az_span_atod ( az_span  source,
double *  out_number 
)

Parses an az_span containing ASCII digits into a double number.

Parameters
[in]sourceThe az_span containing the ASCII digits to be parsed.
[out]out_numberThe pointer to the variable that is to receive the number.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKSuccess.
AZ_ERROR_UNEXPECTED_CHARA non-ASCII digit or an invalid character is found within the span, or the resulting out_number wouldn't be a finite double number.
Remarks
The az_span being parsed must contain a number that is finite. Values such as NaN, INFINITY, and those that would overflow a double to +/-inf are not allowed.

◆ az_span_atoi32()

AZ_NODISCARD az_result az_span_atoi32 ( az_span  source,
int32_t *  out_number 
)

Parses an az_span containing ASCII digits into an int32_t number.

Parameters
[in]sourceThe az_span containing the ASCII digits to be parsed.
[out]out_numberThe pointer to the variable that is to receive the number.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKSuccess.
AZ_ERROR_UNEXPECTED_CHARA non-ASCII digit is found within the span or if the source contains a number that would overflow or underflow int32_t.

◆ az_span_atoi64()

AZ_NODISCARD az_result az_span_atoi64 ( az_span  source,
int64_t *  out_number 
)

Parses an az_span containing ASCII digits into an int64_t number.

Parameters
[in]sourceThe az_span containing the ASCII digits to be parsed.
[out]out_numberThe pointer to the variable that is to receive the number.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKSuccess.
AZ_ERROR_UNEXPECTED_CHARA non-ASCII digit is found within the span or the source contains a number that would overflow or underflow int64_t.

◆ az_span_atou32()

AZ_NODISCARD az_result az_span_atou32 ( az_span  source,
uint32_t *  out_number 
)

Parses an az_span containing ASCII digits into a uint32_t number.

Parameters
[in]sourceThe az_span containing the ASCII digits to be parsed.
[out]out_numberThe pointer to the variable that is to receive the number.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKSuccess.
AZ_ERROR_UNEXPECTED_CHARA non-ASCII digit is found within the span or the source contains a number that would overflow or underflow uint32_t.

◆ az_span_atou64()

AZ_NODISCARD az_result az_span_atou64 ( az_span  source,
uint64_t *  out_number 
)

Parses an az_span containing ASCII digits into a uint64_t number.

Parameters
[in]sourceThe az_span containing the ASCII digits to be parsed.
[out]out_numberThe pointer to the variable that is to receive the number.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKSuccess.
AZ_ERROR_UNEXPECTED_CHARA non-ASCII digit is found within the span or the source contains a number that would overflow or underflow uint64_t.

◆ az_span_copy()

az_span az_span_copy ( az_span  destination,
az_span  source 
)

Copies the content of the source az_span to the destination az_span.

Parameters
destinationThe az_span whose bytes will be replaced by the bytes from source.
[in]sourceThe az_span containing the bytes to copy to the destination.
Returns
An az_span that is a slice of the destination az_span (i.e. the remainder) after the source bytes have been copied.
Remarks
This function assumes that the destination has a large enough size to hold the source.
This function copies all of source into the destination even if they overlap.
If source is an empty az_span or AZ_SPAN_EMPTY, this function will just return destination.

◆ az_span_copy_u8()

az_span az_span_copy_u8 ( az_span  destination,
uint8_t  byte 
)

Copies the uint8_t byte to the destination at its 0-th index.

Parameters
destinationThe az_span where the byte should be copied to.
[in]byteThe uint8_t to copy into the destination span.
Returns
An az_span that is a slice of the destination az_span (i.e. the remainder) after the byte has been copied.
Remarks
The function assumes that the destination has a large enough size to hold one more byte.

◆ az_span_create()

AZ_NODISCARD az_span az_span_create ( uint8_t *  ptr,
int32_t  size 
)

Returns an az_span over a byte buffer.

Parameters
[in]ptrThe memory address of the first byte in the byte buffer.
[in]sizeThe total number of bytes in the byte buffer.
Returns
The "view" over the byte buffer.

◆ az_span_create_from_str()

AZ_NODISCARD az_span az_span_create_from_str ( char *  str)

Returns an az_span from a 0-terminated array of bytes (chars).

Parameters
[in]strThe pointer to the 0-terminated array of bytes (chars).
Returns
An az_span over the byte buffer where the size is set to the string's length not including the \0 terminator.

◆ az_span_dtoa()

AZ_NODISCARD az_result az_span_dtoa ( az_span  destination,
double  source,
int32_t  fractional_digits,
az_span out_span 
)

Converts a double into its digit characters (base 10 decimal notation) and copies them to the destination az_span starting at its 0-th index.

Parameters
destinationThe az_span where the bytes should be copied to.
[in]sourceThe double whose number is copied to the destination az_span as ASCII digits and characters.
[in]fractional_digitsThe number of digits to write into the destination az_span after the decimal point and truncate the rest.
[out]out_spanA pointer to an az_span that receives the remainder of the destination az_span after the double has been copied.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKSuccess.
AZ_ERROR_NOT_ENOUGH_SPACEThe destination is not big enough to contain the copied bytes.
AZ_ERROR_NOT_SUPPORTEDThe source is not a finite decimal number or contains an integer component that is too large and would overflow beyond 2^53 - 1.
Remarks
Only finite double values are supported. Values such as NaN and INFINITY are not allowed.
Non-significant trailing zeros (after the decimal point) are not written, even if fractional_digits is large enough to allow the zero padding.
The fractional_digits must be between 0 and 15 (inclusive). Any value passed in that is larger will be clamped down to 15.

◆ az_span_fill()

AZ_INLINE void az_span_fill ( az_span  destination,
uint8_t  value 
)

Fills all the bytes of the destination az_span with the specified value.

Parameters
destinationThe az_span whose bytes will be set to value.
[in]valueThe byte to be replicated within the destination az_span.

◆ az_span_find()

AZ_NODISCARD int32_t az_span_find ( az_span  source,
az_span  target 
)

Searches for target in source, returning an az_span within source if it finds it.

Parameters
[in]sourceThe az_span with the content to be searched on.
[in]targetThe az_span containing the tokens to be searched within source.
Returns
The position of target in source if source contains the target within it.
Return values
0target is empty (if its size is equal zero).
-1target is not found in source OR source is empty (if its size is zero) and target is non-empty.
>=0The position of target in source.

◆ az_span_i32toa()

AZ_NODISCARD az_result az_span_i32toa ( az_span  destination,
int32_t  source,
az_span out_span 
)

Converts an int32_t into its digit characters (base 10) and copies them to the destination az_span starting at its 0-th index.

Parameters
destinationThe az_span where the bytes should be copied to.
[in]sourceThe int32_t whose number is copied to the destination az_span as ASCII digits.
[out]out_spanA pointer to an az_span that receives the remainder of the destination az_span after the int32_t has been copied.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKSuccess.
AZ_ERROR_NOT_ENOUGH_SPACEThe destination is not big enough to contain the copied bytes.

◆ az_span_i64toa()

AZ_NODISCARD az_result az_span_i64toa ( az_span  destination,
int64_t  source,
az_span out_span 
)

Converts an int64_t into its digit characters (base 10) and copies them to the destination az_span starting at its 0-th index.

Parameters
destinationThe az_span where the bytes should be copied to.
[in]sourceThe int64_t whose number is copied to the destination az_span as ASCII digits.
[out]out_spanA pointer to an az_span that receives the remainder of the destination az_span after the int64_t has been copied.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKSuccess.
AZ_ERROR_NOT_ENOUGH_SPACEThe destination is not big enough to contain the copied bytes.

◆ az_span_is_content_equal()

AZ_NODISCARD AZ_INLINE bool az_span_is_content_equal ( az_span  span1,
az_span  span2 
)

Determines whether two spans are equal by comparing their bytes.

Parameters
[in]span1The first az_span to compare.
[in]span2The second az_span to compare.
Returns
true if the sizes of both spans are identical and the bytes in both spans are also identical. Otherwise, false.

◆ az_span_is_content_equal_ignoring_case()

AZ_NODISCARD bool az_span_is_content_equal_ignoring_case ( az_span  span1,
az_span  span2 
)

Determines whether two spans are equal by comparing their characters, except for casing.

Parameters
[in]span1The first az_span to compare.
[in]span2The second az_span to compare.
Returns
true if the sizes of both spans are identical and the ASCII characters in both spans are also identical, except for casing.
Remarks
This function assumes the bytes in both spans are ASCII characters.

◆ az_span_ptr()

AZ_NODISCARD AZ_INLINE uint8_t* az_span_ptr ( az_span  span)

Returns the az_span byte buffer's starting memory address.

Parameters
[in]spanThe az_span whose starting memory address to return.
Returns
Starting memory address of span buffer.

◆ az_span_size()

AZ_NODISCARD AZ_INLINE int32_t az_span_size ( az_span  span)

Returns the number of bytes within the az_span.

Parameters
[in]spanThe az_span whose size to return.
Returns
Size of span buffer.

◆ az_span_slice()

AZ_NODISCARD az_span az_span_slice ( az_span  span,
int32_t  start_index,
int32_t  end_index 
)

Returns a new az_span which is a sub-span of the specified span.

Parameters
[in]spanThe original az_span.
[in]start_indexAn index into the original az_span indicating where the returned az_span will start.
[in]end_indexAn index into the original az_span indicating where the returned az_span should stop. The byte at the end_index is NOT included in the returned az_span.
Returns
An az_span into a portion (from start_index to end_index - 1) of the original az_span.

◆ az_span_slice_to_end()

AZ_NODISCARD az_span az_span_slice_to_end ( az_span  span,
int32_t  start_index 
)

Returns a new az_span which is a sub-span of the specified span.

Parameters
[in]spanThe original az_span.
[in]start_indexAn index into the original az_span indicating where the returned az_span will start.
Returns
An az_span into a portion (from start_index to the size) of the original az_span.

◆ az_span_to_str()

void az_span_to_str ( char *  destination,
int32_t  destination_max_size,
az_span  source 
)

Copies a source az_span containing a string (that is not 0-terminated) to a destination char buffer and appends the 0-terminating byte.

Parameters
destinationA pointer to a buffer where the string should be copied into.
[in]destination_max_sizeThe maximum available space within the buffer referred to by destination.
[in]sourceThe az_span containing the not-0-terminated string to copy into destination.
Remarks
The buffer referred to by destination must have a size that is at least 1 byte bigger than the source az_span for the destination string to be zero-terminated. Content is copied from the source buffer and then \0 is added at the end.

◆ az_span_u32toa()

AZ_NODISCARD az_result az_span_u32toa ( az_span  destination,
uint32_t  source,
az_span out_span 
)

Converts an uint32_t into its digit characters (base 10) and copies them to the destination az_span starting at its 0-th index.

Parameters
destinationThe az_span where the bytes should be copied to.
[in]sourceThe uint32_t whose number is copied to the destination az_span as ASCII digits.
[out]out_spanA pointer to an az_span that receives the remainder of the destination az_span after the uint32_t has been copied.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKSuccess.
AZ_ERROR_NOT_ENOUGH_SPACEThe destination is not big enough to contain the copied bytes.

◆ az_span_u64toa()

AZ_NODISCARD az_result az_span_u64toa ( az_span  destination,
uint64_t  source,
az_span out_span 
)

Converts a uint64_t into its digit characters (base 10) and copies them to the destination az_span starting at its 0-th index.

Parameters
destinationThe az_span where the bytes should be copied to.
[in]sourceThe uint64_t whose number is copied to the destination az_span as ASCII digits.
[out]out_spanA pointer to an az_span that receives the remainder of the destination az_span after the uint64_t has been copied.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKSuccess.
AZ_ERROR_NOT_ENOUGH_SPACEThe destination is not big enough to contain the copied bytes.
az_span_create
AZ_NODISCARD az_span az_span_create(uint8_t *ptr, int32_t size)
Returns an az_span over a byte buffer.