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>

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:

az_span_create( \

(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_context	A container of required and user-defined fields that provide the necessary information and parameters for the implementation of the callback.
[out]	out_next_destination	A 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_OK	Success.
other	Failure.

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]	source	The az_span containing the ASCII digits to be parsed.
[out]	out_number	The pointer to the variable that is to receive the number.

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK	Success.
AZ_ERROR_UNEXPECTED_CHAR	A 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]	source	The az_span containing the ASCII digits to be parsed.
[out]	out_number	The pointer to the variable that is to receive the number.

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK	Success.
AZ_ERROR_UNEXPECTED_CHAR	A 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]	source	The az_span containing the ASCII digits to be parsed.
[out]	out_number	The pointer to the variable that is to receive the number.

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK	Success.
AZ_ERROR_UNEXPECTED_CHAR	A 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]	source	The az_span containing the ASCII digits to be parsed.
[out]	out_number	The pointer to the variable that is to receive the number.

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK	Success.
AZ_ERROR_UNEXPECTED_CHAR	A 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]	source	The az_span containing the ASCII digits to be parsed.
[out]	out_number	The pointer to the variable that is to receive the number.

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK	Success.
AZ_ERROR_UNEXPECTED_CHAR	A 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

	destination	The az_span whose bytes will be replaced by the bytes from `source`.
[in]	source	The 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

	destination	The az_span where the byte should be copied to.
[in]	byte	The `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]	ptr	The memory address of the first byte in the byte buffer.
[in]	size	The 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] str The 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

	destination	The az_span where the bytes should be copied to.
[in]	source	The `double` whose number is copied to the `destination` az_span as ASCII digits and characters.
[in]	fractional_digits	The number of digits to write into the `destination` az_span after the decimal point and truncate the rest.
[out]	out_span	A 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_OK	Success.
AZ_ERROR_NOT_ENOUGH_SPACE	The `destination` is not big enough to contain the copied bytes.
AZ_ERROR_NOT_SUPPORTED	The `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

	destination	The az_span whose bytes will be set to `value`.
[in]	value	The 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]	source	The az_span with the content to be searched on.
[in]	target	The 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

0	`target` is empty (if its size is equal zero).
-1	`target` is not found in `source` OR `source` is empty (if its size is zero) and `target` is non-empty.
>=0	The 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

	destination	The az_span where the bytes should be copied to.
[in]	source	The `int32_t` whose number is copied to the `destination` az_span as ASCII digits.
[out]	out_span	A 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_OK	Success.
AZ_ERROR_NOT_ENOUGH_SPACE	The `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

	destination	The az_span where the bytes should be copied to.
[in]	source	The `int64_t` whose number is copied to the `destination` az_span as ASCII digits.
[out]	out_span	A 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_OK	Success.
AZ_ERROR_NOT_ENOUGH_SPACE	The `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]	span1	The first az_span to compare.
[in]	span2	The 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]	span1	The first az_span to compare.
[in]	span2	The 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] span The 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] span The 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]	span	The original az_span.
[in]	start_index	An index into the original az_span indicating where the returned az_span will start.
[in]	end_index	An 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]	span	The original az_span.
[in]	start_index	An 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

	destination	A pointer to a buffer where the string should be copied into.
[in]	destination_max_size	The maximum available space within the buffer referred to by `destination`.
[in]	source	The 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

	destination	The az_span where the bytes should be copied to.
[in]	source	The `uint32_t` whose number is copied to the `destination` az_span as ASCII digits.
[out]	out_span	A 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_OK	Success.
AZ_ERROR_NOT_ENOUGH_SPACE	The `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

	destination	The az_span where the bytes should be copied to.
[in]	source	The `uint64_t` whose number is copied to the `destination` az_span as ASCII digits.
[out]	out_span	A 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_OK	Success.
AZ_ERROR_NOT_ENOUGH_SPACE	The `destination` is not big enough to contain the copied bytes.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ AZ_SPAN_EMPTY

◆ AZ_SPAN_FROM_BUFFER

◆ AZ_SPAN_FROM_STR

◆ AZ_SPAN_LITERAL_EMPTY

◆ AZ_SPAN_LITERAL_FROM_STR

Typedef Documentation

◆ az_span_allocator_fn

Function Documentation

◆ az_span_atod()

◆ az_span_atoi32()

◆ az_span_atoi64()

◆ az_span_atou32()

◆ az_span_atou64()

◆ az_span_copy()

◆ az_span_copy_u8()

◆ az_span_create()

◆ az_span_create_from_str()

◆ az_span_dtoa()

◆ az_span_fill()

◆ az_span_find()

◆ az_span_i32toa()

◆ az_span_i64toa()

◆ az_span_is_content_equal()

◆ az_span_is_content_equal_ignoring_case()

◆ az_span_ptr()

◆ az_span_size()

◆ az_span_slice()

◆ az_span_slice_to_end()

◆ az_span_to_str()

◆ az_span_u32toa()

◆ az_span_u64toa()