API: str.cat will align on index (collected)

Author: h-vetinari

doc/source/text.rst

@@ -247,27 +247,84 @@ Missing values on either side will result in missing values in the result as wel
     s.str.cat(t)
     s.str.cat(t, na_rep='-')
 
-Series are *not* aligned on their index before concatenation:
+Concatenating a Series and something array-like into a Series
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 0.23.0
+
+The parameter ``others`` can also be two-dimensional. In this case, the number or rows must match the lengths of the calling ``Series`` (or ``Index``).
 
 .. ipython:: python
 
-    u = pd.Series(['b', 'd', 'e', 'c'], index=[1, 3, 4, 2])
-    # without alignment
+    d = pd.concat([t, s], axis=1)
+    d
+    s.str.cat(d, na_rep='-')
+    
+Concatenating a Series and an indexed object into a Series, with alignment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 0.23.0
+
+For concatenation with a ``Series`` or ``DataFrame``, it is possible to align the respective indexes before concatenation by setting
+the ``join``-keyword, which controls the manner of alignment.
+
+.. ipython:: python
+
+    u = pd.Series(['b', 'd', 'a', 'c'], index=[1, 3, 0, 2])
     s.str.cat(u)
-    # with separate alignment
-    v, w = s.align(u)
-    v.str.cat(w, na_rep='-')
+    s.str.cat(u, join='left')
+
+.. warning::
+
+    If the ``join`` keyword is not passed, the method :meth:`~Series.str.cat` will currently fall back to the behavior before version 0.23.0 (i.e. no alignment),
+    but a ``FutureWarning`` will be raised, since this default will change to ``join='left'`` in a future version.
+
+To usual options are available for ``join`` (one of ``'left', 'outer', 'inner', 'right'``).
+In particular, alignment also means that the different lengths do not need to coincide anymore.
+
+.. ipython:: python
+
+    v = pd.Series(['z', 'a', 'b', 'd', 'e'], index=[-1, 0, 1, 3, 4])
+    s.str.cat(v, join='left', na_rep='-')
+    s.str.cat(v, join='outer', na_rep='-')
+
+The same alignment can be used when ``others`` is a ``DataFrame``:
+
+.. ipython:: python
+    
+    f = d.loc[[3, 2, 1, 0], :]
+    f
+    s.str.cat(f, join='left', na_rep='-')
 
 Concatenating a Series and many objects into a Series
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-List-likes (excluding iterators, ``dict``-views, etc.) can be arbitrarily combined in a list.
-All elements of the list must match in length to the calling ``Series`` (resp. ``Index``):
+All list-likes (as well as ``DataFrame`` and two-dimensional ``ndarray``) can be arbitrarily combined in a list-like container:
+
+.. ipython:: python
+
+    s.str.cat([u, t.values, ['A', 'B', 'C', 'D'], d.values, f], na_rep='-')
+
+All elements must match in length to the calling ``Series``, except those having an index if ``join`` is not None:
 
 .. ipython:: python
 
-    x = pd.Series([1, 2, 3, 4], index=['A', 'B', 'C', 'D'])
-    s.str.cat([['A', 'B', 'C', 'D'], s, s.values, x.index])
+    s.str.cat([u, v, ['A', 'B', 'C', 'D'], d.values, f.loc[[1]]],
+               join='outer', na_rep='-')
+
+If using ``join='right'`` on a list of ``others`` that contains different indexes,
+the union of these indexes will be used as the basis for the final concatenation:
+
+.. ipython:: python
+
+    s.str.cat([u.loc[[3]], v.loc[[-1, 0]]], join='right', na_rep='-')
+
+Finally, the surrounding container can also be an :obj:`Iterable` other than a ``list`` (e.g. an iterator, or a ``dict``-view, etc.):
+
+.. ipython:: python
+    
+    from collections import OrderedDict
+    s.str.cat(d.to_dict('series', into=OrderedDict).values(), na_rep='-')
 
 Indexing with ``.str``
 ----------------------

doc/source/whatsnew/v0.23.0.txt

@@ -308,6 +308,39 @@ The :func:`DataFrame.assign` now accepts dependent keyword arguments for python
 
       df.assign(A=df.A+1, C= lambda df: df.A* -1)
 
+.. _whatsnew_0230.enhancements.str_cat_align:
+
+``Series.str.cat`` has gained the ``join`` kwarg
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Previously, :meth:`Series.str.cat` did not -- in contrast to most of ``pandas`` -- align :class:`Series` on their index before concatenation (see :issue:`18657`).
+The method has now gained a keyword ``join`` to control the manner of alignment. In v.0.23 it will default to None (meaning no alignment), but this default will change
+to ``'left'`` in a future version of pandas.
+
+.. ipython:: python
+
+    s = pd.Series(['a', 'b', 'c', 'd'])
+    t = pd.Series(['b', 'd', 'e', 'c'], index=[1, 3, 4, 2])
+    s.str.cat(t)
+    s.str.cat(t, join='left', na_rep='-')
+
+In particular, ``others`` does not need to be of the same length as the calling ``Series`` (if both have an index and ``join is not None``).
+For more examples, see :ref:`here <text.concatenate>`.
+
+Additionally, ``str.cat`` now allows ``others`` to be a ``DataFrame`` or two-dimensional ``np.ndarray``.
+
+.. ipython:: python
+    
+    u = pd.Series(['b', 'd', 'a', 'c'], index=[1, 3, 0, 2])
+    d = pd.concat([s, u], axis=1)
+    t.str.cat(d.values)
+    s.str.cat(d, join='left', na_rep='-')
+
+Furthermore, any combination of "concatenateable" arguments can be passed in a list-like container (e.g. an iterator).
+    
+For categorical data, it is now possible to call :meth:`Series.str.cat` for ``CategoricalIndex`` as well (previously raised a ``ValueError``).
+Finally, if ``others is not None``, the resulting ``Series``/``Index`` will now remain categorical if the calling
+``Series``/``Index`` is categorical.
 
 .. _whatsnew_0230.enhancements.astype_category: