Refactor EventReader::iter to read (#9631)

# Objective

- The current `EventReader::iter` has been determined to cause confusion
among new Bevy users. It was suggested by @JoJoJet to rename the method
to better clarify its usage.
- Solves #9624 

## Solution

- Rename `EventReader::iter` to `EventReader::read`.
- Rename `EventReader::iter_with_id` to `EventReader::read_with_id`.
- Rename `ManualEventReader::iter` to `ManualEventReader::read`.
- Rename `ManualEventReader::iter_with_id` to
`ManualEventReader::read_with_id`.

---

## Changelog

- `EventReader::iter` has been renamed to `EventReader::read`.
- `EventReader::iter_with_id` has been renamed to
`EventReader::read_with_id`.
- `ManualEventReader::iter` has been renamed to
`ManualEventReader::read`.
- `ManualEventReader::iter_with_id` has been renamed to
`ManualEventReader::read_with_id`.
- Deprecated `EventReader::iter`
- Deprecated `EventReader::iter_with_id`
- Deprecated `ManualEventReader::iter`
- Deprecated `ManualEventReader::iter_with_id`

## Migration Guide

- Existing usages of `EventReader::iter` and `EventReader::iter_with_id`
will have to be changed to `EventReader::read` and
`EventReader::read_with_id` respectively.
- Existing usages of `ManualEventReader::iter` and
`ManualEventReader::iter_with_id` will have to be changed to
`ManualEventReader::read` and `ManualEventReader::read_with_id`
respectively.

Author: hate

crates/bevy_app/src/schedule_runner.rs

@@ -94,7 +94,7 @@ impl Plugin for ScheduleRunnerPlugin {
                         if let Some(app_exit_events) =
                             app.world.get_resource_mut::<Events<AppExit>>()
                         {
-                            if let Some(exit) = app_exit_event_reader.iter(&app_exit_events).last()
+                            if let Some(exit) = app_exit_event_reader.read(&app_exit_events).last()
                             {
                                 return Err(exit.clone());
                             }

crates/bevy_ecs/examples/events.rs

@@ -52,7 +52,7 @@ fn sending_system(mut event_writer: EventWriter<MyEvent>) {
 // This system listens for events of the type MyEvent
 // If an event is received it will be printed to the console
 fn receiving_system(mut event_reader: EventReader<MyEvent>) {
-    for my_event in event_reader.iter() {
+    for my_event in event_reader.read() {
         println!(
             "    Received message {:?}, with random value of {}",
             my_event.message, my_event.random_value

crates/bevy_ecs/src/event.rs

@@ -403,13 +403,27 @@ impl<'w, 's, E: Event> EventReader<'w, 's, E> {
     /// Iterates over the events this [`EventReader`] has not seen yet. This updates the
     /// [`EventReader`]'s event counter, which means subsequent event reads will not include events
     /// that happened before now.
+    pub fn read(&mut self) -> EventIterator<'_, E> {
+        self.reader.read(&self.events)
+    }
+
+    /// Iterates over the events this [`EventReader`] has not seen yet. This updates the
+    /// [`EventReader`]'s event counter, which means subsequent event reads will not include events
+    /// that happened before now.
+    #[deprecated = "use `.read()` instead."]
     pub fn iter(&mut self) -> EventIterator<'_, E> {
-        self.reader.iter(&self.events)
+        self.reader.read(&self.events)
+    }
+
+    /// Like [`read`](Self::read), except also returning the [`EventId`] of the events.
+    pub fn read_with_id(&mut self) -> EventIteratorWithId<'_, E> {
+        self.reader.read_with_id(&self.events)
     }
 
     /// Like [`iter`](Self::iter), except also returning the [`EventId`] of the events.
+    #[deprecated = "use `.read_with_id() instead."]
     pub fn iter_with_id(&mut self) -> EventIteratorWithId<'_, E> {
-        self.reader.iter_with_id(&self.events)
+        self.reader.read_with_id(&self.events)
     }
 
     /// Determines the number of events available to be read from this [`EventReader`] without consuming any.
@@ -545,12 +559,24 @@ impl<E: Event> Default for ManualEventReader<E> {
 
 #[allow(clippy::len_without_is_empty)] // Check fails since the is_empty implementation has a signature other than `(&self) -> bool`
 impl<E: Event> ManualEventReader<E> {
+    /// See [`EventReader::read`]
+    pub fn read<'a>(&'a mut self, events: &'a Events<E>) -> EventIterator<'a, E> {
+        self.read_with_id(events).without_id()
+    }
+
     /// See [`EventReader::iter`]
+    #[deprecated = "use `.read()` instead."]
     pub fn iter<'a>(&'a mut self, events: &'a Events<E>) -> EventIterator<'a, E> {
-        self.iter_with_id(events).without_id()
+        self.read_with_id(events).without_id()
+    }
+
+    /// See [`EventReader::read_with_id`]
+    pub fn read_with_id<'a>(&'a mut self, events: &'a Events<E>) -> EventIteratorWithId<'a, E> {
+        EventIteratorWithId::new(self, events)
     }
 
     /// See [`EventReader::iter_with_id`]
+    #[deprecated = "use `.read_with_id() instead."]
     pub fn iter_with_id<'a>(&'a mut self, events: &'a Events<E>) -> EventIteratorWithId<'a, E> {
         EventIteratorWithId::new(self, events)
     }
@@ -834,7 +860,7 @@ mod tests {
         events: &Events<E>,
         reader: &mut ManualEventReader<E>,
     ) -> Vec<E> {
-        reader.iter(events).cloned().collect::<Vec<E>>()
+        reader.read(events).cloned().collect::<Vec<E>>()
     }
 
     #[derive(Event, PartialEq, Eq, Debug)]
@@ -844,21 +870,21 @@ mod tests {
         let mut events = Events::<E>::default();
         let mut reader = events.get_reader();
 
-        assert!(reader.iter(&events).next().is_none());
+        assert!(reader.read(&events).next().is_none());
 
         events.send(E(0));
-        assert_eq!(*reader.iter(&events).next().unwrap(), E(0));
-        assert_eq!(reader.iter(&events).next(), None);
+        assert_eq!(*reader.read(&events).next().unwrap(), E(0));
+        assert_eq!(reader.read(&events).next(), None);
 
         events.send(E(1));
         clear_func(&mut events);
-        assert!(reader.iter(&events).next().is_none());
+        assert!(reader.read(&events).next().is_none());
 
         events.send(E(2));
         events.update();
         events.send(E(3));
 
-        assert!(reader.iter(&events).eq([E(2), E(3)].iter()));
+        assert!(reader.read(&events).eq([E(2), E(3)].iter()));
     }
 
     #[test]
@@ -880,7 +906,7 @@ mod tests {
 
         events.extend(vec![TestEvent { i: 0 }, TestEvent { i: 1 }]);
         assert!(reader
-            .iter(&events)
+            .read(&events)
             .eq([TestEvent { i: 0 }, TestEvent { i: 1 }].iter()));
     }
 
@@ -923,7 +949,7 @@ mod tests {
         events.send(TestEvent { i: 1 });
         events.send(TestEvent { i: 2 });
         let mut reader = events.get_reader();
-        let mut iter = reader.iter(&events);
+        let mut iter = reader.read(&events);
         assert_eq!(iter.len(), 3);
         iter.next();
         assert_eq!(iter.len(), 2);
@@ -994,13 +1020,13 @@ mod tests {
 
         events.send(TestEvent { i: 0 });
         events.send(TestEvent { i: 1 });
-        assert_eq!(reader.iter(&events).count(), 2);
+        assert_eq!(reader.read(&events).count(), 2);
 
         let mut old_events = Vec::from_iter(events.update_drain());
         assert!(old_events.is_empty());
 
         events.send(TestEvent { i: 2 });
-        assert_eq!(reader.iter(&events).count(), 1);
+        assert_eq!(reader.read(&events).count(), 1);
 
         old_events.extend(events.update_drain());
         assert_eq!(old_events.len(), 2);
@@ -1028,7 +1054,7 @@ mod tests {
 
         let mut schedule = Schedule::default();
         schedule.add_systems(|mut events: EventReader<TestEvent>| {
-            let mut iter = events.iter();
+            let mut iter = events.read();
 
             assert_eq!(iter.next(), Some(&TestEvent { i: 0 }));
             assert_eq!(iter.nth(2), Some(&TestEvent { i: 3 }));
@@ -1048,7 +1074,7 @@ mod tests {
 
         let mut reader =
             IntoSystem::into_system(|mut events: EventReader<TestEvent>| -> Option<TestEvent> {
-                events.iter().last().copied()
+                events.read().last().copied()
             });
         reader.initialize(&mut world);
 

crates/bevy_ecs/src/removal_detection.rs

@@ -202,7 +202,7 @@ impl<'w, 's, T: Component> RemovedComponents<'w, 's, T> {
     /// that happened before now.
     pub fn iter(&mut self) -> RemovedIter<'_> {
         self.reader_mut_with_events()
-            .map(|(reader, events)| reader.iter(events).cloned())
+            .map(|(reader, events)| reader.read(events).cloned())
             .into_iter()
             .flatten()
             .map(RemovedComponentEntity::into)
@@ -211,7 +211,7 @@ impl<'w, 's, T: Component> RemovedComponents<'w, 's, T> {
     /// Like [`iter`](Self::iter), except also returning the [`EventId`] of the events.
     pub fn iter_with_id(&mut self) -> RemovedIterWithId<'_> {
         self.reader_mut_with_events()
-            .map(|(reader, events)| reader.iter_with_id(events))
+            .map(|(reader, events)| reader.read_with_id(events))
             .into_iter()
             .flatten()
             .map(map_id_events)

crates/bevy_ecs/src/schedule/condition.rs

@@ -895,7 +895,7 @@ pub mod common_conditions {
         // calls of the run condition. Simply checking `is_empty` would not be enough.
         // PERF: note that `count` is efficient (not actually looping/iterating),
         // due to Bevy having a specialized implementation for events.
-        move |mut reader: EventReader<T>| reader.iter().count() > 0
+        move |mut reader: EventReader<T>| reader.read().count() > 0
     }
 
     /// Generates a [`Condition`](super::Condition)-satisfying closure that returns `true`

crates/bevy_gilrs/src/rumble.rs

@@ -136,7 +136,7 @@ pub(crate) fn play_gilrs_rumble(
         .retain(|_gamepad, rumbles| !rumbles.is_empty());
 
     // Add new effects.
-    for rumble in requests.iter().cloned() {
+    for rumble in requests.read().cloned() {
         let gamepad = rumble.gamepad();
         match handle_rumble_request(&mut running_rumbles, &mut gilrs, rumble, current_time) {
             Ok(()) => {}

crates/bevy_input/src/gamepad.rs

@@ -1023,7 +1023,7 @@ pub fn gamepad_connection_system(
     mut button_axis: ResMut<Axis<GamepadButton>>,
     mut button_input: ResMut<Input<GamepadButton>>,
 ) {
-    for connection_event in connection_events.iter() {
+    for connection_event in connection_events.read() {
         let gamepad = connection_event.gamepad;
 
         if let GamepadConnection::Connected(info) = &connection_event.connection {
@@ -1168,7 +1168,7 @@ pub fn gamepad_axis_event_system(
     mut gamepad_axis: ResMut<Axis<GamepadAxis>>,
     mut axis_events: EventReader<GamepadAxisChangedEvent>,
 ) {
-    for axis_event in axis_events.iter() {
+    for axis_event in axis_events.read() {
         let axis = GamepadAxis::new(axis_event.gamepad, axis_event.axis_type);
         gamepad_axis.set(axis, axis_event.value);
     }
@@ -1181,7 +1181,7 @@ pub fn gamepad_button_event_system(
     mut button_input_events: EventWriter<GamepadButtonInput>,
     settings: Res<GamepadSettings>,
 ) {
-    for button_event in button_changed_events.iter() {
+    for button_event in button_changed_events.read() {
         let button = GamepadButton::new(button_event.gamepad, button_event.button_type);
         let value = button_event.value;
         let button_property = settings.get_button_settings(button);
@@ -1258,7 +1258,7 @@ pub fn gamepad_event_system(
     mut button_input: ResMut<Input<GamepadButton>>,
 ) {
     button_input.bypass_change_detection().clear();
-    for gamepad_event in gamepad_events.iter() {
+    for gamepad_event in gamepad_events.read() {
         match gamepad_event {
             GamepadEvent::Connection(connection_event) => {
                 connection_events.send(connection_event.clone());

crates/bevy_input/src/keyboard.rs

@@ -53,7 +53,7 @@ pub fn keyboard_input_system(
     // Avoid clearing if it's not empty to ensure change detection is not triggered.
     scan_input.bypass_change_detection().clear();
     key_input.bypass_change_detection().clear();
-    for event in keyboard_input_events.iter() {
+    for event in keyboard_input_events.read() {
         let KeyboardInput {
             scan_code, state, ..
         } = event;

crates/bevy_input/src/mouse.rs

@@ -144,7 +144,7 @@ pub fn mouse_button_input_system(
     mut mouse_button_input_events: EventReader<MouseButtonInput>,
 ) {
     mouse_button_input.bypass_change_detection().clear();
-    for event in mouse_button_input_events.iter() {
+    for event in mouse_button_input_events.read() {
         match event.state {
             ButtonState::Pressed => mouse_button_input.press(event.button),
             ButtonState::Released => mouse_button_input.release(event.button),

crates/bevy_input/src/touch.rs

@@ -366,7 +366,7 @@ pub fn touch_screen_input_system(
 ) {
     touch_state.update();
 
-    for event in touch_input_events.iter() {
+    for event in touch_input_events.read() {
         touch_state.process_touch_event(event);
     }
 }

crates/bevy_pbr/src/material.rs

@@ -608,7 +608,7 @@ pub fn extract_materials<M: Material>(
 ) {
     let mut changed_assets = HashSet::default();
     let mut removed = Vec::new();
-    for event in events.iter() {
+    for event in events.read() {
         match event {
             AssetEvent::Created { handle } | AssetEvent::Modified { handle } => {
                 changed_assets.insert(handle.clone_weak());

crates/bevy_render/src/camera/camera.rs

@@ -575,11 +575,11 @@ pub fn camera_system<T: CameraProjection + Component>(
     let primary_window = primary_window.iter().next();
 
     let mut changed_window_ids = HashSet::new();
-    changed_window_ids.extend(window_created_events.iter().map(|event| event.window));
-    changed_window_ids.extend(window_resized_events.iter().map(|event| event.window));
+    changed_window_ids.extend(window_created_events.read().map(|event| event.window));
+    changed_window_ids.extend(window_resized_events.read().map(|event| event.window));
 
     let changed_image_handles: HashSet<&Handle<Image>> = image_asset_events
-        .iter()
+        .read()
         .filter_map(|event| {
             if let AssetEvent::Modified { handle } = event {
                 Some(handle)

crates/bevy_render/src/render_asset.rs

@@ -136,7 +136,7 @@ fn extract_render_asset<A: RenderAsset>(
 ) {
     let mut changed_assets = HashSet::default();
     let mut removed = Vec::new();
-    for event in events.iter() {
+    for event in events.read() {
         match event {
             AssetEvent::Created { handle } | AssetEvent::Modified { handle } => {
                 changed_assets.insert(handle.clone_weak());

crates/bevy_render/src/render_resource/pipeline_cache.rs

@@ -832,7 +832,7 @@ impl PipelineCache {
         shaders: Extract<Res<Assets<Shader>>>,
         mut events: Extract<EventReader<AssetEvent<Shader>>>,
     ) {
-        for event in events.iter() {
+        for event in events.read() {
             match event {
                 AssetEvent::Created { handle } | AssetEvent::Modified { handle } => {
                     if let Some(shader) = shaders.get(handle) {

crates/bevy_render/src/view/window/mod.rs

@@ -161,7 +161,7 @@ fn extract_windows(
         }
     }
 
-    for closed_window in closed.iter() {
+    for closed_window in closed.read() {
         extracted_windows.remove(&closed_window.window);
     }
     // This lock will never block because `callbacks` is `pub(crate)` and this is the singular callsite where it's locked.

crates/bevy_scene/src/scene_spawner.rs

@@ -354,7 +354,7 @@ pub fn scene_spawner_system(world: &mut World) {
         let scene_spawner = &mut *scene_spawner;
         for event in scene_spawner
             .scene_asset_event_reader
-            .iter(scene_asset_events)
+            .read(scene_asset_events)
         {
             if let AssetEvent::Modified { handle } = event {
                 if scene_spawner.spawned_dynamic_scenes.contains_key(handle) {

crates/bevy_sprite/src/mesh2d/material.rs

@@ -467,7 +467,7 @@ pub fn extract_materials_2d<M: Material2d>(
 ) {
     let mut changed_assets = HashSet::default();
     let mut removed = Vec::new();
-    for event in events.iter() {
+    for event in events.read() {
         match event {
             AssetEvent::Created { handle } | AssetEvent::Modified { handle } => {
                 changed_assets.insert(handle.clone_weak());

crates/bevy_sprite/src/render/mod.rs

@@ -327,7 +327,7 @@ pub fn extract_sprite_events(
     let SpriteAssetEvents { ref mut images } = *events;
     images.clear();
 
-    for image in image_events.iter() {
+    for image in image_events.read() {
         // AssetEvent: !Clone
         images.push(match image {
             AssetEvent::Created { handle } => AssetEvent::Created {

crates/bevy_text/src/text2d.rs

@@ -165,7 +165,7 @@ pub fn update_text2d_layout(
     mut text_query: Query<(Entity, Ref<Text>, Ref<Text2dBounds>, &mut TextLayoutInfo)>,
 ) {
     // We need to consume the entire iterator, hence `last`
-    let factor_changed = scale_factor_changed.iter().last().is_some();
+    let factor_changed = scale_factor_changed.read().last().is_some();
 
     // TODO: Support window-independent scaling: https://github.com/bevyengine/bevy/issues/5621
     let scale_factor = windows

crates/bevy_ui/src/layout/mod.rs

@@ -248,7 +248,7 @@ pub fn ui_layout_system(
         };
 
     let resized = resize_events
-        .iter()
+        .read()
         .any(|resized_window| resized_window.window == primary_window_entity);
 
     // update window root nodes

crates/bevy_window/src/system.rs

@@ -41,7 +41,7 @@ pub fn exit_on_primary_closed(
 ///
 /// [`WindowPlugin`]: crate::WindowPlugin
 pub fn close_when_requested(mut commands: Commands, mut closed: EventReader<WindowCloseRequested>) {
-    for event in closed.iter() {
+    for event in closed.read() {
         commands.entity(event.window).despawn();
     }
 }

crates/bevy_winit/src/accessibility.rs

@@ -46,7 +46,7 @@ fn handle_window_focus(
     adapters: NonSend<AccessKitAdapters>,
     mut focused: EventReader<WindowFocused>,
 ) {
-    for event in focused.iter() {
+    for event in focused.read() {
         if let Some(adapter) = adapters.get(&event.window) {
             adapter.update_if_active(|| {
                 let focus_id = (*focus).unwrap_or_else(|| event.window);
@@ -68,7 +68,7 @@ fn window_closed(
     mut receivers: ResMut<WinitActionHandlers>,
     mut events: EventReader<WindowClosed>,
 ) {
-    for WindowClosed { window, .. } in events.iter() {
+    for WindowClosed { window, .. } in events.read() {
         adapters.remove(window);
         receivers.remove(window);
     }