bevy_reflect/
list.rs

1use std::any::{Any, TypeId};
2use std::fmt::{Debug, Formatter};
3use std::hash::{Hash, Hasher};
4
5use bevy_reflect_derive::impl_type_path;
6
7use crate::utility::reflect_hasher;
8use crate::{
9    self as bevy_reflect, ApplyError, FromReflect, Reflect, ReflectKind, ReflectMut, ReflectOwned,
10    ReflectRef, TypeInfo, TypePath, TypePathTable,
11};
12
13/// A trait used to power [list-like] operations via [reflection].
14///
15/// This corresponds to types, like [`Vec`], which contain an ordered sequence
16/// of elements that implement [`Reflect`].
17///
18/// Unlike the [`Array`](crate::Array) trait, implementors of this trait are not expected to
19/// maintain a constant length.
20/// Methods like [insertion](List::insert) and [removal](List::remove) explicitly allow for their
21/// internal size to change.
22///
23/// [`push`](List::push) and [`pop`](List::pop) have default implementations,
24/// however it will generally be more performant to implement them manually
25/// as the default implementation uses a very naive approach to find the correct position.
26///
27/// This trait expects its elements to be ordered linearly from front to back.
28/// The _front_ element starts at index 0 with the _back_ element ending at the largest index.
29/// This contract above should be upheld by any manual implementors.
30///
31/// Due to the [type-erasing] nature of the reflection API as a whole,
32/// this trait does not make any guarantees that the implementor's elements
33/// are homogeneous (i.e. all the same type).
34///
35/// # Example
36///
37/// ```
38/// use bevy_reflect::{Reflect, List};
39///
40/// let foo: &mut dyn List = &mut vec![123_u32, 456_u32, 789_u32];
41/// assert_eq!(foo.len(), 3);
42///
43/// let last_field: Box<dyn Reflect> = foo.pop().unwrap();
44/// assert_eq!(last_field.downcast_ref::<u32>(), Some(&789));
45/// ```
46///
47/// [list-like]: https://doc.rust-lang.org/book/ch08-01-vectors.html
48/// [reflection]: crate
49/// [type-erasing]: https://doc.rust-lang.org/book/ch17-02-trait-objects.html
50pub trait List: Reflect {
51    /// Returns a reference to the element at `index`, or `None` if out of bounds.
52    fn get(&self, index: usize) -> Option<&dyn Reflect>;
53
54    /// Returns a mutable reference to the element at `index`, or `None` if out of bounds.
55    fn get_mut(&mut self, index: usize) -> Option<&mut dyn Reflect>;
56
57    /// Inserts an element at position `index` within the list,
58    /// shifting all elements after it towards the back of the list.
59    ///
60    /// # Panics
61    /// Panics if `index > len`.
62    fn insert(&mut self, index: usize, element: Box<dyn Reflect>);
63
64    /// Removes and returns the element at position `index` within the list,
65    /// shifting all elements before it towards the front of the list.
66    ///
67    /// # Panics
68    /// Panics if `index` is out of bounds.
69    fn remove(&mut self, index: usize) -> Box<dyn Reflect>;
70
71    /// Appends an element to the _back_ of the list.
72    fn push(&mut self, value: Box<dyn Reflect>) {
73        self.insert(self.len(), value);
74    }
75
76    /// Removes the _back_ element from the list and returns it, or [`None`] if it is empty.
77    fn pop(&mut self) -> Option<Box<dyn Reflect>> {
78        if self.is_empty() {
79            None
80        } else {
81            Some(self.remove(self.len() - 1))
82        }
83    }
84
85    /// Returns the number of elements in the list.
86    fn len(&self) -> usize;
87
88    /// Returns `true` if the collection contains no elements.
89    fn is_empty(&self) -> bool {
90        self.len() == 0
91    }
92
93    /// Returns an iterator over the list.
94    fn iter(&self) -> ListIter;
95
96    /// Drain the elements of this list to get a vector of owned values.
97    fn drain(self: Box<Self>) -> Vec<Box<dyn Reflect>>;
98
99    /// Clones the list, producing a [`DynamicList`].
100    fn clone_dynamic(&self) -> DynamicList {
101        DynamicList {
102            represented_type: self.get_represented_type_info(),
103            values: self.iter().map(|value| value.clone_value()).collect(),
104        }
105    }
106}
107
108/// A container for compile-time list info.
109#[derive(Clone, Debug)]
110pub struct ListInfo {
111    type_path: TypePathTable,
112    type_id: TypeId,
113    item_type_path: TypePathTable,
114    item_type_id: TypeId,
115    #[cfg(feature = "documentation")]
116    docs: Option<&'static str>,
117}
118
119impl ListInfo {
120    /// Create a new [`ListInfo`].
121    pub fn new<TList: List + TypePath, TItem: FromReflect + TypePath>() -> Self {
122        Self {
123            type_path: TypePathTable::of::<TList>(),
124            type_id: TypeId::of::<TList>(),
125            item_type_path: TypePathTable::of::<TItem>(),
126            item_type_id: TypeId::of::<TItem>(),
127            #[cfg(feature = "documentation")]
128            docs: None,
129        }
130    }
131
132    /// Sets the docstring for this list.
133    #[cfg(feature = "documentation")]
134    pub fn with_docs(self, docs: Option<&'static str>) -> Self {
135        Self { docs, ..self }
136    }
137
138    /// A representation of the type path of the list.
139    ///
140    /// Provides dynamic access to all methods on [`TypePath`].
141    pub fn type_path_table(&self) -> &TypePathTable {
142        &self.type_path
143    }
144
145    /// The [stable, full type path] of the list.
146    ///
147    /// Use [`type_path_table`] if you need access to the other methods on [`TypePath`].
148    ///
149    /// [stable, full type path]: TypePath
150    /// [`type_path_table`]: Self::type_path_table
151    pub fn type_path(&self) -> &'static str {
152        self.type_path_table().path()
153    }
154
155    /// The [`TypeId`] of the list.
156    pub fn type_id(&self) -> TypeId {
157        self.type_id
158    }
159
160    /// Check if the given type matches the list type.
161    pub fn is<T: Any>(&self) -> bool {
162        TypeId::of::<T>() == self.type_id
163    }
164
165    /// A representation of the type path of the list item.
166    ///
167    /// Provides dynamic access to all methods on [`TypePath`].
168    pub fn item_type_path_table(&self) -> &TypePathTable {
169        &self.item_type_path
170    }
171
172    /// The [`TypeId`] of the list item.
173    pub fn item_type_id(&self) -> TypeId {
174        self.item_type_id
175    }
176
177    /// Check if the given type matches the list item type.
178    pub fn item_is<T: Any>(&self) -> bool {
179        TypeId::of::<T>() == self.item_type_id
180    }
181
182    /// The docstring of this list, if any.
183    #[cfg(feature = "documentation")]
184    pub fn docs(&self) -> Option<&'static str> {
185        self.docs
186    }
187}
188
189/// A list of reflected values.
190#[derive(Default)]
191pub struct DynamicList {
192    represented_type: Option<&'static TypeInfo>,
193    values: Vec<Box<dyn Reflect>>,
194}
195
196impl DynamicList {
197    /// Sets the [type] to be represented by this `DynamicList`.
198    /// # Panics
199    ///
200    /// Panics if the given [type] is not a [`TypeInfo::List`].
201    ///
202    /// [type]: TypeInfo
203    pub fn set_represented_type(&mut self, represented_type: Option<&'static TypeInfo>) {
204        if let Some(represented_type) = represented_type {
205            assert!(
206                matches!(represented_type, TypeInfo::List(_)),
207                "expected TypeInfo::List but received: {:?}",
208                represented_type
209            );
210        }
211
212        self.represented_type = represented_type;
213    }
214
215    /// Appends a typed value to the list.
216    pub fn push<T: Reflect>(&mut self, value: T) {
217        self.values.push(Box::new(value));
218    }
219
220    /// Appends a [`Reflect`] trait object to the list.
221    pub fn push_box(&mut self, value: Box<dyn Reflect>) {
222        self.values.push(value);
223    }
224}
225
226impl List for DynamicList {
227    fn get(&self, index: usize) -> Option<&dyn Reflect> {
228        self.values.get(index).map(|value| &**value)
229    }
230
231    fn get_mut(&mut self, index: usize) -> Option<&mut dyn Reflect> {
232        self.values.get_mut(index).map(|value| &mut **value)
233    }
234
235    fn insert(&mut self, index: usize, element: Box<dyn Reflect>) {
236        self.values.insert(index, element);
237    }
238
239    fn remove(&mut self, index: usize) -> Box<dyn Reflect> {
240        self.values.remove(index)
241    }
242
243    fn push(&mut self, value: Box<dyn Reflect>) {
244        DynamicList::push_box(self, value);
245    }
246
247    fn pop(&mut self) -> Option<Box<dyn Reflect>> {
248        self.values.pop()
249    }
250
251    fn len(&self) -> usize {
252        self.values.len()
253    }
254
255    fn iter(&self) -> ListIter {
256        ListIter::new(self)
257    }
258
259    fn drain(self: Box<Self>) -> Vec<Box<dyn Reflect>> {
260        self.values
261    }
262
263    fn clone_dynamic(&self) -> DynamicList {
264        DynamicList {
265            represented_type: self.represented_type,
266            values: self
267                .values
268                .iter()
269                .map(|value| value.clone_value())
270                .collect(),
271        }
272    }
273}
274
275impl Reflect for DynamicList {
276    #[inline]
277    fn get_represented_type_info(&self) -> Option<&'static TypeInfo> {
278        self.represented_type
279    }
280
281    #[inline]
282    fn into_any(self: Box<Self>) -> Box<dyn Any> {
283        self
284    }
285
286    #[inline]
287    fn as_any(&self) -> &dyn Any {
288        self
289    }
290
291    #[inline]
292    fn as_any_mut(&mut self) -> &mut dyn Any {
293        self
294    }
295
296    #[inline]
297    fn into_reflect(self: Box<Self>) -> Box<dyn Reflect> {
298        self
299    }
300
301    #[inline]
302    fn as_reflect(&self) -> &dyn Reflect {
303        self
304    }
305
306    #[inline]
307    fn as_reflect_mut(&mut self) -> &mut dyn Reflect {
308        self
309    }
310
311    fn apply(&mut self, value: &dyn Reflect) {
312        list_apply(self, value);
313    }
314
315    fn try_apply(&mut self, value: &dyn Reflect) -> Result<(), ApplyError> {
316        list_try_apply(self, value)
317    }
318
319    #[inline]
320    fn set(&mut self, value: Box<dyn Reflect>) -> Result<(), Box<dyn Reflect>> {
321        *self = value.take()?;
322        Ok(())
323    }
324
325    #[inline]
326    fn reflect_kind(&self) -> ReflectKind {
327        ReflectKind::List
328    }
329
330    #[inline]
331    fn reflect_ref(&self) -> ReflectRef {
332        ReflectRef::List(self)
333    }
334
335    #[inline]
336    fn reflect_mut(&mut self) -> ReflectMut {
337        ReflectMut::List(self)
338    }
339
340    #[inline]
341    fn reflect_owned(self: Box<Self>) -> ReflectOwned {
342        ReflectOwned::List(self)
343    }
344
345    #[inline]
346    fn clone_value(&self) -> Box<dyn Reflect> {
347        Box::new(self.clone_dynamic())
348    }
349
350    #[inline]
351    fn reflect_hash(&self) -> Option<u64> {
352        list_hash(self)
353    }
354
355    fn reflect_partial_eq(&self, value: &dyn Reflect) -> Option<bool> {
356        list_partial_eq(self, value)
357    }
358
359    fn debug(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
360        write!(f, "DynamicList(")?;
361        list_debug(self, f)?;
362        write!(f, ")")
363    }
364
365    #[inline]
366    fn is_dynamic(&self) -> bool {
367        true
368    }
369}
370
371impl_type_path!((in bevy_reflect) DynamicList);
372
373impl Debug for DynamicList {
374    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
375        self.debug(f)
376    }
377}
378
379impl IntoIterator for DynamicList {
380    type Item = Box<dyn Reflect>;
381    type IntoIter = std::vec::IntoIter<Self::Item>;
382
383    fn into_iter(self) -> Self::IntoIter {
384        self.values.into_iter()
385    }
386}
387
388/// An iterator over an [`List`].
389pub struct ListIter<'a> {
390    list: &'a dyn List,
391    index: usize,
392}
393
394impl<'a> ListIter<'a> {
395    /// Creates a new [`ListIter`].
396    #[inline]
397    pub const fn new(list: &'a dyn List) -> ListIter {
398        ListIter { list, index: 0 }
399    }
400}
401
402impl<'a> Iterator for ListIter<'a> {
403    type Item = &'a dyn Reflect;
404
405    #[inline]
406    fn next(&mut self) -> Option<Self::Item> {
407        let value = self.list.get(self.index);
408        self.index += value.is_some() as usize;
409        value
410    }
411
412    #[inline]
413    fn size_hint(&self) -> (usize, Option<usize>) {
414        let size = self.list.len();
415        (size, Some(size))
416    }
417}
418
419impl<'a> ExactSizeIterator for ListIter<'a> {}
420
421/// Returns the `u64` hash of the given [list](List).
422#[inline]
423pub fn list_hash<L: List>(list: &L) -> Option<u64> {
424    let mut hasher = reflect_hasher();
425    Any::type_id(list).hash(&mut hasher);
426    list.len().hash(&mut hasher);
427    for value in list.iter() {
428        hasher.write_u64(value.reflect_hash()?);
429    }
430    Some(hasher.finish())
431}
432
433/// Applies the elements of `b` to the corresponding elements of `a`.
434///
435/// If the length of `b` is greater than that of `a`, the excess elements of `b`
436/// are cloned and appended to `a`.
437///
438/// # Panics
439///
440/// This function panics if `b` is not a list.
441#[inline]
442pub fn list_apply<L: List>(a: &mut L, b: &dyn Reflect) {
443    if let Err(err) = list_try_apply(a, b) {
444        panic!("{err}");
445    }
446}
447
448/// Tries to apply the elements of `b` to the corresponding elements of `a` and
449/// returns a Result.
450///
451/// If the length of `b` is greater than that of `a`, the excess elements of `b`
452/// are cloned and appended to `a`.
453///
454/// # Errors
455///
456/// This function returns an [`ApplyError::MismatchedKinds`] if `b` is not a list or if
457/// applying elements to each other fails.
458#[inline]
459pub fn list_try_apply<L: List>(a: &mut L, b: &dyn Reflect) -> Result<(), ApplyError> {
460    if let ReflectRef::List(list_value) = b.reflect_ref() {
461        for (i, value) in list_value.iter().enumerate() {
462            if i < a.len() {
463                if let Some(v) = a.get_mut(i) {
464                    v.try_apply(value)?;
465                }
466            } else {
467                List::push(a, value.clone_value());
468            }
469        }
470    } else {
471        return Err(ApplyError::MismatchedKinds {
472            from_kind: b.reflect_kind(),
473            to_kind: ReflectKind::List,
474        });
475    }
476    Ok(())
477}
478
479/// Compares a [`List`] with a [`Reflect`] value.
480///
481/// Returns true if and only if all of the following are true:
482/// - `b` is a list;
483/// - `b` is the same length as `a`;
484/// - [`Reflect::reflect_partial_eq`] returns `Some(true)` for pairwise elements of `a` and `b`.
485///
486/// Returns [`None`] if the comparison couldn't even be performed.
487#[inline]
488pub fn list_partial_eq<L: List>(a: &L, b: &dyn Reflect) -> Option<bool> {
489    let ReflectRef::List(list) = b.reflect_ref() else {
490        return Some(false);
491    };
492
493    if a.len() != list.len() {
494        return Some(false);
495    }
496
497    for (a_value, b_value) in a.iter().zip(list.iter()) {
498        let eq_result = a_value.reflect_partial_eq(b_value);
499        if let failed @ (Some(false) | None) = eq_result {
500            return failed;
501        }
502    }
503
504    Some(true)
505}
506
507/// The default debug formatter for [`List`] types.
508///
509/// # Example
510/// ```
511/// use bevy_reflect::Reflect;
512///
513/// let my_list: &dyn Reflect = &vec![1, 2, 3];
514/// println!("{:#?}", my_list);
515///
516/// // Output:
517///
518/// // [
519/// //   1,
520/// //   2,
521/// //   3,
522/// // ]
523/// ```
524#[inline]
525pub fn list_debug(dyn_list: &dyn List, f: &mut Formatter<'_>) -> std::fmt::Result {
526    let mut debug = f.debug_list();
527    for item in dyn_list.iter() {
528        debug.entry(&item as &dyn Debug);
529    }
530    debug.finish()
531}
532
533#[cfg(test)]
534mod tests {
535    use super::DynamicList;
536    use crate::{Reflect, ReflectRef};
537    use std::assert_eq;
538
539    #[test]
540    fn test_into_iter() {
541        let mut list = DynamicList::default();
542        list.push(0usize);
543        list.push(1usize);
544        list.push(2usize);
545        let items = list.into_iter();
546        for (index, item) in items.into_iter().enumerate() {
547            let value = item.take::<usize>().expect("couldn't downcast to usize");
548            assert_eq!(index, value);
549        }
550    }
551
552    #[test]
553    fn next_index_increment() {
554        const SIZE: usize = if cfg!(debug_assertions) {
555            4
556        } else {
557            // If compiled in release mode, verify we dont overflow
558            usize::MAX
559        };
560        let b = Box::new(vec![(); SIZE]).into_reflect();
561
562        let ReflectRef::List(list) = b.reflect_ref() else {
563            panic!("Not a list...");
564        };
565
566        let mut iter = list.iter();
567        iter.index = SIZE - 1;
568        assert!(iter.next().is_some());
569
570        // When None we should no longer increase index
571        assert!(iter.next().is_none());
572        assert!(iter.index == SIZE);
573        assert!(iter.next().is_none());
574        assert!(iter.index == SIZE);
575    }
576}
bevy_reflect/list.rs

bevy_reflect/
list.rs
