introduce FieldIndex::new + rename ecs_field_* to flecs_field

flecs_ecs/src/core/components/component.rs

@@ -286,7 +286,7 @@ impl<'a, T> Component<'a, T> {
             let on_add = &mut *on_add;
             let world = WorldRef::from_ptr(iter.world);
             let entity = EntityView::new_from(world, *iter.entities);
-            let component: *mut T = ecs_field::<T>(iter, 0);
+            let component: *mut T = flecs_field::<T>(iter, 0);
             on_add(entity, &mut *component);
         }
     }
@@ -303,7 +303,7 @@ impl<'a, T> Component<'a, T> {
         let on_set = unsafe { &mut *on_set };
         let world = unsafe { WorldRef::from_ptr(iter.world) };
         let entity = EntityView::new_from(world, unsafe { *iter.entities });
-        let component: *mut T = ecs_field::<T>(iter, 0);
+        let component: *mut T = flecs_field::<T>(iter, 0);
         on_set(entity, unsafe { &mut *component });
     }
 
@@ -320,7 +320,7 @@ impl<'a, T> Component<'a, T> {
             let on_remove = &mut *on_remove;
             let world = WorldRef::from_ptr(iter.world);
             let entity = EntityView::new_from(world, *iter.entities);
-            let component: *mut T = ecs_field::<T>(iter, 0);
+            let component: *mut T = flecs_field::<T>(iter, 0);
             on_remove(entity, &mut *component);
         }
     }

flecs_ecs/src/core/query_tuple.rs

@@ -395,12 +395,12 @@ where
         indexes: &mut [i8],
     ) -> IsAnyArray {
         if it.row_fields & (1u32 << 0) != 0 {
-            // Need to fetch the value with ecs_field_at()
+            // Need to fetch the value with flecs_field_at()
             is_ref[0] = true;
             is_row[0] = true;
             indexes[0] = 0;
         } else {
-            components[0] = ecs_field::<A::OnlyPairType>(it, 0) as *mut u8 ;
+            components[0] = flecs_field::<A::OnlyPairType>(it, 0) as *mut u8 ;
             is_ref[0] = unsafe { *it.sources.add(0) != 0 };
         };
         IsAnyArray {
@@ -415,7 +415,7 @@ where
         components: &mut [*mut u8],
     ) {
         ecs_assert!(unsafe { *it.sources.add(0) == 0 }, FlecsErrorCode::InternalError, "unexpected source");
-        components[0] = ecs_field::<A::OnlyPairType>(it, 0) as *mut u8 ;
+        components[0] = flecs_field::<A::OnlyPairType>(it, 0) as *mut u8 ;
     }
 
     #[inline(always)]
@@ -447,7 +447,7 @@ where
 
         if is_row_array_components[0] {
             let ptr_to_first_index_array = &mut array_components[0];
-            *ptr_to_first_index_array = unsafe { ecs_field_at::<A::OnlyPairType>(iter, indexes_array_components[0], index_row_entity as i32) } as *mut u8;
+            *ptr_to_first_index_array = unsafe { flecs_field_at::<A::OnlyPairType>(iter, indexes_array_components[0], index_row_entity as i32) } as *mut u8;
         }
 
         A::create_tuple_with_ref_data(
@@ -586,13 +586,13 @@ macro_rules! impl_iterable {
                 let mut any_row = false;
                 $(
                     if (it.row_fields & (1u32 << index)) != 0 {
-                        // Need to fetch the value with ecs_field_at()
+                        // Need to fetch the value with flecs_field_at()
                         is_ref[index ] =  true;
                         is_row[index ] = true;
                         indexes[index ] = index as i8;
                     } else {
                         components[index ] =
-                            ecs_field::<$t::OnlyPairType>(it, index as i8) as *mut u8;
+                            flecs_field::<$t::OnlyPairType>(it, index as i8) as *mut u8;
                         is_ref[index ] = unsafe { *it.sources.add(index ) != 0 };
                     }
                     any_ref |= is_ref[index ];
@@ -615,7 +615,7 @@ macro_rules! impl_iterable {
                 $(
                     ecs_assert!(unsafe { *it.sources.add(index ) == 0 }, FlecsErrorCode::InternalError, "unexpected source");
                     components[index] =
-                        ecs_field::<$t::OnlyPairType>(it, index as i8) as *mut u8;
+                        flecs_field::<$t::OnlyPairType>(it, index as i8) as *mut u8;
                     index += 1;
                 )*
 
@@ -662,7 +662,7 @@ macro_rules! impl_iterable {
                     if is_row {
                         let ptr_to_first_index_array = unsafe { &mut *array_components.get_unchecked_mut(column) };
                         let index_array_component = unsafe { *indexes_array_components.get_unchecked(column) };
-                        *ptr_to_first_index_array = unsafe { ecs_field_at::<$t::OnlyPairType>(iter, index_array_component, index_row_entity as i32) } as *mut $t::OnlyPairType as *mut u8;
+                        *ptr_to_first_index_array = unsafe { flecs_field_at::<$t::OnlyPairType>(iter, index_array_component, index_row_entity as i32) } as *mut $t::OnlyPairType as *mut u8;
                     }
                     let data_ptr = unsafe { *array_components.get_unchecked(column) };
                     let is_ref = unsafe { *is_ref_array_components.get_unchecked(column) };

flecs_ecs/src/core/table/field.rs

@@ -12,6 +12,20 @@ use core::ops::IndexMut;
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct FieldIndex(pub(crate) usize);
 
+impl FieldIndex {
+    /// Constructs a new `FieldIndex` from a `usize` value.
+    ///
+    /// This is useful when you need a more efficient indexing mechanism for fields than usize as it avoids unnecessary bounds checks.
+    ///
+    /// # Safety
+    /// The caller must ensure that `value` is a valid field index.
+    /// This function does *not* perform any bounds or validity checks.
+    #[inline(always)]
+    pub unsafe fn new(value: usize) -> Self {
+        Self(value)
+    }
+}
+
 impl From<usize> for FieldIndex {
     #[inline(always)]
     fn from(value: usize) -> Self {
@@ -57,7 +71,7 @@ impl<'a, T> Index<FieldIndex> for Field<'a, T> {
 
     #[inline(always)]
     fn index(&self, idx: FieldIndex) -> &'a Self::Output {
-        // Safety: This index can only be obtained from `it.iter`
+        // Safety: This index can only be obtained from `it.iter` or unsafe FieldIndex::new
         ecs_assert!(
             !(self.is_shared && idx.0 > 0),
             FlecsErrorCode::InvalidParameter,
@@ -118,7 +132,7 @@ impl<'a, T> Index<FieldIndex> for FieldMut<'a, T> {
 
     #[inline(always)]
     fn index(&self, idx: FieldIndex) -> &T {
-        // Safety: This index can only be obtained from `it.iter`
+        // Safety: This index can only be obtained from `it.iter` or unsafe FieldIndex::new
         ecs_assert!(
             !(self.is_shared && idx.0 > 0),
             FlecsErrorCode::InvalidParameter,
@@ -325,7 +339,7 @@ impl FieldUntypedMut {
 /// let velocity_ptr: *mut Velocity = ecs_field(it, 1);
 /// ```
 #[inline(always)]
-pub fn ecs_field<T>(it: &sys::ecs_iter_t, index: i8) -> *mut T {
+pub(crate) fn flecs_field<T>(it: &sys::ecs_iter_t, index: i8) -> *mut T {
     let _size = const { core::mem::size_of::<T>() };
 
     const {
@@ -394,7 +408,6 @@ pub fn ecs_field<T>(it: &sys::ecs_iter_t, index: i8) -> *mut T {
     p as *mut T
 }
 
-#[cold]
 #[inline(never)]
 fn ecs_field_fallback<T>(it: &sys::ecs_iter_t, index: i8) -> *mut T {
     let index_usize = index as usize;
@@ -472,9 +485,7 @@ fn ecs_field_fallback<T>(it: &sys::ecs_iter_t, index: i8) -> *mut T {
     unsafe { sys::ecs_table_get_column(table, column_index as i32, row as i32) as *mut T }
 }
 
-#[inline(never)]
-#[unsafe(no_mangle)]
-pub fn ecs_field_w_size(it: &sys::ecs_iter_t, _size: usize, index: i8) -> *mut c_void {
+pub(crate) fn flecs_field_w_size(it: &sys::ecs_iter_t, _size: usize, index: i8) -> *mut c_void {
     let index_usize = index as usize;
     //TODO should be soft asserts
     ecs_assert!(

flecs_ecs/src/core/table/iter.rs

@@ -853,7 +853,7 @@ where
             self.count()
         };
 
-        let array = ecs_field::<T>(self.iter, index);
+        let array = flecs_field::<T>(self.iter, index);
 
         (array, is_shared, count)
     }
@@ -873,7 +873,7 @@ where
             self.count()
         };
 
-        let array = ecs_field_w_size(self.iter, size, index);
+        let array = flecs_field_w_size(self.iter, size, index);
 
         (array, is_shared, count, size)
     }

flecs_ecs/src/core/table/mod.rs

@@ -5,7 +5,9 @@ mod flags;
 mod iter;
 
 use core::{ffi::CStr, ffi::c_void, ptr::NonNull};
-pub use field::{Field, FieldIndex, FieldUntyped, ecs_field, ecs_field_w_size};
+pub use field::{Field, FieldIndex, FieldUntyped};
+pub(crate) use field::{flecs_field, flecs_field_w_size};
+
 pub use flags::TableFlags;
 pub use iter::TableIter;
 pub(crate) use iter::{table_lock, table_unlock};

flecs_ecs/src/core/utility/functions.rs

@@ -378,7 +378,7 @@ pub fn get_generation(entity: impl Into<Entity>) -> u32 {
 }
 
 #[inline(always)]
-pub(crate) unsafe fn ecs_field_at<T>(it: *const sys::ecs_iter_t, index: i8, row: i32) -> *mut T {
+pub(crate) unsafe fn flecs_field_at<T>(it: *const sys::ecs_iter_t, index: i8, row: i32) -> *mut T {
     unsafe {
         let size = core::mem::size_of::<T>();
         sys::ecs_field_at_w_size(it, size, index, row) as *mut T