@@ -526,11 +526,12 @@ def cat(
526
526
to match the length of the calling Series/Index). To disable
527
527
alignment, use `.values` on any Series/Index/DataFrame in `others`.
528
528
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.
534
535
535
536
See Also
536
537
--------
@@ -608,14 +609,25 @@ def cat(
608
609
dtype: object
609
610
>>>
610
611
>>> 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>`.
616
630
617
- For more examples, see :ref:`here <text.concatenate>`.
618
- """
619
631
# TODO: dispatch
620
632
from pandas import (
621
633
Index,
0 commit comments