Tracker is a small crate that allows you to track changes to struct fields.
It implements the following methods for your struct fields:
-
get_#field_name()
Get an immutable reference tofield_name
-
get_mut_#field_name()
Get a mutable reference tofield_name
. Assumes the field will be modified and marks it as changed. -
set_#field_name(value)
Set a value offield_name
. Marks the field as changed only if the new value isn't equal with the previous value. -
update_#field_name(fn)
Update yourfield_name
with a function or closure. Assumes the field will be modified and marks it as changed. -
changed_#field_name()
Check if value offield_name
has changed.
To check for changes explicitly you can call var_name.changed(StructName::field_name())
and it will return a bool.
Multiple fields can be checked with var_name.changed(StructName::field_name_1() | StructName::field_name_2())
.
Finally, it is possible to check for any changes at all with var_name.changed(StructName::track_all())
or its shortcut
var_name.changed_any()
.
To reset all previous changes you can call var_name.reset()
.
Let's have a look at a small example.
#[tracker::track]
struct Test {
x: u8,
y: u64,
}
fn main() {
let mut t = Test {
x: 0,
y: 0,
// the macro generates a new variable called
// "tracker" that stores the changes
tracker: 0,
};
t.set_x(42);
// let's check whether the change was detected
assert!(t.changed(Test::x()));
// reset t so we don't track old changes
t.reset();
t.set_x(42);
// same value so no change
assert!(!t.changed(Test::x()));
}
What happens behind the scenes when you call set_x()
is that a bitflag is set in the tracker field of your struct:
y x
tracker: u8 = | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
set_x(42) -> | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 |
reset() -> | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
As you can see this works pretty efficient. The macro expansion looks like this:
impl Test {
pub fn get_x(&self) -> &u8 {
&self.x
}
pub fn get_mut_x(&mut self) -> &mut u8 {
self.tracker |= Self::x();
&mut self.x
}
pub fn update_x<F: Fn(&mut u8)>(&mut self, f: F) {
self.tracker |= Self::x();
f(&mut self.x);
}
pub const fn x() -> u8 {
1 << 0usize
}
pub fn set_x(&mut self, value: u8) {
if self.x != value {
self.tracker |= Self::x();
}
self.x = value;
}
}
#[tracker::track]
struct Test {
#[tracker::do_not_track]
a: u8,
#[do_not_track]
b: u8,
#[tracker::no_eq]
c: u8,
#[no_eq]
d: u8,
}
You can mark fields as
do_not_track
if you don't want tracker to implement anything for this fieldno_eq
if the type of the field doesn't implement PartialEq or tracker should not check for equality when callingset_#field_name(value)
so that even overwriting with the same value marks the field as changed.