Gaia-ECS v1.0.0
A simple and powerful entity component system
Loading...
Searching...
No Matches
Classes | Public Member Functions | Static Public Member Functions | Static Public Attributes | Friends | List of all members
gaia::ecs::ComponentCursor Struct Reference

Stack-only cursor over raw component bytes and runtime field metadata. More...

#include <component_cursor.h>

Public Member Functions

GAIA_NODISCARD bool valid () const noexcept
 
GAIA_NODISCARD uint32_t depth () const noexcept
 
GAIA_NODISCARD Entity type () const noexcept
 
GAIA_NODISCARD RuntimeTypeKind type_kind () const noexcept
 Returns the runtime type kind at the current cursor scope.
 
GAIA_NODISCARD Entity opaque_as_type () const noexcept
 Returns the semantic runtime type exposed by the current opaque scope, or EntityBad otherwise.
 
GAIA_NODISCARD Entity element_type () const noexcept
 Returns the element type for the current sequence scope, or EntityBad otherwise.
 
GAIA_NODISCARD uint32_t size () const noexcept
 Returns the current payload or field size in bytes.
 
GAIA_NODISCARD const void * ptr () const noexcept
 
GAIA_NODISCARD void * mut_ptr () const noexcept
 
GAIA_NODISCARD uint32_t field_count () const
 
GAIA_NODISCARD CursorResult< uint32_t > count () const noexcept
 Returns the element count for the current fixed or adapted sequence scope.
 
bool field (uint32_t index)
 Descends into the reflected field at index.
 
bool field (util::str_view name)
 Descends into the reflected field named name.
 
bool elem (uint32_t index) noexcept
 Descends into element index of the current fixed inline or named array scope.
 
CursorResult< void > resize (uint32_t count) noexcept
 Resizes the current adapted dynamic sequence scope.
 
bool parent () noexcept
 Moves back to the parent cursor scope.
 
GAIA_NODISCARD CursorResult< bool > b () const noexcept
 Reads the current cursor value as a bool.
 
GAIA_NODISCARD CursorResult< void > b (bool value) noexcept
 Writes value to the current cursor value as a bool.
 
GAIA_NODISCARD CursorResult< char > c8 () const noexcept
 Reads the current cursor value as a scalar c8.
 
GAIA_NODISCARD CursorResult< void > c8 (char value) noexcept
 Writes value to the current cursor value as a scalar c8.
 
GAIA_NODISCARD CursorResult< uint32_t > c8 (char *dst, uint32_t cap) noexcept
 Reads the current fixed c8 buffer.
 
GAIA_NODISCARD CursorResult< uint32_t > c8 (char *dst, uint32_t cap) const noexcept
 Reads the current fixed c8 buffer.
 
GAIA_NODISCARD CursorResult< void > c8 (const char *src, uint32_t len) noexcept
 Writes bytes to the current fixed c8 buffer.
 
GAIA_NODISCARD CursorResult< char16_t > c16 () const noexcept
 Reads the current cursor value as a scalar c16.
 
GAIA_NODISCARD CursorResult< void > c16 (char16_t value) noexcept
 Writes value to the current cursor value as a scalar c16.
 
GAIA_NODISCARD CursorResult< char32_t > c32 () const noexcept
 Reads the current cursor value as a scalar c32.
 
GAIA_NODISCARD CursorResult< void > c32 (char32_t value) noexcept
 Writes value to the current cursor value as a scalar c32.
 
GAIA_NODISCARD CursorResult< int8_t > s8 () const noexcept
 Reads the current cursor value as an s8.
 
GAIA_NODISCARD CursorResult< void > s8 (int8_t value) noexcept
 Writes value to the current cursor value as an s8.
 
GAIA_NODISCARD CursorResult< uint8_t > u8 () const noexcept
 Reads the current cursor value as a u8.
 
GAIA_NODISCARD CursorResult< void > u8 (uint8_t value) noexcept
 Writes value to the current cursor value as a u8.
 
GAIA_NODISCARD CursorResult< int16_t > s16 () const noexcept
 Reads the current cursor value as an s16.
 
GAIA_NODISCARD CursorResult< void > s16 (int16_t value) noexcept
 Writes value to the current cursor value as an s16.
 
GAIA_NODISCARD CursorResult< uint16_t > u16 () const noexcept
 Reads the current cursor value as a u16.
 
GAIA_NODISCARD CursorResult< void > u16 (uint16_t value) noexcept
 Writes value to the current cursor value as a u16.
 
GAIA_NODISCARD CursorResult< int32_t > s32 () const noexcept
 Reads the current cursor value as an s32.
 
GAIA_NODISCARD CursorResult< void > s32 (int32_t value) noexcept
 Writes value to the current cursor value as an s32.
 
GAIA_NODISCARD CursorResult< uint32_t > u32 () const noexcept
 Reads the current cursor value as a u32.
 
GAIA_NODISCARD CursorResult< void > u32 (uint32_t value) noexcept
 Writes value to the current cursor value as a u32.
 
GAIA_NODISCARD CursorResult< int64_t > s64 () const noexcept
 Reads the current cursor value as an s64.
 
GAIA_NODISCARD CursorResult< void > s64 (int64_t value) noexcept
 Writes value to the current cursor value as an s64.
 
GAIA_NODISCARD CursorResult< uint64_t > u64 () const noexcept
 Reads the current cursor value as a u64.
 
GAIA_NODISCARD CursorResult< void > u64 (uint64_t value) noexcept
 Writes value to the current cursor value as a u64.
 
GAIA_NODISCARD CursorResult< float > f32 () const noexcept
 Reads the current cursor value as an f32.
 
GAIA_NODISCARD CursorResult< void > f32 (float value) noexcept
 Writes value to the current cursor value as an f32.
 
GAIA_NODISCARD CursorResult< double > f64 () const noexcept
 Reads the current cursor value as an f64.
 
GAIA_NODISCARD CursorResult< void > f64 (double value) noexcept
 Writes value to the current cursor value as an f64.
 
GAIA_NODISCARD CursorResult< uint32_t > get_raw (void *data, uint32_t byteCount) const noexcept
 Copies exact bytes from the current cursor position.
 
CursorResult< void > set_raw (const void *data, uint32_t byteCount) noexcept
 Writes exact bytes to the current cursor position.
 

Static Public Member Functions

static GAIA_NODISCARD ComponentCursor from_raw (const ComponentCache &components, Entity component, ComponentRawView view)
 Creates a read-only cursor from a raw component view.
 
static GAIA_NODISCARD ComponentCursor from_raw (World &world, const ComponentCache &components, Entity entity, Entity component, ComponentRawMutView view)
 Creates a mutable cursor from a raw component view.
 
static GAIA_NODISCARD ComponentCursor from_soa (const World &world, const ComponentCache &components, Entity entity, Entity component, uint32_t size)
 Creates a read-only cursor over a non-contiguous SoA component value.
 
static GAIA_NODISCARD ComponentCursor from_soa (World &world, const ComponentCache &components, Entity entity, Entity component, uint32_t size)
 Creates a mutable cursor over a non-contiguous SoA component value.
 

Static Public Attributes

static constexpr uint32_t MaxDepth = 32
 Maximum nested field depth tracked by the cursor.
 

Friends

class World
 

Detailed Description

Stack-only cursor over raw component bytes and runtime field metadata.

The cursor is a short-lived non-owning view. It never owns component bytes or metadata and is invalidated by structural changes that can move component storage. Field navigation is strict: missing fields, unsupported type metadata, and out-of-bounds field ranges leave the cursor unchanged.

Member Function Documentation

◆ b() [1/2]

GAIA_NODISCARD CursorResult< bool > gaia::ecs::ComponentCursor::b ( ) const
inlinenoexcept

Reads the current cursor value as a bool.

Returns
Read result and value.

◆ b() [2/2]

GAIA_NODISCARD CursorResult< void > gaia::ecs::ComponentCursor::b ( bool  value)
inlinenoexcept

Writes value to the current cursor value as a bool.

Parameters
valueValue to write.
Returns
Write result.

◆ c16() [1/2]

GAIA_NODISCARD CursorResult< char16_t > gaia::ecs::ComponentCursor::c16 ( ) const
inlinenoexcept

Reads the current cursor value as a scalar c16.

Returns
Read result and value.

◆ c16() [2/2]

GAIA_NODISCARD CursorResult< void > gaia::ecs::ComponentCursor::c16 ( char16_t  value)
inlinenoexcept

Writes value to the current cursor value as a scalar c16.

Parameters
valueValue to write.
Returns
Write result.

◆ c32() [1/2]

GAIA_NODISCARD CursorResult< char32_t > gaia::ecs::ComponentCursor::c32 ( ) const
inlinenoexcept

Reads the current cursor value as a scalar c32.

Returns
Read result and value.

◆ c32() [2/2]

GAIA_NODISCARD CursorResult< void > gaia::ecs::ComponentCursor::c32 ( char32_t  value)
inlinenoexcept

Writes value to the current cursor value as a scalar c32.

Parameters
valueValue to write.
Returns
Write result.

◆ c8() [1/5]

GAIA_NODISCARD CursorResult< char > gaia::ecs::ComponentCursor::c8 ( ) const
inlinenoexcept

Reads the current cursor value as a scalar c8.

Returns
Read result and value.

◆ c8() [2/5]

GAIA_NODISCARD CursorResult< uint32_t > gaia::ecs::ComponentCursor::c8 ( char *  dst,
uint32_t  cap 
) const
inlinenoexcept

Reads the current fixed c8 buffer.

Parameters
dstDestination buffer receiving bytes.
capDestination buffer size in bytes. Must be at least the reflected field count.
Returns
Read result and copied byte count.

◆ c8() [3/5]

GAIA_NODISCARD CursorResult< uint32_t > gaia::ecs::ComponentCursor::c8 ( char *  dst,
uint32_t  cap 
)
inlinenoexcept

Reads the current fixed c8 buffer.

Parameters
dstDestination buffer receiving bytes.
capDestination buffer size in bytes. Must be at least the reflected field count.
Returns
Read result and copied byte count.

◆ c8() [4/5]

GAIA_NODISCARD CursorResult< void > gaia::ecs::ComponentCursor::c8 ( char  value)
inlinenoexcept

Writes value to the current cursor value as a scalar c8.

Parameters
valueValue to write.
Returns
Write result.

◆ c8() [5/5]

GAIA_NODISCARD CursorResult< void > gaia::ecs::ComponentCursor::c8 ( const char *  src,
uint32_t  len 
)
inlinenoexcept

Writes bytes to the current fixed c8 buffer.

Parameters
srcSource bytes to copy.
lenSource byte count. Must fit in the reflected field count.
Returns
Write result.

◆ count()

GAIA_NODISCARD CursorResult< uint32_t > gaia::ecs::ComponentCursor::count ( ) const
inlinenoexcept

Returns the element count for the current fixed or adapted sequence scope.

Returns
Element count and read status.

◆ depth()

GAIA_NODISCARD uint32_t gaia::ecs::ComponentCursor::depth ( ) const
inlinenoexcept
Returns
Current nesting depth. Root payload is depth 0.

◆ elem()

bool gaia::ecs::ComponentCursor::elem ( uint32_t  index)
inlinenoexcept

Descends into element index of the current fixed inline or named array scope.

Parameters
indexElement index inside the current field.
Returns
True when the cursor moved to the element.

◆ element_type()

GAIA_NODISCARD Entity gaia::ecs::ComponentCursor::element_type ( ) const
inlinenoexcept

Returns the element type for the current sequence scope, or EntityBad otherwise.

Returns
Element type of the current sequence scope, or EntityBad.

◆ f32() [1/2]

GAIA_NODISCARD CursorResult< float > gaia::ecs::ComponentCursor::f32 ( ) const
inlinenoexcept

Reads the current cursor value as an f32.

Returns
Read result and value.

◆ f32() [2/2]

GAIA_NODISCARD CursorResult< void > gaia::ecs::ComponentCursor::f32 ( float  value)
inlinenoexcept

Writes value to the current cursor value as an f32.

Returns
Write result.

◆ f64() [1/2]

GAIA_NODISCARD CursorResult< double > gaia::ecs::ComponentCursor::f64 ( ) const
inlinenoexcept

Reads the current cursor value as an f64.

Returns
Read result and value.

◆ f64() [2/2]

GAIA_NODISCARD CursorResult< void > gaia::ecs::ComponentCursor::f64 ( double  value)
inlinenoexcept

Writes value to the current cursor value as an f64.

Returns
Write result.

◆ field() [1/2]

bool gaia::ecs::ComponentCursor::field ( uint32_t  index)
inline

Descends into the reflected field at index.

Parameters
indexReflected field index on the current type.
Returns
True when the cursor moved to the field.

◆ field() [2/2]

bool gaia::ecs::ComponentCursor::field ( util::str_view  name)
inline

Descends into the reflected field named name.

Parameters
nameReflected field name on the current type.
Returns
True when the cursor moved to the field.

◆ field_count()

GAIA_NODISCARD uint32_t gaia::ecs::ComponentCursor::field_count ( ) const
inline
Returns
Number of reflected fields on the current type.

◆ from_raw() [1/2]

static GAIA_NODISCARD ComponentCursor gaia::ecs::ComponentCursor::from_raw ( const ComponentCache &  components,
Entity  component,
ComponentRawView  view 
)
inlinestatic

Creates a read-only cursor from a raw component view.

Parameters
componentsComponent metadata registry used for field/type lookup.
componentComponent/type entity represented by view.
viewRaw component view returned by World::get_raw().
Returns
Cursor positioned at the root component payload, or invalid cursor when view is invalid.

◆ from_raw() [2/2]

static GAIA_NODISCARD ComponentCursor gaia::ecs::ComponentCursor::from_raw ( World &  world,
const ComponentCache &  components,
Entity  entity,
Entity  component,
ComponentRawMutView  view 
)
inlinestatic

Creates a mutable cursor from a raw component view.

Parameters
worldWorld owning the mutated chunk storage.
componentsComponent metadata registry used for field/type lookup.
entityEntity whose component payload is represented by view.
componentComponent/type entity represented by view.
viewRaw component view returned by World::mut_raw().
Returns
Cursor positioned at the root component payload, or invalid cursor when view is invalid.

◆ from_soa() [1/2]

static GAIA_NODISCARD ComponentCursor gaia::ecs::ComponentCursor::from_soa ( const World &  world,
const ComponentCache &  components,
Entity  entity,
Entity  component,
uint32_t  size 
)
inlinestatic

Creates a read-only cursor over a non-contiguous SoA component value.

Parameters
worldWorld owning the SoA storage.
componentsComponent metadata registry used for field/type lookup.
entityEntity owning the resolved component value.
componentComponent/type entity represented by the cursor.
sizeLogical AoS value size represented by the SoA fields.
Returns
Cursor positioned at the non-contiguous root component scope.

◆ from_soa() [2/2]

static GAIA_NODISCARD ComponentCursor gaia::ecs::ComponentCursor::from_soa ( World &  world,
const ComponentCache &  components,
Entity  entity,
Entity  component,
uint32_t  size 
)
inlinestatic

Creates a mutable cursor over a non-contiguous SoA component value.

Parameters
worldWorld owning the SoA storage.
componentsComponent metadata registry used for field/type lookup.
entityEntity owning the component value.
componentComponent/type entity represented by the cursor.
sizeLogical AoS value size represented by the SoA fields.
Returns
Cursor positioned at the non-contiguous writable root component scope.

◆ get_raw()

GAIA_NODISCARD CursorResult< uint32_t > gaia::ecs::ComponentCursor::get_raw ( void *  data,
uint32_t  byteCount 
) const
inlinenoexcept

Copies exact bytes from the current cursor position.

This is the cursor read path for runtime component data. It performs no type conversion and copies the whole current cursor scope. Use field navigation to choose the address being read.

Parameters
dataDestination bytes. Must be non-null when the current scope size is non-zero.
byteCountDestination capacity in bytes. Must be at least the current scope size.
Returns
Ok and copied byte count when bytes were copied, otherwise the reason the read failed.

◆ mut_ptr()

GAIA_NODISCARD void * gaia::ecs::ComponentCursor::mut_ptr ( ) const
inlinenoexcept
Returns
Mutable pointer at the current cursor position. Null for read-only cursors, tags, and invalid cursors.

◆ opaque_as_type()

GAIA_NODISCARD Entity gaia::ecs::ComponentCursor::opaque_as_type ( ) const
inlinenoexcept

Returns the semantic runtime type exposed by the current opaque scope, or EntityBad otherwise.

Returns
Semantic runtime type, or EntityBad when not in an opaque scope.

◆ parent()

bool gaia::ecs::ComponentCursor::parent ( )
inlinenoexcept

Moves back to the parent cursor scope.

Returns
True when the cursor moved to the parent. False at root or when invalid.

◆ ptr()

GAIA_NODISCARD const void * gaia::ecs::ComponentCursor::ptr ( ) const
inlinenoexcept
Returns
Read-only pointer at the current cursor position. Null for tags and invalid cursors.

◆ resize()

CursorResult< void > gaia::ecs::ComponentCursor::resize ( uint32_t  count)
inlinenoexcept

Resizes the current adapted dynamic sequence scope.

Returns
Resize status.

◆ s16() [1/2]

GAIA_NODISCARD CursorResult< int16_t > gaia::ecs::ComponentCursor::s16 ( ) const
inlinenoexcept

Reads the current cursor value as an s16.

Returns
Read result and value.

◆ s16() [2/2]

GAIA_NODISCARD CursorResult< void > gaia::ecs::ComponentCursor::s16 ( int16_t  value)
inlinenoexcept

Writes value to the current cursor value as an s16.

Returns
Write result.

◆ s32() [1/2]

GAIA_NODISCARD CursorResult< int32_t > gaia::ecs::ComponentCursor::s32 ( ) const
inlinenoexcept

Reads the current cursor value as an s32.

Returns
Read result and value.

◆ s32() [2/2]

GAIA_NODISCARD CursorResult< void > gaia::ecs::ComponentCursor::s32 ( int32_t  value)
inlinenoexcept

Writes value to the current cursor value as an s32.

Returns
Write result.

◆ s64() [1/2]

GAIA_NODISCARD CursorResult< int64_t > gaia::ecs::ComponentCursor::s64 ( ) const
inlinenoexcept

Reads the current cursor value as an s64.

Returns
Read result and value.

◆ s64() [2/2]

GAIA_NODISCARD CursorResult< void > gaia::ecs::ComponentCursor::s64 ( int64_t  value)
inlinenoexcept

Writes value to the current cursor value as an s64.

Returns
Write result.

◆ s8() [1/2]

GAIA_NODISCARD CursorResult< int8_t > gaia::ecs::ComponentCursor::s8 ( ) const
inlinenoexcept

Reads the current cursor value as an s8.

Returns
Read result and value.

◆ s8() [2/2]

GAIA_NODISCARD CursorResult< void > gaia::ecs::ComponentCursor::s8 ( int8_t  value)
inlinenoexcept

Writes value to the current cursor value as an s8.

Returns
Write result.

◆ set_raw()

CursorResult< void > gaia::ecs::ComponentCursor::set_raw ( const void *  data,
uint32_t  byteCount 
)
inlinenoexcept

Writes exact bytes to the current cursor position.

This is the cursor write path for runtime component data. It performs no type conversion and requires byteCount to match the current cursor scope size. Use field navigation to choose the address being written. Successful writes finish the root component write, so normal chunk write tracking and OnSet observers run.

Parameters
dataBytes to copy. Must be non-null when byteCount is non-zero.
byteCountNumber of bytes to copy.
Returns
Ok when bytes were copied, otherwise the reason the write failed.

◆ size()

GAIA_NODISCARD uint32_t gaia::ecs::ComponentCursor::size ( ) const
inlinenoexcept

Returns the current payload or field size in bytes.

Returns
Current payload or field size in bytes, or zero for an invalid cursor.

◆ type()

GAIA_NODISCARD Entity gaia::ecs::ComponentCursor::type ( ) const
inlinenoexcept
Returns
Current component/type entity, or EntityBad for an invalid cursor.

◆ type_kind()

GAIA_NODISCARD RuntimeTypeKind gaia::ecs::ComponentCursor::type_kind ( ) const
inlinenoexcept

Returns the runtime type kind at the current cursor scope.

Returns
Runtime type kind of the current scope, RuntimeTypeKind::None for invalid cursors.

◆ u16() [1/2]

GAIA_NODISCARD CursorResult< uint16_t > gaia::ecs::ComponentCursor::u16 ( ) const
inlinenoexcept

Reads the current cursor value as a u16.

Returns
Read result and value.

◆ u16() [2/2]

GAIA_NODISCARD CursorResult< void > gaia::ecs::ComponentCursor::u16 ( uint16_t  value)
inlinenoexcept

Writes value to the current cursor value as a u16.

Returns
Write result.

◆ u32() [1/2]

GAIA_NODISCARD CursorResult< uint32_t > gaia::ecs::ComponentCursor::u32 ( ) const
inlinenoexcept

Reads the current cursor value as a u32.

Returns
Read result and value.

◆ u32() [2/2]

GAIA_NODISCARD CursorResult< void > gaia::ecs::ComponentCursor::u32 ( uint32_t  value)
inlinenoexcept

Writes value to the current cursor value as a u32.

Returns
Write result.

◆ u64() [1/2]

GAIA_NODISCARD CursorResult< uint64_t > gaia::ecs::ComponentCursor::u64 ( ) const
inlinenoexcept

Reads the current cursor value as a u64.

Returns
Read result and value.

◆ u64() [2/2]

GAIA_NODISCARD CursorResult< void > gaia::ecs::ComponentCursor::u64 ( uint64_t  value)
inlinenoexcept

Writes value to the current cursor value as a u64.

Returns
Write result.

◆ u8() [1/2]

GAIA_NODISCARD CursorResult< uint8_t > gaia::ecs::ComponentCursor::u8 ( ) const
inlinenoexcept

Reads the current cursor value as a u8.

Returns
Read result and value.

◆ u8() [2/2]

GAIA_NODISCARD CursorResult< void > gaia::ecs::ComponentCursor::u8 ( uint8_t  value)
inlinenoexcept

Writes value to the current cursor value as a u8.

Returns
Write result.

◆ valid()

GAIA_NODISCARD bool gaia::ecs::ComponentCursor::valid ( ) const
inlinenoexcept
Returns
True when the cursor points at a valid component payload, tag, or field.
The documentation for this struct was generated from the following file: