@@ -199,6 +199,75 @@ regular expression object will raise a ``ValueError``.
199
199
---------------------------------------------------------------------------
200
200
ValueError: case and flags cannot be set when pat is a compiled regex
201
201
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])
202
271
203
272
Indexing with ``.str ``
204
273
----------------------
0 commit comments