Skip to content

Commit

Permalink
Improve documentation for set_if_neq (#8254)
Browse files Browse the repository at this point in the history
# Objective

Reword the documentation for `set_if_neq` and add a doctest.
  • Loading branch information
JoJoJet authored Mar 30, 2023
1 parent d9113cc commit 3533c3d
Showing 1 changed file with 30 additions and 4 deletions.
34 changes: 30 additions & 4 deletions crates/bevy_ecs/src/change_detection.rs
Original file line number Diff line number Diff line change
Expand Up @@ -119,12 +119,38 @@ pub trait DetectChangesMut: DetectChanges {
/// you are trying to synchronize representations using change detection and need to avoid infinite recursion.
fn bypass_change_detection(&mut self) -> &mut Self::Inner;

/// Sets `self` to `value`, if and only if `*self != *value`
///
/// `T` is the type stored within the smart pointer (e.g. [`Mut`] or [`ResMut`]).
/// Overwrites this smart pointer with the given value, if and only if `*self != value`
///
/// This is useful to ensure change detection is only triggered when the underlying value
/// changes, instead of every time [`DerefMut`] is used.
/// changes, instead of every time it is mutably accessed.
///
/// # Examples
///
/// ```
/// # use bevy_ecs::{prelude::*, schedule::common_conditions::resource_changed};
/// #[derive(Resource, PartialEq, Eq)]
/// pub struct Score(u32);
///
/// fn reset_score(mut score: ResMut<Score>) {
/// // Set the score to zero, unless it is already zero.
/// score.set_if_neq(Score(0));
/// }
/// # let mut world = World::new();
/// # world.insert_resource(Score(1));
/// # let mut score_changed = IntoSystem::into_system(resource_changed::<Score>());
/// # score_changed.initialize(&mut world);
/// # score_changed.run((), &mut world);
/// #
/// # let mut schedule = Schedule::new();
/// # schedule.add_systems(reset_score);
/// #
/// # // first time `reset_score` runs, the score is changed.
/// # schedule.run(&mut world);
/// # assert!(score_changed.run((), &mut world));
/// # // second time `reset_score` runs, the score is not changed.
/// # schedule.run(&mut world);
/// # assert!(!score_changed.run((), &mut world));
/// ```
#[inline]
fn set_if_neq(&mut self, value: Self::Inner)
where
Expand Down

0 comments on commit 3533c3d

Please sign in to comment.