diff --git a/pandas/core/strings.py b/pandas/core/strings.py index 6b427ed1da834..d6ea5d0e4bf0d 100644 --- a/pandas/core/strings.py +++ b/pandas/core/strings.py @@ -51,11 +51,18 @@ def str_cat(arr, others=None, sep=None, na_rep=None): """ Concatenate strings in the Series/Index with given separator. + If `others` is specified, this function concatenates the Series/Index + and elements of `others` element-wise. + If `others` is not being passed then all values in the Series are + concatenated in a single string with a given `sep`. + Parameters ---------- - others : list-like, or list of list-likes - If None, returns str concatenating strings of the Series + others : list-like, or list of list-likes, optional + List-likes (or a list of them) of the same length as calling object. + If None, returns str concatenating strings of the Series. sep : string or None, default None + If None, concatenates without any separator. na_rep : string or None, default None If None, NA in the series are ignored. @@ -63,34 +70,37 @@ def str_cat(arr, others=None, sep=None, na_rep=None): ------- concat : Series/Index of objects or str + See Also + -------- + split : Split each string in the Series/Index + Examples -------- - When ``na_rep`` is `None` (default behavior), NaN value(s) - in the Series are ignored. + When not passing `other`, all values are concatenated into a single + string: - >>> Series(['a','b',np.nan,'c']).str.cat(sep=' ') + >>> s = pd.Series(['a', 'b', np.nan, 'c']) + >>> s.str.cat(sep=' ') 'a b c' - >>> Series(['a','b',np.nan,'c']).str.cat(sep=' ', na_rep='?') + By default, NA values in the Series are ignored. Using `na_rep`, they + can be given a representation: + + >>> pd.Series(['a', 'b', np.nan, 'c']).str.cat(sep=' ', na_rep='?') 'a b ? c' - If ``others`` is specified, corresponding values are + If `others` is specified, corresponding values are concatenated with the separator. Result will be a Series of strings. - >>> Series(['a', 'b', 'c']).str.cat(['A', 'B', 'C'], sep=',') + >>> pd.Series(['a', 'b', 'c']).str.cat(['A', 'B', 'C'], sep=',') 0 a,A 1 b,B 2 c,C dtype: object - Otherwise, strings in the Series are concatenated. Result will be a string. - - >>> Series(['a', 'b', 'c']).str.cat(sep=',') - 'a,b,c' - Also, you can pass a list of list-likes. - >>> Series(['a', 'b']).str.cat([['x', 'y'], ['1', '2']], sep=',') + >>> pd.Series(['a', 'b']).str.cat([['x', 'y'], ['1', '2']], sep=',') 0 a,x,1 1 b,y,2 dtype: object