DOC: whatsnew and docs for multiple accessors

Also add some docs in text.rst to mention the performance gains
when using ``s_cat.str`` vs ``s.str``.

Author: jankatins

doc/source/categorical.rst

@@ -515,6 +515,50 @@ To get a single value `Series` of type ``category`` pass in a list with a single
 
     df.loc[["h"],"cats"]
 
+String and datetime accessors
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 0.17.1
+
+The accessors  ``.dt`` and ``.str`` will work if the ``s.cat.categories`` are of an appropriate
+type:
+
+
+.. ipython:: python
+
+    str_s = pd.Series(list('aabb'))
+    str_cat = str_s.astype('category')
+    str_cat.str.contains("a")
+
+    date_s = pd.Series(date_range('1/1/2015', periods=5))
+    date_cat = date_s.astype('category')
+    date_cat.dt.day
+
+.. note::
+
+    The returned ``Series`` (or ``DataFrame``) is of the same type as if you used the
+    ``.str.<method>`` / ``.dt.<method>`` on a ``Series`` of that type (and not of
+    type ``category``!).
+
+That means, that the returned values from methods and properties on the accessors of a
+``Series`` and the returned values from methods and properties on the accessors of this
+``Series`` transformed to one of type `category` will be equal:
+
+.. ipython:: python
+
+    ret_s = str_s.str.contains("a")
+    ret_cat = str_cat.str.contains("a")
+    ret_s.dtype == ret_cat.dtype
+    ret_s == ret_cat
+
+.. note::
+
+    The work is done on the ``categories`` and then a new ``Series`` is constructed. This has
+    some performance implication if you have a ``Series`` of type string, where lots of elements
+    are repeated (i.e. the number of unique elements in the ``Series`` is a lot smaller than the
+    length of the ``Series``). In this case it can be faster to convert the original ``Series``
+    to one of type ``category`` and use ``.str.<method>`` or ``.dt.<property>`` on that.
+
 Setting
 ~~~~~~~
 

doc/source/text.rst

@@ -63,6 +63,22 @@ and replacing any remaining whitespaces with underscores:
    df.columns = df.columns.str.strip().str.lower().str.replace(' ', '_')
    df
 
+.. note::
+
+    If you do a lot of string munging and have a ``Series`` where lots of elements are repeated
+    (i.e. the number of unique elements in the ``Series`` is a lot smaller than the length of the
+    ``Series``), it can be faster to convert the original ``Series`` to one of type
+    ``category`` and then use ``.str.<method>`` or ``.dt.<property>`` on that. The
+    performance difference comes from the fact that, for ``Series`` of type ``category``, the
+    string operations are done on the ``.categories`` and not on each element of the
+    ``Series``. Please note that a ``Series`` of type ``category`` with string ``.categories`` has
+    some limitations in comparison of ``Series`` of type string (e.g. you can't add strings to
+    each other: ``s + " " + s`` won't work if ``s`` is a ``Series`` of type ``category``). Also,
+    ``.str`` methods which operate on elements of type ``list`` are not available on such a
+    ``Series``. If you are interested in having these performance gains on all string ``Series``,
+    please look at `this bug report <https://github.com/pydata/pandas/issues/8640>`_.
+
+
 Splitting and Replacing Strings
 -------------------------------
 

doc/source/whatsnew/v0.17.1.txt

@@ -65,6 +65,8 @@ Enhancements
 
      pd.Index([1, np.nan, 3]).fillna(2)
 
+- Series of type ``"category"`` now make ``.str.<...>`` and ``.dt.<...>`` accessor methods / properties available, if the categories are of that type. (:issue:`10661`)
+
 - ``pivot_table`` now has a ``margins_name`` argument so you can use something other than the default of 'All' (:issue:`3335`)
 
 .. _whatsnew_0171.api: