From 0a709799344ade15ffa20a566bb79cb5ddaade24 Mon Sep 17 00:00:00 2001
From: Michele Caini <michele.caini@gmail.com>
Date: Sat, 2 May 2020 01:20:08 +0200
Subject: [PATCH] observer: deprecated .replace, use .update instead

---
 docs/md/entity.md            | 17 ++++++++---------
 src/entt/entity/observer.hpp | 23 +++++++++++++++++++----
 2 files changed, 27 insertions(+), 13 deletions(-)

diff --git a/docs/md/entity.md b/docs/md/entity.md
index abd0f90ab..ca642bc08 100644
--- a/docs/md/entity.md
+++ b/docs/md/entity.md
@@ -419,7 +419,7 @@ An `observer` is initialized with an instance of a registry and a set of rules
 that describes what are the entities to intercept. As an example:
 
 ```cpp
-entt::observer observer{registry, entt::collector.replace<sprite>()};
+entt::observer observer{registry, entt::collector.update<sprite>()};
 ```
 
 The class is default constructible and can be reconfigured at any time by means
@@ -466,11 +466,11 @@ rules) to use with an `observer` instead.<br/>
 There are two types of `matcher`s:
 
 * Observing matcher: an observer will return at least all the living entities
-  for which one or more of the given components have been explicitly replaced
-  and not yet destroyed.
+  for which one or more of the given components have been updated and not yet
+  destroyed.
 
   ```cpp
-  entt::collector.replace<sprite>();
+  entt::collector.update<sprite>();
   ```
 
 * Grouping matcher: an observer will return at least all the living entities
@@ -484,22 +484,21 @@ There are two types of `matcher`s:
   A grouping matcher supports also exclusion lists as well as single components.
 
 Roughly speaking, an observing matcher intercepts the entities for which the
-given components are replaced (as in `registry::replace`) while a grouping
-matcher tracks the entities that have assigned the given components since the
-last time one asked.<br/>
+given components are updated while a grouping matcher tracks the entities that
+have assigned the given components since the last time one asked.<br/>
 If an entity already has all the components except one and the missing type is
 assigned to it, the entity is intercepted by a grouping matcher.
 
 In addition, a matcher can be filtered with a `where` clause:
 
 ```cpp
-entt::collector.replace<sprite>().where<position>(entt::exclude<velocity>);
+entt::collector.update<sprite>().where<position>(entt::exclude<velocity>);
 ```
 
 This clause introduces a way to intercept entities if and only if they are
 already part of a hypothetical group. If they are not, they aren't returned by
 the observer, no matter if they matched the given rule.<br/>
-In the example above, whenever the component `sprite` of an entity is replaced,
+In the example above, whenever the component `sprite` of an entity is updated,
 the observer probes the entity itself to verify that it has at least `position`
 and has not `velocity` before to store it aside. If one of the two conditions of
 the filter isn't respected, the entity is discared, no matter what.
diff --git a/src/entt/entity/observer.hpp b/src/entt/entity/observer.hpp
index 1307f602c..dea3cf8cb 100644
--- a/src/entt/entity/observer.hpp
+++ b/src/entt/entity/observer.hpp
@@ -61,9 +61,16 @@ struct basic_collector<> {
      * @return The updated collector.
      */
     template<typename AnyOf>
-    static constexpr auto replace() ENTT_NOEXCEPT {
+    static constexpr auto update() ENTT_NOEXCEPT {
         return basic_collector<matcher<type_list<>, type_list<>, AnyOf>>{};
     }
+
+    /*! @copydoc update */
+    template<typename AnyOf>
+    [[deprecated("use ::update instead")]]
+    static constexpr auto replace() ENTT_NOEXCEPT {
+        return update<AnyOf>();
+    }
 };
 
 /**
@@ -96,10 +103,18 @@ struct basic_collector<matcher<type_list<Reject...>, type_list<Require...>, Rule
      * @return The updated collector.
      */
     template<typename AnyOf>
-    static constexpr auto replace() ENTT_NOEXCEPT {
+    static constexpr auto update() ENTT_NOEXCEPT {
         return basic_collector<matcher<type_list<>, type_list<>, AnyOf>, current_type, Other...>{};
     }
 
+    /*! @copydoc update */
+    template<typename AnyOf>
+    [[deprecated("use ::update instead")]]
+    static constexpr auto replace() ENTT_NOEXCEPT {
+        return update<AnyOf>();
+    }
+
+
     /**
      * @brief Updates the filter of the last added matcher.
      * @tparam AllOf Types of components required by the matcher.
@@ -130,8 +145,8 @@ inline constexpr basic_collector<> collector{};
  * collector:
  *
  * * Observing matcher: an observer will return at least all the living entities
- *   for which one or more of the given components have been explicitly
- *   replaced and not yet destroyed.
+ *   for which one or more of the given components have been updated and not yet
+ *   destroyed.
  * * Grouping matcher: an observer will return at least all the living entities
  *   that would have entered the given group if it existed and that would have
  *   not yet left it.