Skip to content

Commit 5d0e815

Browse files
h-vetinarijreback
authored andcommitted
DOC: add concatenation-section to text.rst (#20790)
1 parent 64564e8 commit 5d0e815

File tree

2 files changed

+85
-0
lines changed

2 files changed

+85
-0
lines changed

doc/source/text.rst

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -199,6 +199,75 @@ regular expression object will raise a ``ValueError``.
199199
---------------------------------------------------------------------------
200200
ValueError: case and flags cannot be set when pat is a compiled regex
201201

202+
.. _text.concatenate:
203+
204+
Concatenation
205+
-------------
206+
207+
There are several ways to concatenate a ``Series`` or ``Index``, either with itself or others, all based on :meth:`~Series.str.cat`,
208+
resp. ``Index.str.cat``.
209+
210+
Concatenating a single Series into a string
211+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
212+
213+
The content of a ``Series`` (or ``Index``) can be concatenated:
214+
215+
.. ipython:: python
216+
217+
s = pd.Series(['a', 'b', 'c', 'd'])
218+
s.str.cat(sep=',')
219+
220+
If not specified, the keyword ``sep`` for the separator defaults to the empty string, ``sep=''``:
221+
222+
.. ipython:: python
223+
224+
s.str.cat()
225+
226+
By default, missing values are ignored. Using ``na_rep``, they can be given a representation:
227+
228+
.. ipython:: python
229+
230+
t = pd.Series(['a', 'b', np.nan, 'd'])
231+
t.str.cat(sep=',')
232+
t.str.cat(sep=',', na_rep='-')
233+
234+
Concatenating a Series and something list-like into a Series
235+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
236+
237+
The first argument to :meth:`~Series.str.cat` can be a list-like object, provided that it matches the length of the calling ``Series`` (or ``Index``).
238+
239+
.. ipython:: python
240+
241+
s.str.cat(['A', 'B', 'C', 'D'])
242+
243+
Missing values on either side will result in missing values in the result as well, *unless* ``na_rep`` is specified:
244+
245+
.. ipython:: python
246+
247+
s.str.cat(t)
248+
s.str.cat(t, na_rep='-')
249+
250+
Series are *not* aligned on their index before concatenation:
251+
252+
.. ipython:: python
253+
254+
u = pd.Series(['b', 'd', 'e', 'c'], index=[1, 3, 4, 2])
255+
# without alignment
256+
s.str.cat(u)
257+
# with separate alignment
258+
v, w = s.align(u)
259+
v.str.cat(w, na_rep='-')
260+
261+
Concatenating a Series and many objects into a Series
262+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
263+
264+
List-likes (excluding iterators, ``dict``-views, etc.) can be arbitrarily combined in a list.
265+
All elements of the list must match in length to the calling ``Series`` (resp. ``Index``):
266+
267+
.. ipython:: python
268+
269+
x = pd.Series([1, 2, 3, 4], index=['A', 'B', 'C', 'D'])
270+
s.str.cat([['A', 'B', 'C', 'D'], s, s.values, x.index])
202271
203272
Indexing with ``.str``
204273
----------------------

pandas/core/strings.py

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,22 @@
3636

3737

3838
def _get_array_list(arr, others):
39+
"""
40+
Auxiliary function for :func:`str_cat`
41+
42+
Parameters
43+
----------
44+
arr : ndarray
45+
The left-most ndarray of the concatenation
46+
others : list, ndarray, Series
47+
The rest of the content to concatenate. If list of list-likes,
48+
all elements must be passable to ``np.asarray``.
49+
50+
Returns
51+
-------
52+
list
53+
List of all necessary arrays
54+
"""
3955
from pandas.core.series import Series
4056

4157
if len(others) and isinstance(com._values_from_object(others)[0],

0 commit comments

Comments
 (0)