Repository: bevyengine/bevy
File: crates/bevy_ecs/src/system/commands/mod.rs (Rust)

Code before:
    /// # use bevy_ecs::prelude::*;
    /// fn my_system(mut commands: Commands) {
    ///     // We do our initialization in a separate function,
    ///     // which expects an owned `Commands`.
    ///     do_initialization(commands.reborrow());
    ///
    ///     // Since we only reborrowed the commands instead of moving them, we can still use them.
    ///     commands.spawn_empty();
    /// }
    /// #
    /// # fn do_initialization(_: Commands) {}
    /// ```
    pub fn reborrow(&mut self) -> Commands<'w, '_> {
        Commands {
            queue: match &mut self.queue {
                InternalQueue::CommandQueue(queue) => InternalQueue::CommandQueue(queue.reborrow()),
                InternalQueue::RawCommandQueue(queue) => {
                    InternalQueue::RawCommandQueue(queue.clone())
                }
            },
            allocator: self.allocator,
            entities: self.entities,
        }
    }

    /// Returns a [`Commands`] that pushes commands to the provided queue instead of the one from `self`.
    ///
    /// Does not affect commands previously queued on `self`, and `self` can still be used after this call.
    pub fn rebind<'q>(&self, queue: &'q mut CommandQueue) -> Commands<'w, 'q> {
        Commands {
            queue: InternalQueue::CommandQueue(Deferred(queue)),
            allocator: self.allocator,
            entities: self.entities,
        }
    }

    /// Take all commands from `other` and append them to `self`, leaving `other` empty.
    pub fn append(&mut self, other: &mut CommandQueue) {
        match &mut self.queue {
            InternalQueue::CommandQueue(queue) => queue.bytes.append(&mut other.bytes),
            InternalQueue::RawCommandQueue(queue) => {
                // SAFETY: Pointers in `RawCommandQueue` are never null
                unsafe { queue.bytes.as_mut() }.append(&mut other.bytes);
            }
        }
    }

    /// Spawns a new empty [`Entity`] and returns its corresponding [`EntityCommands`].
    ///
    /// # Example
    ///

Review comment (suggestion):
Fancy. This needs more docs! We need to cover:

1. Why you might want to do this.
2. What the semantic meaning of the returned `Commands` object is.
3. The fact that you don't seem to need to *do* anything with the returned `Commands` object: the magic seems to be done via `Drop`.

Code after:
    /// freed for reuse.
    ///
    /// The original `Commands` isn't mutated or borrowed after this returns, so you can keep using it.
    pub fn rebound_to<'q>(&self, queue: &'q mut CommandQueue) -> Commands<'w, 'q> {
        Commands::new_from_entities(queue, self.allocator, self.entities)
    }

    /// Returns a [`Commands`] with a smaller lifetime.
    ///
    /// This is useful if you have `&mut Commands` but need `Commands`.
    ///
    /// # Example
    ///
    /// ```
    /// # use bevy_ecs::prelude::*;
    /// fn my_system(mut commands: Commands) {
    ///     // We do our initialization in a separate function,
    ///     // which expects an owned `Commands`.
    ///     do_initialization(commands.reborrow());
    ///
    ///     // Since we only reborrowed the commands instead of moving them, we can still use them.
    ///     commands.spawn_empty();
    /// }
    /// #
    /// # fn do_initialization(_: Commands) {}
    /// ```
    pub fn reborrow(&mut self) -> Commands<'w, '_> {
        Commands {
            queue: match &mut self.queue {
                InternalQueue::CommandQueue(queue) => InternalQueue::CommandQueue(queue.reborrow()),
                InternalQueue::RawCommandQueue(queue) => {
                    InternalQueue::RawCommandQueue(queue.clone())
                }
            },
            allocator: self.allocator,
            entities: self.entities,
        }
    }

    /// Take all commands from `other` and append them to `self`, leaving `other` empty.
    pub fn append(&mut self, other: &mut CommandQueue) {
        match &mut self.queue {
            InternalQueue::CommandQueue(queue) => queue.bytes.append(&mut other.bytes),
            InternalQueue::RawCommandQueue(queue) => {
                // SAFETY: Pointers in `RawCommandQueue` are never null
                unsafe { queue.bytes.as_mut() }.append(&mut other.bytes);
            }
        }
    }

    /// Spawns a new empty [`Entity`] and returns its corresponding [`EntityCommands`].