diff --git a/pandas/core/strings.py b/pandas/core/strings.py index 6702bf519c52e..c447f551da87c 100644 --- a/pandas/core/strings.py +++ b/pandas/core/strings.py @@ -2371,8 +2371,7 @@ def cat(self, others=None, sep=None, na_rep=None, join="left"): join : {'left', 'right', 'outer', 'inner'}, default 'left' Determines the join-style between the calling Series/Index and any Series/Index/DataFrame in `others` (objects without an index need - to match the length of the calling Series/Index). To disable - alignment, use `.values` on any Series/Index/DataFrame in `others`. + to match the length of the calling Series/Index). .. versionadded:: 0.23.0 .. versionchanged:: 1.0.0 @@ -2389,6 +2388,15 @@ def cat(self, others=None, sep=None, na_rep=None, join="left"): split : Split each string in the Series/Index. join : Join lists contained as elements in the Series/Index. + Notes + ----- + Since version 1.0.0, index alignment is performed when + `others` is a Series/Index/DataFrame (or a list-like containing + one). To disable alignment (the behavior in and before v0.23.0), + convert `others` to a numpy array while passing it as an argument + (using `.to_numpy()`). See the Examples section below for more + information. + Examples -------- When not passing `others`, all values are concatenated into a single @@ -2466,7 +2474,27 @@ def cat(self, others=None, sep=None, na_rep=None, join="left"): 2 -c dtype: object - For more examples, see :ref:`here `. + When `others` is a Series/Index/DataFrame, it is advisable + to use `to_numpy()` while passing it to the function to + avoid unexpected results. + + The following example demostrates this: + + If `others` is a Series/Index/DataFrame and `to_numpy()` + **is not** used: + + >>> idx = pd.Index(["a", "b", "c", "d", "e"]) + >>> ser = pd.Series(["f", "g", "h", "i", "j"]) + >>> idx.str.cat(ser) # the caller is an Index here + Index([nan, nan, nan, nan, nan], dtype='object') + + When `to_numpy()` **is** used: + + >>> idx.str.cat(ser.to_numpy()) + Index(['af', 'bg', 'ch', 'di', 'ej'], dtype='object') + + For other examples and usages, see + :ref:`here `. """ from pandas import Index, Series, concat