BUG-26988 implement replace for categorical blocks

doc/source/whatsnew/v0.25.0.rst

@@ -585,6 +585,7 @@ Categorical
 
 - Bug in :func:`DataFrame.at` and :func:`Series.at` that would raise exception if the index was a :class:`CategoricalIndex` (:issue:`20629`)
 - Fixed bug in comparison of ordered :class:`Categorical` that contained missing values with a scalar which sometimes incorrectly resulted in ``True`` (:issue:`26504`)
+- Bug in :func:`DataFrame.replace` and :func:`Series.replace` that would give unusual results on categorical data (:issue:`26988`)
 -
 
 Datetimelike

pandas/core/internals/blocks.py

@@ -2978,6 +2978,29 @@ def where(self, other, cond, align=True, errors='raise',
                                                axis=axis, transpose=transpose)
         return result
 
+    def replace(self, to_replace, value, inplace=False, filter=None,
+                regex=False, convert=True):
+        if filter is None or not self.mgr_locs.isin(filter).any():
+            result = self if inplace else self.copy()
+            categories = result.values.categories.tolist()
+            if to_replace in categories:
+                if isna(value):
+                    result.values.remove_categories(to_replace, inplace=True)
+                else:
+                    index = categories.index(to_replace)
+                    categories[index] = value
+                    result.values.rename_categories(categories, inplace=True)
+            if convert:
+                return result.convert(by_item=True, numeric=False,
+                                      copy=not inplace)
+            else:
+                return result
+        else:
+            if not isna(value):
+                self.values.add_categories(value, inplace=True)
+            return super().replace(to_replace, value, inplace,
+                                   filter, regex, convert)
+
 
 # -----------------------------------------------------------------
 # Constructor Helpers

pandas/tests/series/test_replace.py

@@ -292,6 +292,23 @@ def test_replace_categorical(self, categorical, numeric):
         expected = pd.Series(numeric)
         tm.assert_series_equal(expected, result, check_dtype=False)
 
+    def test_replace_categorical_single(self):
+        # GH 26988
+        dti = pd.date_range('2016-01-01', periods=3, tz='US/Pacific')
+        s = pd.Series(dti)
+        c = s.astype('category')
+
+        expected = c.copy()
+        expected.cat.add_categories('foo', inplace=True)
+        expected[2] = 'foo'
+        expected.cat.remove_unused_categories(inplace=True)
+
+        result = c.replace(c[2], 'foo')
+        tm.assert_series_equal(expected, result)
+
+        c.replace(c[2], 'foo', inplace=True)
+        tm.assert_series_equal(expected, c)
+
     def test_replace_with_no_overflowerror(self):
         # GH 25616
         # casts to object without Exception from OverflowError