bevy/crates/bevy_utils/src
Joseph 474b55a29c
Add system.map(...) for transforming the output of a system (#8526)
# Objective

Any time we wish to transform the output of a system, we currently use
system piping to do so:

```rust
my_system.pipe(|In(x)| do_something(x))
```

Unfortunately, system piping is not a zero cost abstraction. Each call
to `.pipe` requires allocating two extra access sets: one for the second
system and one for the combined accesses of both systems. This also adds
extra work to each call to `update_archetype_component_access`, which
stacks as one adds multiple layers of system piping.

## Solution

Add the `AdapterSystem` abstraction: similar to `CombinatorSystem`, this
allows you to implement a trait to generically control how a system is
run and how its inputs and outputs are processed. Unlike
`CombinatorSystem`, this does not have any overhead when computing world
accesses which makes it ideal for simple operations such as inverting or
ignoring the output of a system.

Add the extension method `.map(...)`: this is similar to `.pipe(...)`,
only it accepts a closure as an argument instead of an `In<T>` system.

```rust
my_system.map(do_something)
```

This has the added benefit of making system names less messy: a system
that ignores its output will just be called `my_system`, instead of
`Pipe(my_system, ignore)`

---

## Changelog

TODO

## Migration Guide

The `system_adapter` functions have been deprecated: use `.map` instead,
which is a lightweight alternative to `.pipe`.

```rust
// Before:
my_system.pipe(system_adapter::ignore)
my_system.pipe(system_adapter::unwrap)
my_system.pipe(system_adapter::new(T::from))

// After:
my_system.map(std::mem::drop)
my_system.map(Result::unwrap)
my_system.map(T::from)

// Before:
my_system.pipe(system_adapter::info)
my_system.pipe(system_adapter::dbg)
my_system.pipe(system_adapter::warn)
my_system.pipe(system_adapter::error)

// After:
my_system.map(bevy_utils::info)
my_system.map(bevy_utils::dbg)
my_system.map(bevy_utils::warn)
my_system.map(bevy_utils::error)
```

---------

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2023-08-28 16:36:46 +00:00
..
default.rs default() shorthand (#4071) 2022-03-01 20:52:09 +00:00
float_ord.rs Document That FloatOrd Implements Hash and Eq Too (#5228) 2022-07-11 14:11:27 +00:00
futures.rs Document remaining members of bevy_utils (#6897) 2022-12-11 18:46:42 +00:00
label.rs Simplify world schedule methods (#8403) 2023-04-19 19:48:35 +00:00
lib.rs Add system.map(...) for transforming the output of a system (#8526) 2023-08-28 16:36:46 +00:00
short_names.rs change 'collapse_type_name' to retain enum types (#9587) 2023-08-26 14:50:12 +00:00
synccell.rs Fix some typos (#7763) 2023-02-20 22:56:57 +00:00
syncunsafecell.rs Fix typos throughout the project (#9090) 2023-07-10 00:11:51 +00:00