c_span
ο
c_span
is a type that is generated by defining the macro ZTD_IDK_C_SPAN_TYPE
to a specific type name and including the header #include <ztd/idk/c_span.g.h>
. Occasionally, some types include spaces or similar, and therefore need some additional tweaking in order to handle it all properly. This comes up to forming 3 different macros which can help control configuration:
ZTD_IDK_C_SPAN_TYPE
, the type;ZTD_IDK_C_SPAN_TYPE_IS_CONST
, an optional definition that, if defined, must be either 1 or 0. If 1, it indicates that the stored pointer should be to a const T type;ZTD_IDK_C_SPAN_TYPE_NAME
, an optional name of the type if it should not be derived directly from the type itself (defaults toZTD_ID_C_SPAN_TYPE
);ZTD_IDK_C_SPAN_SIZE_TYPE
, an optional type name used to control the type for the storage of thesize
(defaults tosize_t
).ZTD_IDK_C_SPAN_SIZE_TYPE_NAME
, an optional suffix for thec_span
βs name to override the default which is generated from the type (defaults toZTD_ID_C_SPAN_SIZE_TYPE
); and,ZTD_IDK_C_SPAN_NAME
, an optional override for the entire name of the structure and its functions (ignores all previous name-based derivations).ZTD_IDK_C_SPAN_SIZE_FIRST
, an optional definition that, if defined, must be either 1 or 0. If 1, it indicates that the size member should go first.
The final name is composed of either just the type name suffixed on c_span
; the type name and the size type name (if defined) suffixed onto c_span
; or, the the full name provided in the override.
Important
Any macros that are consumed by this header are undefined by the end of the header, including the ones listed above.
The <ztd/idk/c_span.h>
header includes some common definitions of a c_span
to be used, most notably c_span_uchar
. The documentation below is for c_span_uchar
, but works for all entities.
Note
ztd_generic_type
is a name used as a placeholder. When it appears as a name (or within a name) or a type, it can be substituted out for another type name!
Structure + Functionsο
-
void copy_c_span(c_span *__destination, c_span __source)ο
Copies on c_span into the memory of another.
Remark
- Preconditions:
__destination != NULL
- Parameters
__destination β [in] Pointer to the destination.
__source β [in] The source span to copy.
-
c_span make_c_span(ztd_generic_type *__first, ztd_generic_type *__last)ο
Create a c_span from two pointers which denote a region of memory.
Remark
- Preconditions:
__first
<__last
(__first
is reachable from__last
).__first
and__last
are part of the same storage and form a valid range.
- Parameters
__first β [in] The start of the region of memory, inclusive.
__last β [in] The end of the region of memory, non-inclusive.
-
c_span make_sized_c_span(ztd_generic_type *__first, size_t __size)ο
Create a c_span from two pointers which denote a region of memory.
Remark
- Preconditions:
__first
and__first + __size
are part of the same storage and form a valid range.
- Parameters
__first β [in] The start of the region of memory, inclusive.
__size β [in] The number of elements of the region of memory.
-
ztd_generic_type *c_span_data(c_span __span)ο
Retrieves a pointer to the start of this span of memory.
- Parameters
__span β [in] The βselfβ object.
-
size_t c_span_size(c_span __span)ο
Retrieves the size of this span of memory, in number of elements.
- Parameters
__span β [in] The βselfβ object.
-
bool c_span_empty(c_span __span)ο
Returns whether or not this span is empty.
- Parameters
__span β [in] The βselfβ object.
-
ztd_generic_type c_span_front(c_span __span)ο
Retrieves the first element of this span of elements.
Remark
Preconditions:
__span.size > 0
.
- Parameters
__span β [in] The βselfβ object.
-
ztd_generic_type c_span_back(c_span __span)ο
Retrieves the last element of this span of elements.
Remark
Preconditions:
__span.size > 0
.
-
ztd_generic_type c_span_at(c_span __span, size_t __index)ο
Retrieves the the element at the provided index.
Remark
Preconditions:
__span.size > __index
.
- Parameters
__span β [in] The βselfβ object.
__index β [in] The offset into the span of elements to access.
-
void c_span_set(c_span __span, size_t __index, ztd_generic_type __value)ο
Retrieves the the element at the provided index.
Remark
Preconditions:
__span.size > __index
.
- Parameters
__span β [in] The βselfβ object.
__index β [in] The offset into the span of elements to access.
__value β [in] The value to insert.
-
ztd_generic_type *c_span_ptr_at(c_span __span, size_t __index)ο
Retrieves the the element at the provided index.
Remark
Preconditions:
__span.size > __index
.
- Parameters
__span β [in] The βselfβ object.
__index β [in] The offset into the span of elements to access.
-
ztd_generic_type *c_span_maybe_ptr_at(c_span __span, size_t __index)ο
Retrieves the the element at the provided index.
Remark
This function checks size so there are no preconditions.
- Parameters
__span β [in] The βselfβ object.
__index β [in] The offset into the span of elements to access.
-
size_t c_span_byte_size(c_span __span)ο
Retrieves the size of this span of memory, in number of
unsigned char
s.- Parameters
__span β [in] The βselfβ object.
-
c_span c_span_begin(c_span __span)ο
An iterator to the beginning of the span of elements.
- Parameters
__span β [in] The βselfβ object.
-
ztd_generic_type *c_span_end(c_span __span)ο
An iterator to the end of the span of elements.
- Parameters
__span β [in] The βselfβ object.
-
c_span c_span_subspan(c_span __span, size_t __offset_index, size_t __size)ο
Creates a smaller span from this span, using the given offset into the span and the desired size.
Remark
- Preconditions:
__span.size >= (__offset_index + __size)
.
- Parameters
__span β [in] The βselfβ object.
__offset_index β [in] The offset into the span.
__size β [in] The size of the resulting span.
-
c_span c_span_subspan_at(c_span __span, size_t __offset_index)ο
Creates a smaller span from this span, from the given offset. The resulting size is the offset minus the
__span
βs current size.Remark
- Preconditions:
__span.size >= __offset_index
.
- Parameters
__span β [in] The βselfβ object.
__offset_index β [in] The offset into the span.
-
c_span c_span_subspan_prefix(c_span __span, size_t __size)ο
Creates a smaller span from this span, from the given size. The resulting offset is from 0 and has the given size.
Remark
- Preconditions:
__span.size >= __size
.
- Parameters
__span β [in] The βselfβ object.
__size β [in] The size of the span, from the beginning.
-
c_span c_span_subspan_suffix(c_span __span, size_t __size)ο
Creates a smaller span from this span, from the given size.
Remark
The resulting offset is from the current spanβs size minus the desired size, and has the given
__size
.- Preconditions:
__span.size >= __size
.
- Parameters
__span β [in] The βselfβ object.
__size β [in] The size of the span, from the beginning.
-
struct c_spanο
- #include <c_span.h>
A structured pointer which keeps its size type, which represents a non-owning view into a buffer.
This type can be initialized with designated initializers.
Remark
This type is meant to be βimmutableβ, which is why the members are marked const. This can present some issues when dealing with, for example, trying to fill out members manually in structures that are heap-allocated. Instead, copy it using
memcpy
, likememcpy(my_span_ptr, &some_span, sizeof(some_span));
rather thanmy_span_ptr->data = some_ptr; my_span_ptr->size = some_size;
.
Definesο
-
ZTD_IDK_C_SPAN_TYPEο
The type used to create a new c_span type.
Remark
This definition is required. If a type is not provided and the generation header is included, then an error will be produced.
-
ZTD_IDK_C_SPAN_TYPE_NAMEο
The name to use when generating the function and structure names.
Remark
This definition is optional. The default is whatever ZTD_IDK_C_SPAN_TYPE is. However, that may be bad since sometimes type names can have spaces in them (such as
unsigned char
). Therefore, one can se names to make it all better, likeuchar
to representunsigned char
.
-
ZTD_IDK_C_SPAN_SIZE_TYPEο
The size type used to create a new c_span type.
Remark
This definition is optional. The default is
size_t
. In certain cases, a more compact size type may be beneficial than the original size_type. Some may also want to provide a signed type rather than an unsigned type. Note that contract checks will still check for things such as> 0
or< size
, even if what is provided is a signed size type (span will not allow negative indexing, where viable).
-
ZTD_IDK_C_SPAN_SIZE_TYPE_NAMEο
The name to use when generating the function and structure names.
Remark
This definition is optional. Normally, it would be defaulted to whatever ZTD_IDK_C_SPAN_SIZE_TYPE is. However, that may be bad since sometimes type names can have spaces in them (such as
long long
). Therefore, one can se names to make it all better, likeuchar
to representunsigned char
.
-
ZTD_IDK_C_SPAN_NAMEο
The whole name of the generated type.
Remark
This definition is optional. When not provided, a sequence of checks are gone through to define a hopefully unique name for the newly generated c_span. The first generated attempt is just using
c_span{type name}{size type}
, where the size type is only used if ZTD_IDK_C_SPAN_SIZE_TYPE is also defined by you. Otherwise, it defaults to justc_span{type name}
(without the brackets and with the names substituted in).
-
ZTD_IDK_C_SPAN_SIZE_FIRSTο
Whether or not the size type comes before the pointer.
Remark
This definition is optional. When not provided, the default layout is
{ pointer_type , size_type }
. If this is defined and its value is 1, the layout is{ size_type, pointer_type }
. This can aid when generating certain types that are meant to be compatible with other kinds of buffers, e.g. with POSIXβsiovec
.