Skip to content

Commit 988ffb0

Browse files
committed
DOC: Clarify str.cat output for Index object (GH35556)
1 parent 9da2c8f commit 988ffb0

File tree

1 file changed

+24
-12
lines changed

1 file changed

+24
-12
lines changed

pandas/core/strings/accessor.py

Lines changed: 24 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -526,11 +526,12 @@ def cat(
526526
to match the length of the calling Series/Index). To disable
527527
alignment, use `.values` on any Series/Index/DataFrame in `others`.
528528
529-
Returns
530-
-------
531-
str, Series or Index
532-
If `others` is None, `str` is returned, otherwise a `Series/Index`
533-
(same type as caller) of objects is returned.
529+
Returns
530+
-------
531+
str, Series or Index
532+
- If the caller is a Series and `others` is None, a single concatenated `str` is returned.
533+
- If the caller is an Index and `others` is None, an Index of length 1 containing the concatenated string is returned.
534+
- If `others` is specified, the result is a Series or Index (same type as caller) of concatenated strings.
534535
535536
See Also
536537
--------
@@ -608,14 +609,25 @@ def cat(
608609
dtype: object
609610
>>>
610611
>>> s.str.cat(t, join="right", na_rep="-")
611-
3 dd
612-
0 aa
613-
4 -e
614-
2 -c
615-
dtype: object
612+
3 dd
613+
0 aa
614+
4 -e
615+
2 -c
616+
dtype: object
617+
618+
When calling `.str.cat()` on an Index and not passing `others`, the return value is an Index:
619+
620+
>>> idx = pd.Index(["x", "y", np.nan])
621+
>>> idx.str.cat(sep="-")
622+
Index(['x-y'], dtype='object')
623+
624+
Note
625+
----
626+
Calling `.str.cat()` on a Series returns a string if `others` is None,
627+
but when called on an Index, it returns a new Index containing the concatenated string.
628+
629+
For more examples, see :ref:`here <text.concatenate>`.
616630
617-
For more examples, see :ref:`here <text.concatenate>`.
618-
"""
619631
# TODO: dispatch
620632
from pandas import (
621633
Index,

0 commit comments

Comments
 (0)