Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/pandas/core/strings/accessor.py: 25%

1from __future__ import annotations

3import codecs

4from functools import wraps

5import re

6from typing import (

7 TYPE_CHECKING,

8 Literal,

9 cast,

10)

11import warnings

13import numpy as np

15from pandas._config import using_string_dtype

17from pandas._libs import lib

18from pandas._typing import (

19 AlignJoin,

20 DtypeObj,

21 F,

22 Scalar,

23 npt,

24)

25from pandas.util._exceptions import find_stack_level

27from pandas.core.dtypes.common import (

28 ensure_object,

29 is_bool_dtype,

30 is_extension_array_dtype,

31 is_integer,

32 is_list_like,

33 is_numeric_dtype,

34 is_object_dtype,

35 is_re,

36 is_string_dtype,

37)

38from pandas.core.dtypes.dtypes import (

39 ArrowDtype,

40 CategoricalDtype,

41)

42from pandas.core.dtypes.generic import (

43 ABCDataFrame,

44 ABCIndex,

45 ABCMultiIndex,

46 ABCSeries,

47)

48from pandas.core.dtypes.missing import isna

50from pandas.core.arrays import ExtensionArray

51from pandas.core.base import NoNewAttributesMixin

52from pandas.core.construction import extract_array

54if TYPE_CHECKING:

55 from collections.abc import (

56 Callable,

57 Hashable,

58 Iterator,

59 )

61 from pandas._typing import NpDtype

63 from pandas import (

64 DataFrame,

65 Index,

66 Series,

67 )

69_cpython_optimized_encoders = (

70 "utf-8",

71 "utf8",

72 "latin-1",

73 "latin1",

74 "iso-8859-1",

75 "mbcs",

76 "ascii",

77)

78_cpython_optimized_decoders = (*_cpython_optimized_encoders, "utf-16", "utf-32")

81def forbid_nonstring_types(

82 forbidden: list[str] | None, name: str | None = None

83) -> Callable[[F], F]:

84 """

85 Decorator to forbid specific types for a method of StringMethods.

87 For calling `.str.{method}` on a Series or Index, it is necessary to first

88 initialize the :class:`StringMethods` object, and then call the method.

89 However, different methods allow different input types, and so this can not

90 be checked during :meth:`StringMethods.__init__`, but must be done on a

91 per-method basis. This decorator exists to facilitate this process, and

92 make it explicit which (inferred) types are disallowed by the method.

94 :meth:`StringMethods.__init__` allows the *union* of types its different

95 methods allow (after skipping NaNs; see :meth:`StringMethods._validate`),

96 namely: ['string', 'empty', 'bytes', 'mixed', 'mixed-integer'].

98 The default string types ['string', 'empty'] are allowed for all methods.

99 For the additional types ['bytes', 'mixed', 'mixed-integer'], each method

100 then needs to forbid the types it is not intended for.

101

102 Parameters

103 ----------

104 forbidden : list-of-str or None

105 List of forbidden non-string types, may be one or more of

106 `['bytes', 'mixed', 'mixed-integer']`.

107 name : str, default None

108 Name of the method to use in the error message. By default, this is

109 None, in which case the name from the method being wrapped will be

110 copied. However, for working with further wrappers (like _pat_wrapper

111 and _noarg_wrapper), it is necessary to specify the name.

112

113 Returns

114 -------

115 func : wrapper

116 The method to which the decorator is applied, with an added check that

117 enforces the inferred type to not be in the list of forbidden types.

118

119 Raises

120 ------

121 TypeError

122 If the inferred type of the underlying data is in `forbidden`.

123 """

124 # deal with None

125 forbidden = [] if forbidden is None else forbidden

126

127 allowed_types = {"string", "empty", "bytes", "mixed", "mixed-integer"} - set(

128 forbidden

129 )

130

131 def _forbid_nonstring_types(func: F) -> F:

132 func_name = func.__name__ if name is None else name

133

134 @wraps(func)

135 def wrapper(self, *args, **kwargs):

136 if self._inferred_dtype not in allowed_types:

137 msg = (

138 f"Cannot use .str.{func_name} with values of "

139 f"inferred dtype '{self._inferred_dtype}'."

140 )

141 raise TypeError(msg)

142 return func(self, *args, **kwargs)

143

144 wrapper.__name__ = func_name

145 return cast(F, wrapper)

146

147 return _forbid_nonstring_types

148

149

150class StringMethods(NoNewAttributesMixin):

151 """

152 Vectorized string functions for Series and Index.

153

154 NAs stay NA unless handled otherwise by a particular method.

155 Patterned after Python's string methods, with some inspiration from

156 R's stringr package.

157

158 Parameters

159 ----------

160 data : Series or Index

161 The content of the Series or Index.

162

163 See Also

164 --------

165 Series.str : Vectorized string functions for Series.

166 Index.str : Vectorized string functions for Index.

167

168 Examples

169 --------

170 >>> s = pd.Series(["A_Str_Series"])

171 >>> s

172 0 A_Str_Series

173 dtype: str

174

175 >>> s.str.split("_")

176 0 [A, Str, Series]

177 dtype: object

178

179 >>> s.str.replace("_", "")

180 0 AStrSeries

181 dtype: str

182 """

183

184 # Note: see the docstring in pandas.core.strings.__init__

185 # for an explanation of the implementation.

186 # TODO: Dispatch all the methods

187 # Currently the following are not dispatched to the array

188 # * cat

189 # * extractall

190

191 def __init__(self, data) -> None:

192 from pandas.core.arrays.string_ import StringDtype

193

194 self._inferred_dtype = self._validate(data)

195 self._is_categorical = isinstance(data.dtype, CategoricalDtype)

196 self._is_string = isinstance(data.dtype, StringDtype)

197 self._data = data

198

199 self._index = self._name = None

200 if isinstance(data, ABCSeries):

201 self._index = data.index

202 self._name = data.name

203

204 # ._values.categories works for both Series/Index

205 self._parent = data._values.categories if self._is_categorical else data

206 # save orig to blow up categoricals to the right type

207 self._orig = data

208 self._freeze()

209

210 @staticmethod

211 def _validate(data):

212 """

213 Auxiliary function for StringMethods, infers and checks dtype of data.

214

215 This is a "first line of defence" at the creation of the StringMethods-

216 object, and just checks that the dtype is in the

217 *union* of the allowed types over all string methods below; this

218 restriction is then refined on a per-method basis using the decorator

219 @forbid_nonstring_types (more info in the corresponding docstring).

220

221 This really should exclude all series/index with any non-string values,

222 but that isn't practical for performance reasons until we have a str

223 dtype (GH 9343 / 13877)

224

225 Parameters

226 ----------

227 data : The content of the Series

228

229 Returns

230 -------

231 dtype : inferred dtype of data

232 """

233 if isinstance(data, ABCMultiIndex):

234 raise AttributeError(

235 "Can only use .str accessor with Index, not MultiIndex"

236 )

237

238 # see _libs/lib.pyx for list of inferred types

239 allowed_types = ["string", "empty", "bytes", "mixed", "mixed-integer"]

240

241 data = extract_array(data)

242

243 values = getattr(data, "categories", data) # categorical / normal

244

245 inferred_dtype = lib.infer_dtype(values, skipna=True)

246

247 if inferred_dtype not in allowed_types:

248 raise AttributeError(

249 f"Can only use .str accessor with string values, not {inferred_dtype}"

250 )

251 return inferred_dtype

252

253 def __getitem__(self, key):

254 result = self._data.array._str_getitem(key)

255 return self._wrap_result(result)

256

257 def __iter__(self) -> Iterator:

258 raise TypeError(f"'{type(self).__name__}' object is not iterable")

259

260 def _wrap_result(

261 self,

262 result,

263 name=None,

264 expand: bool | None = None,

265 fill_value=np.nan,

266 returns_string: bool = True,

267 dtype=None,

268 ):

269 from pandas import (

270 Index,

271 MultiIndex,

272 )

273

274 if not hasattr(result, "ndim") or not hasattr(result, "dtype"):

275 if isinstance(result, ABCDataFrame):

276 result = result.__finalize__(self._orig, name="str")

277 return result

278 assert result.ndim < 3

279

280 # We can be wrapping a string / object / categorical result, in which

281 # case we'll want to return the same dtype as the input.

282 # Or we can be wrapping a numeric output, in which case we don't want

283 # to return a StringArray.

284 # Ideally the array method returns the right array type.

285 if expand is None:

286 # infer from ndim if expand is not specified

287 expand = result.ndim != 1

288 elif expand is True and not isinstance(self._orig, ABCIndex):

289 # required when expand=True is explicitly specified

290 # not needed when inferred

291 if isinstance(result.dtype, ArrowDtype):

292 import pyarrow as pa

293

294 from pandas.core.arrays.arrow.array import ArrowExtensionArray

295

296 value_lengths = pa.compute.list_value_length(result._pa_array)

297 max_len = pa.compute.max(value_lengths).as_py()

298 min_len = pa.compute.min(value_lengths).as_py()

299 if result._hasna:

300 # ArrowExtensionArray.fillna doesn't work for list scalars

301 result = ArrowExtensionArray(

302 result._pa_array.fill_null([None] * max_len)

303 )

304 if min_len < max_len:

305 # append nulls to each scalar list element up to max_len

306 result = ArrowExtensionArray(

307 pa.compute.list_slice(

308 result._pa_array,

309 start=0,

310 stop=max_len,

311 return_fixed_size_list=True,

312 )

313 )

314 if name is None:

315 name = range(max_len)

316 result = (

317 pa.compute.list_flatten(result._pa_array)

318 .to_numpy()

319 .reshape(len(result), max_len)

320 )

321 result = {

322 label: ArrowExtensionArray(pa.array(res))

323 for label, res in zip(name, result.T, strict=True)

324 }

325 elif is_object_dtype(result):

326

327 def cons_row(x):

328 if is_list_like(x):

329 return x

330 else:

331 return [x]

332

333 result = [cons_row(x) for x in result]

334 if result and not self._is_string:

335 # propagate nan values to match longest sequence (GH 18450)

336 max_len = max(len(x) for x in result)

337 result = [

338 x * max_len if len(x) == 0 or x[0] is np.nan else x

339 for x in result

340 ]

341

342 if not isinstance(expand, bool):

343 raise ValueError("expand must be True or False")

344

345 if expand is False:

346 # if expand is False, result should have the same name

347 # as the original otherwise specified

348 if name is None:

349 name = getattr(result, "name", None)

350 if name is None:

351 # do not use logical or, _orig may be a DataFrame

352 # which has "name" column

353 name = self._orig.name

354

355 # Wait until we are sure result is a Series or Index before

356 # checking attributes (GH 12180)

357 if isinstance(self._orig, ABCIndex):

358 # if result is a boolean np.array, return the np.array

359 # instead of wrapping it into a boolean Index (GH 8875)

360 if is_bool_dtype(result):

361 return result

362

363 if expand:

364 result = list(result)

365 out: Index = MultiIndex.from_tuples(result, names=name)

366 if out.nlevels == 1:

367 # We had all tuples of length-one, which are

368 # better represented as a regular Index.

369 out = out.get_level_values(0)

370 return out

371 else:

372 return Index(result, name=name, dtype=dtype, copy=False)

373 else:

374 index = self._orig.index

375 # This is a mess.

376 _dtype: DtypeObj | str | None = dtype

377 vdtype = getattr(result, "dtype", None)

378 if _dtype is not None:

379 pass

380 elif self._is_string:

381 if is_bool_dtype(vdtype):

382 _dtype = result.dtype

383 elif returns_string:

384 _dtype = self._orig.dtype

385 else:

386 _dtype = vdtype

387 elif vdtype is not None:

388 _dtype = vdtype

389

390 if expand:

391 cons = self._orig._constructor_expanddim

392 result = cons(result, columns=name, index=index, dtype=_dtype)

393 else:

394 # Must be a Series

395 cons = self._orig._constructor

396 result = cons(result, name=name, index=index, dtype=_dtype)

397 result = result.__finalize__(self._orig, method="str")

398 if name is not None and result.ndim == 1:

399 # __finalize__ might copy over the original name, but we may

400 # want the new name (e.g. str.extract).

401 result.name = name

402 return result

403

404 def _get_series_list(self, others):

405 """

406 Auxiliary function for :meth:`str.cat`. Turn potentially mixed input

407 into a list of Series (elements without an index must match the length

408 of the calling Series/Index).

409

410 Parameters

411 ----------

412 others : Series, DataFrame, np.ndarray, list-like or list-like of

413 Objects that are either Series, Index or np.ndarray (1-dim).

414

415 Returns

416 -------

417 list of Series

418 Others transformed into list of Series.

419 """

420 from pandas import (

421 DataFrame,

422 Series,

423 )

424

425 # self._orig is either Series or Index

426 idx = self._orig if isinstance(self._orig, ABCIndex) else self._orig.index

427

428 # Generally speaking, all objects without an index inherit the index

429 # `idx` of the calling Series/Index - i.e. must have matching length.

430 # Objects with an index (i.e. Series/Index/DataFrame) keep their own.

431 if isinstance(others, ABCSeries):

432 return [others]

433 elif isinstance(others, ABCIndex):

434 return [Series(others, index=idx, dtype=others.dtype)]

435 elif isinstance(others, ABCDataFrame):

436 return [others[x] for x in others]

437 elif isinstance(others, np.ndarray) and others.ndim == 2:

438 others = DataFrame(others, index=idx)

439 return [others[x] for x in others]

440 elif is_list_like(others, allow_sets=False):

441 try:

442 others = list(others) # ensure iterators do not get read twice etc

443 except TypeError:

444 # e.g. ser.str, raise below

445 pass

446 else:

447 # in case of list-like `others`, all elements must be

448 # either Series/Index/np.ndarray (1-dim)...

449 if all(

450 isinstance(x, (ABCSeries, ABCIndex, ExtensionArray))

451 or (isinstance(x, np.ndarray) and x.ndim == 1)

452 for x in others

453 ):

454 los: list[Series] = []

455 while others: # iterate through list and append each element

456 los = los + self._get_series_list(others.pop(0))

457 return los

458 # ... or just strings

459 elif all(not is_list_like(x) for x in others):

460 return [Series(others, index=idx)]

461 raise TypeError(

462 "others must be Series, Index, DataFrame, np.ndarray "

463 "or list-like (either containing only strings or "

464 "containing only objects of type Series/Index/"

465 "np.ndarray[1-dim])"

466 )

467

468 @forbid_nonstring_types(["bytes", "mixed", "mixed-integer"])

469 def cat(

470 self,

471 others=None,

472 sep: str | None = None,

473 na_rep=None,

474 join: AlignJoin = "left",

475 ) -> str | Series | Index:

476 """

477 Concatenate strings in the Series/Index with given separator.

478

479 If `others` is specified, this function concatenates the Series/Index

480 and elements of `others` element-wise.

481 If `others` is not passed, then all values in the Series/Index are

482 concatenated into a single string with a given `sep`.

483

484 Parameters

485 ----------

486 others : Series, Index, DataFrame, np.ndarray or list-like

487 Series, Index, DataFrame, np.ndarray (one- or two-dimensional) and

488 other list-likes of strings must have the same length as the

489 calling Series/Index, with the exception of indexed objects (i.e.

490 Series/Index/DataFrame) if `join` is not None.

491

492 If others is a list-like that contains a combination of Series,

493 Index or np.ndarray (1-dim), then all elements will be unpacked and

494 must satisfy the above criteria individually.

495

496 If others is None, the method returns the concatenation of all

497 strings in the calling Series/Index.

498 sep : str, default ''

499 The separator between the different elements/columns. By default

500 the empty string `''` is used.

501 na_rep : str or None, default None

502 Representation that is inserted for all missing values:

503

504 - If `na_rep` is None, and `others` is None, missing values in the

505 Series/Index are omitted from the result.

506 - If `na_rep` is None, and `others` is not None, a row containing a

507 missing value in any of the columns (before concatenation) will

508 have a missing value in the result.

509 join : {'left', 'right', 'outer', 'inner'}, default 'left'

510 Determines the join-style between the calling Series/Index and any

511 Series/Index/DataFrame in `others` (objects without an index need

512 to match the length of the calling Series/Index). To disable

513 alignment, use `.values` on any Series/Index/DataFrame in `others`.

514

515 Returns

516 -------

517 str, Series or Index

518 If `others` is None, `str` is returned, otherwise a `Series/Index`

519 (same type as caller) of objects is returned.

520

521 See Also

522 --------

523 split : Split each string in the Series/Index.

524 join : Join lists contained as elements in the Series/Index.

525

526 Examples

527 --------

528 When not passing `others`, all values are concatenated into a single

529 string:

530

531 >>> s = pd.Series(["a", "b", np.nan, "d"])

532 >>> s.str.cat(sep=" ")

533 'a b d'

534

535 By default, NA values in the Series are ignored. Using `na_rep`, they

536 can be given a representation:

537

538 >>> s.str.cat(sep=" ", na_rep="?")

539 'a b ? d'

540

541 If `others` is specified, corresponding values are concatenated with

542 the separator. Result will be a Series of strings.

543

544 >>> s.str.cat(["A", "B", "C", "D"], sep=",")

545 0 a,A

546 1 b,B

547 2 NaN

548 3 d,D

549 dtype: str

550

551 Missing values will remain missing in the result, but can again be

552 represented using `na_rep`

553

554 >>> s.str.cat(["A", "B", "C", "D"], sep=",", na_rep="-")

555 0 a,A

556 1 b,B

557 2 -,C

558 3 d,D

559 dtype: str

560

561 If `sep` is not specified, the values are concatenated without

562 separation.

563

564 >>> s.str.cat(["A", "B", "C", "D"], na_rep="-")

565 0 aA

566 1 bB

567 2 -C

568 3 dD

569 dtype: str

570

571 Series with different indexes can be aligned before concatenation. The

572 `join`-keyword works as in other methods.

573

574 >>> t = pd.Series(["d", "a", "e", "c"], index=[3, 0, 4, 2])

575 >>> s.str.cat(t, join="left", na_rep="-")

576 0 aa

577 1 b-

578 2 -c

579 3 dd

580 dtype: str

581 >>>

582 >>> s.str.cat(t, join="outer", na_rep="-")

583 0 aa

584 1 b-

585 2 -c

586 3 dd

587 4 -e

588 dtype: str

589 >>>

590 >>> s.str.cat(t, join="inner", na_rep="-")

591 0 aa

592 2 -c

593 3 dd

594 dtype: str

595 >>>

596 >>> s.str.cat(t, join="right", na_rep="-")

597 3 dd

598 0 aa

599 4 -e

600 2 -c

601 dtype: str

602

603 For more examples, see :ref:`here <text.concatenate>`.

604 """

605 # TODO: dispatch

606 from pandas import (

607 Index,

608 Series,

609 concat,

610 )

611

612 if isinstance(others, str):

613 raise ValueError("Did you mean to supply a `sep` keyword?")

614 if sep is None:

615 sep = ""

616

617 if isinstance(self._orig, ABCIndex):

618 data = Series(self._orig, index=self._orig, dtype=self._orig.dtype)

619 else: # Series

620 data = self._orig

621

622 # concatenate Series/Index with itself if no "others"

623 if others is None:

624 # error: Incompatible types in assignment (expression has type

625 # "ndarray", variable has type "Series")

626 data = ensure_object(data) # type: ignore[assignment]

627 na_mask = isna(data)

628 if na_rep is None and na_mask.any():

629 return sep.join(data[~na_mask])

630 elif na_rep is not None and na_mask.any():

631 return sep.join(np.where(na_mask, na_rep, data))

632 else:

633 return sep.join(data)

634

635 try:

636 # turn anything in "others" into lists of Series

637 others = self._get_series_list(others)

638 except ValueError as err: # do not catch TypeError raised by _get_series_list

639 raise ValueError(

640 "If `others` contains arrays or lists (or other "

641 "list-likes without an index), these must all be "

642 "of the same length as the calling Series/Index."

643 ) from err

644

645 # align if required

646 if any(not data.index.equals(x.index) for x in others):

647 # Need to add keys for uniqueness in case of duplicate columns

648 others = concat(

649 others,

650 axis=1,

651 join=(join if join == "inner" else "outer"),

652 keys=range(len(others)),

653 sort=False,

654 )

655 data, others = data.align(others, join=join)

656 others = [others[x] for x in others] # again list of Series

657

658 all_cols = [ensure_object(x) for x in [data, *others]]

659 na_masks = np.array([isna(x) for x in all_cols])

660 union_mask = np.logical_or.reduce(na_masks, axis=0)

661

662 if na_rep is None and union_mask.any():

663 # no na_rep means NaNs for all rows where any column has a NaN

664 # only necessary if there are actually any NaNs

665 result = np.empty(len(data), dtype=object)

666 np.putmask(result, union_mask, np.nan)

667

668 not_masked = ~union_mask

669 result[not_masked] = cat_safe([x[not_masked] for x in all_cols], sep)

670 elif na_rep is not None and union_mask.any():

671 # fill NaNs with na_rep in case there are actually any NaNs

672 all_cols = [

673 np.where(nm, na_rep, col)

674 for nm, col in zip(na_masks, all_cols, strict=True)

675 ]

676 result = cat_safe(all_cols, sep)

677 else:

678 # no NaNs - can just concatenate

679 result = cat_safe(all_cols, sep)

680

681 out: Index | Series

682 if isinstance(self._orig.dtype, CategoricalDtype):

683 # We need to infer the new categories.

684 dtype = self._orig.dtype.categories.dtype

685 else:

686 dtype = self._orig.dtype

687 if isinstance(self._orig, ABCIndex):

688 # add dtype for case that result is all-NA

689 if isna(result).all():

690 dtype = object # type: ignore[assignment]

691

692 out = Index(result, dtype=dtype, name=self._orig.name, copy=False)

693 else: # Series

694 res_ser = Series(

695 result, dtype=dtype, index=data.index, name=self._orig.name, copy=False

696 )

697 out = res_ser.__finalize__(self._orig, method="str_cat")

698 return out

699

700 @forbid_nonstring_types(["bytes"])

701 def split(

702 self,

703 pat: str | re.Pattern | None = None,

704 *,

705 n=-1,

706 expand: bool = False,

707 regex: bool | None = None,

708 ):

709 r"""

710 Split strings around given separator/delimiter.

711

712 Splits the string in the Series/Index from the beginning,

713 at the specified delimiter string.

714

715 Parameters

716 ----------

717 pat : str or compiled regex, optional

718 String or regular expression to split on.

719 If not specified, split on whitespace.

720 n : int, default -1 (all)

721 Limit number of splits in output.

722 ``None``, 0 and -1 will be interpreted as return all splits.

723 expand : bool, default False

724 Expand the split strings into separate columns.

725

726 - If ``True``, return DataFrame/MultiIndex expanding dimensionality.

727 - If ``False``, return Series/Index, containing lists of strings.

728

729 regex : bool, default None

730 Determines if the passed-in pattern is a regular expression:

731

732 - If ``True``, assumes the passed-in pattern is a regular expression

733 - If ``False``, treats the pattern as a literal string.

734 - If ``None`` and `pat` length is 1, treats `pat` as a literal string.

735 - If ``None`` and `pat` length is not 1, treats `pat` as a regular

736 expression.

737 - Cannot be set to False if `pat` is a compiled regex

738

739 Returns

740 -------

741 Series, Index, DataFrame or MultiIndex

742 Type matches caller unless ``expand=True`` (see Notes).

743

744 Raises

745 ------

746 ValueError

747 * if `regex` is False and `pat` is a compiled regex

748

749 See Also

750 --------

751 Series.str.split : Split strings around given separator/delimiter.

752 Series.str.rsplit : Splits string around given separator/delimiter,

753 starting from the right.

754 Series.str.join : Join lists contained as elements in the Series/Index

755 with passed delimiter.

756 str.split : Standard library version for split.

757 str.rsplit : Standard library version for rsplit.

758

759 Notes

760 -----

761 The handling of the `n` keyword depends on the number of found splits:

762

763 - If found splits > `n`, make first `n` splits only

764 - If found splits <= `n`, make all splits

765 - If for a certain row the number of found splits < `n`,

766 append `None` for padding up to `n` if ``expand=True``

767

768 If using ``expand=True``, Series and Index callers return DataFrame and

769 MultiIndex objects, respectively.

770

771 Use of `regex =False` with a `pat` as a compiled regex will raise an error.

772

773 Examples

774 --------

775 >>> s = pd.Series(

776 ... [

777 ... "this is a regular sentence",

778 ... "https://docs.python.org/3/tutorial/index.html",

779 ... np.nan,

780 ... ]

781 ... )

782 >>> s

783 0 this is a regular sentence

784 1 https://docs.python.org/3/tutorial/index.html

785 2 NaN

786 dtype: str

787

788 In the default setting, the string is split by whitespace.

789

790 >>> s.str.split()

791 0 [this, is, a, regular, sentence]

792 1 [https://docs.python.org/3/tutorial/index.html]

793 2 NaN

794 dtype: object

795

796 Without the `n` parameter, the outputs of `rsplit` and `split`

797 are identical.

798

799 >>> s.str.rsplit()

800 0 [this, is, a, regular, sentence]

801 1 [https://docs.python.org/3/tutorial/index.html]

802 2 NaN

803 dtype: object

804

805 The `n` parameter can be used to limit the number of splits on the

806 delimiter. The outputs of `split` and `rsplit` are different.

807

808 >>> s.str.split(n=2)

809 0 [this, is, a regular sentence]

810 1 [https://docs.python.org/3/tutorial/index.html]

811 2 NaN

812 dtype: object

813

814 >>> s.str.rsplit(n=2)

815 0 [this is a, regular, sentence]

816 1 [https://docs.python.org/3/tutorial/index.html]

817 2 NaN

818 dtype: object

819

820 The `pat` parameter can be used to split by other characters.

821

822 >>> s.str.split(pat="/")

823 0 [this is a regular sentence]

824 1 [https:, , docs.python.org, 3, tutorial, index...

825 2 NaN

826 dtype: object

827

828 When using ``expand=True``, the split elements will expand out into

829 separate columns. If NaN is present, it is propagated throughout

830 the columns during the split.

831

832 >>> s.str.split(expand=True)

833 0 1 2 3 4

834 0 this is a regular sentence

835 1 https://docs.python.org/3/tutorial/index.html NaN NaN NaN NaN

836 2 NaN NaN NaN NaN NaN

837

838 For slightly more complex use cases like splitting the html document name

839 from a url, a combination of parameter settings can be used.

840

841 >>> s.str.rsplit("/", n=1, expand=True)

842 0 1

843 0 this is a regular sentence NaN

844 1 https://docs.python.org/3/tutorial index.html

845 2 NaN NaN

846

847 Remember to escape special characters when explicitly using regular expressions.

848

849 >>> s = pd.Series(["foo and bar plus baz"])

850 >>> s.str.split(r"and|plus", expand=True)

851 0 1 2

852 0 foo bar baz

853

854 Regular expressions can be used to handle urls or file names.

855 When `pat` is a string and ``regex=None`` (the default), the given `pat` is

856 compiled as a regex only if ``len(pat) != 1``.

857

858 >>> s = pd.Series(["foojpgbar.jpg"])

859 >>> s.str.split(r".", expand=True)

860 0 1

861 0 foojpgbar jpg

862

863 >>> s.str.split(r"\.jpg", expand=True)

864 0 1

865 0 foojpgbar

866

867 When ``regex=True``, `pat` is interpreted as a regex

868

869 >>> s.str.split(r"\.jpg", regex=True, expand=True)

870 0 1

871 0 foojpgbar

872

873 A compiled regex can be passed as `pat`

874

875 >>> import re

876 >>> s.str.split(re.compile(r"\.jpg"), expand=True)

877 0 1

878 0 foojpgbar

879

880 When ``regex=False``, `pat` is interpreted as the string itself

881

882 >>> s.str.split(r"\.jpg", regex=False, expand=True)

883 0

884 0 foojpgbar.jpg

885 """

886 if regex is False and is_re(pat):

887 raise ValueError(

888 "Cannot use a compiled regex as replacement pattern with regex=False"

889 )

890 if is_re(pat):

891 regex = True

892 result = self._data.array._str_split(pat, n, expand, regex)

893 if self._data.dtype == "category":

894 dtype = self._data.dtype.categories.dtype

895 else:

896 dtype = object if self._data.dtype == object else None

897 return self._wrap_result(

898 result, expand=expand, returns_string=expand, dtype=dtype

899 )

900

901 @forbid_nonstring_types(["bytes"])

902 def rsplit(self, pat=None, *, n=-1, expand: bool = False):

903 """

904 Split strings around given separator/delimiter.

905

906 Splits the string in the Series/Index from the end,

907 at the specified delimiter string.

908

909 Parameters

910 ----------

911 pat : str, optional

912 String to split on.

913 If not specified, split on whitespace.

914 n : int, default -1 (all)

915 Limit number of splits in output.

916 ``None``, 0 and -1 will be interpreted as return all splits.

917 expand : bool, default False

918 Expand the split strings into separate columns.

919

920 - If ``True``, return DataFrame/MultiIndex expanding dimensionality.

921 - If ``False``, return Series/Index, containing lists of strings.

922

923 Returns

924 -------

925 Series, Index, DataFrame or MultiIndex

926 Type matches caller unless ``expand=True`` (see Notes).

927

928 See Also

929 --------

930 Series.str.split : Split strings around given separator/delimiter.

931 Series.str.rsplit : Splits string around given separator/delimiter,

932 starting from the right.

933 Series.str.join : Join lists contained as elements in the Series/Index

934 with passed delimiter.

935 str.split : Standard library version for split.

936 str.rsplit : Standard library version for rsplit.

937

938 Notes

939 -----

940 The handling of the `n` keyword depends on the number of found splits:

941

942 - If found splits > `n`, make first `n` splits only

943 - If found splits <= `n`, make all splits

944 - If for a certain row the number of found splits < `n`,

945 append `None` for padding up to `n` if ``expand=True``

946

947 If using ``expand=True``, Series and Index callers return DataFrame and

948 MultiIndex objects, respectively.

949

950 Examples

951 --------

952 >>> s = pd.Series(

953 ... [

954 ... "this is a regular sentence",

955 ... "https://docs.python.org/3/tutorial/index.html",

956 ... np.nan,

957 ... ]

958 ... )

959 >>> s

960 0 this is a regular sentence

961 1 https://docs.python.org/3/tutorial/index.html

962 2 NaN

963 dtype: str

964

965 In the default setting, the string is split by whitespace.

966

967 >>> s.str.split()

968 0 [this, is, a, regular, sentence]

969 1 [https://docs.python.org/3/tutorial/index.html]

970 2 NaN

971 dtype: object

972

973 Without the `n` parameter, the outputs of `rsplit` and `split`

974 are identical.

975

976 >>> s.str.rsplit()

977 0 [this, is, a, regular, sentence]

978 1 [https://docs.python.org/3/tutorial/index.html]

979 2 NaN

980 dtype: object

981

982 The `n` parameter can be used to limit the number of splits on the

983 delimiter. The outputs of `split` and `rsplit` are different.

984

985 >>> s.str.split(n=2)

986 0 [this, is, a regular sentence]

987 1 [https://docs.python.org/3/tutorial/index.html]

988 2 NaN

989 dtype: object

990

991 >>> s.str.rsplit(n=2)

992 0 [this is a, regular, sentence]

993 1 [https://docs.python.org/3/tutorial/index.html]

994 2 NaN

995 dtype: object

996

997 The `pat` parameter can be used to split by other characters.

998

999 >>> s.str.split(pat="/")

1000 0 [this is a regular sentence]

1001 1 [https:, , docs.python.org, 3, tutorial, index...

1002 2 NaN

1003 dtype: object

1004

1005 When using ``expand=True``, the split elements will expand out into

1006 separate columns. If NaN is present, it is propagated throughout

1007 the columns during the split.

1008

1009 >>> s.str.split(expand=True)

1010 0 1 2 3 4

1011 0 this is a regular sentence

1012 1 https://docs.python.org/3/tutorial/index.html NaN NaN NaN NaN

1013 2 NaN NaN NaN NaN NaN

1014

1015 For slightly more complex use cases like splitting the html document name

1016 from a url, a combination of parameter settings can be used.

1017

1018 >>> s.str.rsplit("/", n=1, expand=True)

1019 0 1

1020 0 this is a regular sentence NaN

1021 1 https://docs.python.org/3/tutorial index.html

1022 2 NaN NaN

1023 """

1024 result = self._data.array._str_rsplit(pat, n=n)

1025 dtype = object if self._data.dtype == object else None

1026 return self._wrap_result(

1027 result, expand=expand, returns_string=expand, dtype=dtype

1028 )

1029

1030 @forbid_nonstring_types(["bytes"])

1031 def partition(self, sep: str = " ", expand: bool = True):

1032 """

1033 Split the string at the first occurrence of `sep`.

1034

1035 This method splits the string at the first occurrence of `sep`,

1036 and returns 3 elements containing the part before the separator,

1037 the separator itself, and the part after the separator.

1038 If the separator is not found, return 3 elements containing the string itself,

1039 followed by two empty strings.

1040

1041 Parameters

1042 ----------

1043 sep : str, default whitespace

1044 String to split on.

1045 expand : bool, default True

1046 If True, return DataFrame/MultiIndex expanding dimensionality.

1047 If False, return Series/Index.

1048

1049 Returns

1050 -------

1051 DataFrame/MultiIndex or Series/Index of objects

1052 Returns appropriate type based on `expand` parameter with strings

1053 split based on the `sep` parameter.

1054

1055 See Also

1056 --------

1057 rpartition : Split the string at the last occurrence of `sep`.

1058 Series.str.split : Split strings around given separators.

1059 str.partition : Standard library version.

1060

1061 Examples

1062 --------

1063 >>> s = pd.Series(["Linda van der Berg", "George Pitt-Rivers"])

1064 >>> s

1065 0 Linda van der Berg

1066 1 George Pitt-Rivers

1067 dtype: str

1068

1069 >>> s.str.partition()

1070 0 1 2

1071 0 Linda van der Berg

1072 1 George Pitt-Rivers

1073

1074 To partition by the last space instead of the first one:

1075

1076 >>> s.str.rpartition()

1077 0 1 2

1078 0 Linda van der Berg

1079 1 George Pitt-Rivers

1080

1081 To partition by something different than a space:

1082

1083 >>> s.str.partition("-")

1084 0 1 2

1085 0 Linda van der Berg

1086 1 George Pitt - Rivers

1087

1088 To return a Series containing tuples instead of a DataFrame:

1089

1090 >>> s.str.partition("-", expand=False)

1091 0 (Linda van der Berg, , )

1092 1 (George Pitt, -, Rivers)

1093 dtype: object

1094

1095 Also available on indices:

1096

1097 >>> idx = pd.Index(["X 123", "Y 999"])

1098 >>> idx

1099 Index(['X 123', 'Y 999'], dtype='str')

1100

1101 Which will create a MultiIndex:

1102

1103 >>> idx.str.partition()

1104 MultiIndex([('X', ' ', '123'),

1105 ('Y', ' ', '999')],

1106 )

1107

1108 Or an index with tuples with ``expand=False``:

1109

1110 >>> idx.str.partition(expand=False)

1111 Index([('X', ' ', '123'), ('Y', ' ', '999')], dtype='object')

1112 """

1113 result = self._data.array._str_partition(sep, expand)

1114 if self._data.dtype == "category":

1115 dtype = self._data.dtype.categories.dtype

1116 else:

1117 dtype = object if self._data.dtype == object else None

1118 return self._wrap_result(

1119 result, expand=expand, returns_string=expand, dtype=dtype

1120 )

1121

1122 @forbid_nonstring_types(["bytes"])

1123 def rpartition(self, sep: str = " ", expand: bool = True):

1124 """

1125 Split the string at the last occurrence of `sep`.

1126

1127 This method splits the string at the last occurrence of `sep`,

1128 and returns 3 elements containing the part before the separator,

1129 the separator itself, and the part after the separator.

1130 If the separator is not found, return 3 elements containing two empty strings,

1131 followed by the string itself.

1132

1133 Parameters

1134 ----------

1135 sep : str, default " "

1136 String to split on.

1137 expand : bool, default True

1138 If True, return DataFrame/MultiIndex expanding dimensionality.

1139 If False, return Series/Index.

1140

1141 Returns

1142 -------

1143 DataFrame/MultiIndex or Series/Index of objects

1144 Returns appropriate type based on `expand` parameter with strings

1145 split based on the `sep` parameter.

1146

1147 See Also

1148 --------

1149 partition : Split the string at the first occurrence of `sep`.

1150 Series.str.split : Split strings around given separators.

1151 str.partition : Standard library version.

1152

1153 Examples

1154 --------

1155 >>> s = pd.Series(["Linda van der Berg", "George Pitt-Rivers"])

1156 >>> s

1157 0 Linda van der Berg

1158 1 George Pitt-Rivers

1159 dtype: str

1160

1161 >>> s.str.partition()

1162 0 1 2

1163 0 Linda van der Berg

1164 1 George Pitt-Rivers

1165

1166 To partition by the last space instead of the first one:

1167

1168 >>> s.str.rpartition()

1169 0 1 2

1170 0 Linda van der Berg

1171 1 George Pitt-Rivers

1172

1173 To partition by something different than a space:

1174

1175 >>> s.str.partition("-")

1176 0 1 2

1177 0 Linda van der Berg

1178 1 George Pitt - Rivers

1179

1180 To return a Series containing tuples instead of a DataFrame:

1181

1182 >>> s.str.partition("-", expand=False)

1183 0 (Linda van der Berg, , )

1184 1 (George Pitt, -, Rivers)

1185 dtype: object

1186

1187 Also available on indices:

1188

1189 >>> idx = pd.Index(["X 123", "Y 999"])

1190 >>> idx

1191 Index(['X 123', 'Y 999'], dtype='str')

1192

1193 Which will create a MultiIndex:

1194

1195 >>> idx.str.partition()

1196 MultiIndex([('X', ' ', '123'),

1197 ('Y', ' ', '999')],

1198 )

1199

1200 Or an index with tuples with ``expand=False``:

1201

1202 >>> idx.str.partition(expand=False)

1203 Index([('X', ' ', '123'), ('Y', ' ', '999')], dtype='object')

1204 """

1205 result = self._data.array._str_rpartition(sep, expand)

1206 if self._data.dtype == "category":

1207 dtype = self._data.dtype.categories.dtype

1208 else:

1209 dtype = object if self._data.dtype == object else None

1210 return self._wrap_result(

1211 result, expand=expand, returns_string=expand, dtype=dtype

1212 )

1213

1214 def get(self, i):

1215 """

1216 Extract element from each component at specified position or with specified key.

1217

1218 Extract element from lists, tuples, dict, or strings in each element in the

1219 Series/Index.

1220

1221 Parameters

1222 ----------

1223 i : int or hashable dict label

1224 Position or key of element to extract.

1225

1226 Returns

1227 -------

1228 Series or Index

1229 Series or Index where each value is the extracted element from

1230 the corresponding input component.

1231

1232 See Also

1233 --------

1234 Series.str.extract : Extract capture groups in the regex as columns

1235 in a DataFrame.

1236

1237 Examples

1238 --------

1239 >>> s = pd.Series(

1240 ... [

1241 ... "String",

1242 ... (1, 2, 3),

1243 ... ["a", "b", "c"],

1244 ... 123,

1245 ... -456,

1246 ... {1: "Hello", "2": "World"},

1247 ... ]

1248 ... )

1249 >>> s

1250 0 String

1251 1 (1, 2, 3)

1252 2 [a, b, c]

1253 3 123

1254 4 -456

1255 5 {1: 'Hello', '2': 'World'}

1256 dtype: object

1257

1258 >>> s.str.get(1)

1259 0 t

1260 1 2

1261 2 b

1262 3 NaN

1263 4 NaN

1264 5 Hello

1265 dtype: object

1266

1267 >>> s.str.get(-1)

1268 0 g

1269 1 3

1270 2 c

1271 3 NaN

1272 4 NaN

1273 5 None

1274 dtype: object

1275

1276 Return element with given key

1277

1278 >>> s = pd.Series(

1279 ... [

1280 ... {"name": "Hello", "value": "World"},

1281 ... {"name": "Goodbye", "value": "Planet"},

1282 ... ]

1283 ... )

1284 >>> s.str.get("name")

1285 0 Hello

1286 1 Goodbye

1287 dtype: object

1288 """

1289 result = self._data.array._str_get(i)

1290 return self._wrap_result(result)

1291

1292 @forbid_nonstring_types(["bytes"])

1293 def join(self, sep: str):

1294 """

1295 Join lists contained as elements in the Series/Index with passed delimiter.

1296

1297 If the elements of a Series are lists themselves, join the content of these

1298 lists using the delimiter passed to the function.

1299 This function is an equivalent to :meth:`str.join`.

1300

1301 Parameters

1302 ----------

1303 sep : str

1304 Delimiter to use between list entries.

1305

1306 Returns

1307 -------

1308 Series/Index: object

1309 The list entries concatenated by intervening occurrences of the

1310 delimiter.

1311

1312 Raises

1313 ------

1314 AttributeError

1315 If the supplied Series contains neither strings nor lists.

1316

1317 See Also

1318 --------

1319 str.join : Standard library version of this method.

1320 Series.str.split : Split strings around given separator/delimiter.

1321

1322 Notes

1323 -----

1324 If any of the list items is not a string object, the result of the join

1325 will be `NaN`.

1326

1327 Examples

1328 --------

1329 Example with a list that contains non-string elements.

1330

1331 >>> s = pd.Series(

1332 ... [

1333 ... ["lion", "elephant", "zebra"],

1334 ... [1.1, 2.2, 3.3],

1335 ... ["cat", np.nan, "dog"],

1336 ... ["cow", 4.5, "goat"],

1337 ... ["duck", ["swan", "fish"], "guppy"],

1338 ... ]

1339 ... )

1340 >>> s

1341 0 [lion, elephant, zebra]

1342 1 [1.1, 2.2, 3.3]

1343 2 [cat, nan, dog]

1344 3 [cow, 4.5, goat]

1345 4 [duck, [swan, fish], guppy]

1346 dtype: object

1347

1348 Join all lists using a '-'. The lists containing object(s) of types other

1349 than str will produce a NaN.

1350

1351 >>> s.str.join("-")

1352 0 lion-elephant-zebra

1353 1 NaN

1354 2 NaN

1355 3 NaN

1356 4 NaN

1357 dtype: object

1358 """

1359 result = self._data.array._str_join(sep)

1360 return self._wrap_result(result)

1361

1362 @forbid_nonstring_types(["bytes"])

1363 def contains(

1364 self,

1365 pat,

1366 case: bool = True,

1367 flags: int = 0,

1368 na=lib.no_default,

1369 regex: bool = True,

1370 ):

1371 r"""

1372 Test if pattern or regex is contained within a string of a Series or Index.

1373

1374 Return boolean Series or Index based on whether a given pattern or regex is

1375 contained within a string of a Series or Index.

1376

1377 Parameters

1378 ----------

1379 pat : str

1380 Character sequence or regular expression.

1381 case : bool, default True

1382 If True, case sensitive.

1383 flags : int, default 0 (no flags)

1384 Flags to pass through to the re module, e.g. re.IGNORECASE.

1385 na : scalar, optional

1386 Fill value for missing values. The default depends on dtype of the

1387 array. For the ``"str"`` dtype, ``False`` is used. For object

1388 dtype, ``numpy.nan`` is used. For the nullable ``StringDtype``,

1389 ``pandas.NA`` is used.

1390 regex : bool, default True

1391 If True, assumes the pat is a regular expression.

1392

1393 If False, treats the pat as a literal string.

1394

1395 Returns

1396 -------

1397 Series or Index of boolean values

1398 A Series or Index of boolean values indicating whether the

1399 given pattern is contained within the string of each element

1400 of the Series or Index.

1401

1402 See Also

1403 --------

1404 match : Analogous, but stricter, relying on re.match instead of re.search.

1405 Series.str.startswith : Test if the start of each string element matches a

1406 pattern.

1407 Series.str.endswith : Same as startswith, but tests the end of string.

1408

1409 Examples

1410 --------

1411 Returning a Series of booleans using only a literal pattern.

1412

1413 >>> s1 = pd.Series(["Mouse", "dog", "house and parrot", "23", np.nan])

1414 >>> s1.str.contains("og", regex=False)

1415 0 False

1416 1 True

1417 2 False

1418 3 False

1419 4 False

1420 dtype: bool

1421

1422 Returning an Index of booleans using only a literal pattern.

1423

1424 >>> ind = pd.Index(["Mouse", "dog", "house and parrot", "23.0", np.nan])

1425 >>> ind.str.contains("23", regex=False)

1426 array([False, False, False, True, False])

1427

1428 Specifying case sensitivity using `case`.

1429

1430 >>> s1.str.contains("oG", case=True, regex=True)

1431 0 False

1432 1 False

1433 2 False

1434 3 False

1435 4 False

1436 dtype: bool

1437

1438 Returning 'house' or 'dog' when either expression occurs in a string.

1439

1440 >>> s1.str.contains("house|dog", regex=True)

1441 0 False

1442 1 True

1443 2 True

1444 3 False

1445 4 False

1446 dtype: bool

1447

1448 Ignoring case sensitivity using `flags` with regex.

1449

1450 >>> import re

1451 >>> s1.str.contains("PARROT", flags=re.IGNORECASE, regex=True)

1452 0 False

1453 1 False

1454 2 True

1455 3 False

1456 4 False

1457 dtype: bool

1458

1459 Returning any digit using regular expression.

1460

1461 >>> s1.str.contains("\\d", regex=True)

1462 0 False

1463 1 False

1464 2 False

1465 3 True

1466 4 False

1467 dtype: bool

1468

1469 Ensure `pat` is a not a literal pattern when `regex` is set to True.

1470 Note in the following example one might expect only `s2[1]` and `s2[3]` to

1471 return `True`. However, '.0' as a regex matches any character

1472 followed by a 0.

1473

1474 >>> s2 = pd.Series(["40", "40.0", "41", "41.0", "35"])

1475 >>> s2.str.contains(".0", regex=True)

1476 0 True

1477 1 True

1478 2 False

1479 3 True

1480 4 False

1481 dtype: bool

1482 """

1483 if regex:

1484 try:

1485 has_groups = re.compile(pat).groups

1486 except re.error:

1487 has_groups = False

1488 if has_groups:

1489 warnings.warn(

1490 "This pattern is interpreted as a regular expression, and has "

1491 "match groups. To actually get the groups, use str.extract.",

1492 UserWarning,

1493 stacklevel=find_stack_level(),

1494 )

1495

1496 result = self._data.array._str_contains(pat, case, flags, na, regex)

1497 return self._wrap_result(result, fill_value=na, returns_string=False)

1498

1499 @forbid_nonstring_types(["bytes"])

1500 def match(

1501 self,

1502 pat: str | re.Pattern,

1503 case: bool | lib.NoDefault = lib.no_default,

1504 flags: int | lib.NoDefault = lib.no_default,

1505 na=lib.no_default,

1506 ):

1507 """

1508 Determine if each string starts with a match of a regular expression.

1509

1510 Determines whether each string in the Series or Index starts with a

1511 match to a specified regular expression. This function is especially

1512 useful for validating prefixes, such as ensuring that codes, tags, or

1513 identifiers begin with a specific pattern.

1514

1515 Parameters

1516 ----------

1517 pat : str or compiled regex

1518 Character sequence or regular expression.

1519 case : bool, default True

1520 If True, case sensitive.

1521 flags : int, default 0 (no flags)

1522 Regex module flags, e.g. re.IGNORECASE.

1523 na : scalar, optional

1524 Fill value for missing values. The default depends on dtype of the

1525 array. For the ``"str"`` dtype, ``False`` is used. For object

1526 dtype, ``numpy.nan`` is used. For the nullable ``StringDtype``,

1527 ``pandas.NA`` is used.

1528

1529 Returns

1530 -------

1531 Series/Index/array of boolean values

1532 A Series, Index, or array of boolean values indicating whether the start

1533 of each string matches the pattern. The result will be of the same type

1534 as the input.

1535

1536 See Also

1537 --------

1538 fullmatch : Stricter matching that requires the entire string to match.

1539 contains : Analogous, but less strict, relying on re.search instead of

1540 re.match.

1541 extract : Extract matched groups.

1542

1543 Examples

1544 --------

1545 >>> ser = pd.Series(["horse", "eagle", "donkey"])

1546 >>> ser.str.match("e")

1547 0 False

1548 1 True

1549 2 False

1550 dtype: bool

1551 """

1552 if flags is not lib.no_default:

1553 # pat.flags will have re.U regardless, so we need to add it here

1554 # before checking for a match

1555 flags = flags | re.U

1556 if is_re(pat):

1557 if pat.flags != flags:

1558 raise ValueError(

1559 "Cannot both specify 'flags' and pass a compiled regexp "

1560 "object with conflicting flags"

1561 )

1562 else:

1563 pat = re.compile(pat, flags=flags)

1564 # set flags=0 to ensure that when we call

1565 # re.compile(pat, flags=flags) the constructor does not raise.

1566 flags = 0

1567 else:

1568 flags = 0

1569

1570 if case is lib.no_default:

1571 if is_re(pat):

1572 case = not bool(pat.flags & re.IGNORECASE)

1573 else:

1574 # Case-sensitive default

1575 case = True

1576 elif is_re(pat):

1577 implicit_case = not bool(pat.flags & re.IGNORECASE)

1578 if implicit_case != case:

1579 # GH#62240

1580 raise ValueError(

1581 "Cannot both specify 'case' and pass a compiled regexp "

1582 "object with conflicting case-sensitivity"

1583 )

1584

1585 result = self._data.array._str_match(pat, case=case, flags=flags, na=na)

1586 return self._wrap_result(result, fill_value=na, returns_string=False)

1587

1588 @forbid_nonstring_types(["bytes"])

1589 def fullmatch(self, pat, case: bool = True, flags: int = 0, na=lib.no_default):

1590 """

1591 Determine if each string entirely matches a regular expression.

1592

1593 Checks if each string in the Series or Index fully matches the

1594 specified regular expression pattern. This function is useful when the

1595 requirement is for an entire string to conform to a pattern, such as

1596 validating formats like phone numbers or email addresses.

1597

1598 Parameters

1599 ----------

1600 pat : str

1601 Character sequence or regular expression.

1602 case : bool, default True

1603 If True, case sensitive.

1604 flags : int, default 0 (no flags)

1605 Regex module flags, e.g. re.IGNORECASE.

1606 na : scalar, optional

1607 Fill value for missing values. The default depends on dtype of the

1608 array. For the ``"str"`` dtype, ``False`` is used. For object

1609 dtype, ``numpy.nan`` is used. For the nullable ``StringDtype``,

1610 ``pandas.NA`` is used.

1611

1612 Returns

1613 -------

1614 Series/Index/array of boolean values

1615 The function returns a Series, Index, or array of boolean values,

1616 where True indicates that the entire string matches the regular

1617 expression pattern and False indicates that it does not.

1618

1619 See Also

1620 --------

1621 match : Similar, but also returns `True` when only a *prefix* of the string

1622 matches the regular expression.

1623 extract : Extract matched groups.

1624

1625 Examples

1626 --------

1627 >>> ser = pd.Series(["cat", "duck", "dove"])

1628 >>> ser.str.fullmatch(r"d.+")

1629 0 False

1630 1 True

1631 2 True

1632 dtype: bool

1633 """

1634 result = self._data.array._str_fullmatch(pat, case=case, flags=flags, na=na)

1635 return self._wrap_result(result, fill_value=na, returns_string=False)

1636

1637 @forbid_nonstring_types(["bytes"])

1638 def replace(

1639 self,

1640 pat: str | re.Pattern | dict,

1641 repl: str | Callable | None = None,

1642 n: int = -1,

1643 case: bool | None = None,

1644 flags: int = 0,

1645 regex: bool = False,

1646 ):

1647 r"""

1648 Replace each occurrence of pattern/regex in the Series/Index.

1649

1650 Equivalent to :meth:`str.replace` or :func:`re.sub`, depending on

1651 the regex value.

1652

1653 Parameters

1654 ----------

1655 pat : str, compiled regex, or a dict

1656 String can be a character sequence or regular expression.

1657 Dictionary contains <key : value> pairs of strings to be replaced

1658 along with the updated value.

1659 repl : str or callable

1660 Replacement string or a callable. The callable is passed the regex

1661 match object and must return a replacement string to be used.

1662 Must have a value of None if `pat` is a dict

1663 See :func:`re.sub`.

1664 n : int, default -1 (all)

1665 Number of replacements to make from start.

1666 case : bool, default None

1667 Determines if replace is case sensitive:

1668

1669 - If True, case sensitive (the default if `pat` is a string)

1670 - Set to False for case insensitive

1671 - Cannot be set if `pat` is a compiled regex.

1672

1673 flags : int, default 0 (no flags)

1674 Regex module flags, e.g. re.IGNORECASE. Cannot be set if `pat` is a compiled

1675 regex.

1676 regex : bool, default False

1677 Determines if the passed-in pattern is a regular expression:

1678

1679 - If True, assumes the passed-in pattern is a regular expression.

1680 - If False, treats the pattern as a literal string

1681 - Cannot be set to False if `pat` is a compiled regex or `repl` is

1682 a callable.

1683

1684 Returns

1685 -------

1686 Series or Index of object

1687 A copy of the object with all matching occurrences of `pat` replaced by

1688 `repl`.

1689

1690 Raises

1691 ------

1692 ValueError

1693 * if `regex` is False and `repl` is a callable or `pat` is a compiled

1694 regex

1695 * if `pat` is a compiled regex and `case` or `flags` is set

1696 * if `pat` is a dictionary and `repl` is not None.

1697

1698 See Also

1699 --------

1700 Series.str.replace : Method to replace occurrences of a substring with another

1701 substring.

1702 Series.str.extract : Extract substrings using a regular expression.

1703 Series.str.findall : Find all occurrences of a pattern or regex in each string.

1704 Series.str.split : Split each string by a specified delimiter or pattern.

1705

1706 Notes

1707 -----

1708 When `pat` is a compiled regex, all flags should be included in the

1709 compiled regex. Use of `case`, `flags`, or `regex=False` with a compiled

1710 regex will raise an error.

1711

1712 Examples

1713 --------

1714 When `pat` is a dictionary, every key in `pat` is replaced

1715 with its corresponding value:

1716

1717 >>> pd.Series(["A", "B", np.nan]).str.replace(pat={"A": "a", "B": "b"})

1718 0 a

1719 1 b

1720 2 NaN

1721 dtype: str

1722

1723 When `pat` is a string and `regex` is True, the given `pat`

1724 is compiled as a regex. When `repl` is a string, it replaces matching

1725 regex patterns as with :meth:`re.sub`. NaN value(s) in the Series are

1726 left as is:

1727

1728 >>> pd.Series(["foo", "fuz", np.nan]).str.replace("f.", "ba", regex=True)

1729 0 bao

1730 1 baz

1731 2 NaN

1732 dtype: str

1733

1734 When `pat` is a string and `regex` is False, every `pat` is replaced with

1735 `repl` as with :meth:`str.replace`:

1736

1737 >>> pd.Series(["f.o", "fuz", np.nan]).str.replace("f.", "ba", regex=False)

1738 0 bao

1739 1 fuz

1740 2 NaN

1741 dtype: str

1742

1743 When `repl` is a callable, it is called on every `pat` using

1744 :func:`re.sub`. The callable should expect one positional argument

1745 (a regex object) and return a string.

1746

1747 To get the idea:

1748

1749 >>> pd.Series(["foo", "fuz", np.nan]).str.replace("f", repr, regex=True)

1750 0 <re.Match object; span=(0, 1), match='f'>oo

1751 1 <re.Match object; span=(0, 1), match='f'>uz

1752 2 NaN

1753 dtype: str

1754

1755 Reverse every lowercase alphabetic word:

1756

1757 >>> repl = lambda m: m.group(0)[::-1]

1758 >>> ser = pd.Series(["foo 123", "bar baz", np.nan])

1759 >>> ser.str.replace(r"[a-z]+", repl, regex=True)

1760 0 oof 123

1761 1 rab zab

1762 2 NaN

1763 dtype: str

1764

1765 Using regex groups (extract second group and swap case):

1766

1767 >>> pat = r"(?P<one>\w+) (?P<two>\w+) (?P<three>\w+)"

1768 >>> repl = lambda m: m.group("two").swapcase()

1769 >>> ser = pd.Series(["One Two Three", "Foo Bar Baz"])

1770 >>> ser.str.replace(pat, repl, regex=True)

1771 0 tWO

1772 1 bAR

1773 dtype: str

1774

1775 Using a compiled regex with flags

1776

1777 >>> import re

1778 >>> regex_pat = re.compile(r"FUZ", flags=re.IGNORECASE)

1779 >>> pd.Series(["foo", "fuz", np.nan]).str.replace(regex_pat, "bar", regex=True)

1780 0 foo

1781 1 bar

1782 2 NaN

1783 dtype: str

1784 """

1785 if isinstance(pat, dict) and repl is not None:

1786 raise ValueError("repl cannot be used when pat is a dictionary")

1787

1788 # Check whether repl is valid (GH 13438, GH 15055)

1789 if not isinstance(pat, dict) and not (isinstance(repl, str) or callable(repl)):

1790 raise TypeError("repl must be a string or callable")

1791

1792 is_compiled_re = is_re(pat)

1793 if regex or regex is None:

1794 if is_compiled_re and (case is not None or flags != 0):

1795 raise ValueError(

1796 "case and flags cannot be set when pat is a compiled regex"

1797 )

1798

1799 elif is_compiled_re:

1800 raise ValueError(

1801 "Cannot use a compiled regex as replacement pattern with regex=False"

1802 )

1803 elif callable(repl):

1804 raise ValueError("Cannot use a callable replacement when regex=False")

1805

1806 if case is None:

1807 case = True

1808

1809 res_output = self._data

1810 if not isinstance(pat, dict):

1811 pat = {pat: repl}

1812

1813 for key, value in pat.items():

1814 result = res_output.array._str_replace(

1815 key, value, n=n, case=case, flags=flags, regex=regex

1816 )

1817 res_output = self._wrap_result(result)

1818

1819 return res_output

1820

1821 @forbid_nonstring_types(["bytes"])

1822 def repeat(self, repeats):

1823 """

1824 Duplicate each string in the Series or Index.

1825

1826 Duplicates each string in the Series or Index, either by applying the

1827 same repeat count to all elements or by using different repeat values

1828 for each element.

1829

1830 Parameters

1831 ----------

1832 repeats : int or sequence of int

1833 Same value for all (int) or different value per (sequence).

1834

1835 Returns

1836 -------

1837 Series or pandas.Index

1838 Series or Index of repeated string objects specified by

1839 input parameter repeats.

1840

1841 See Also

1842 --------

1843 Series.str.lower : Convert all characters in each string to lowercase.

1844 Series.str.upper : Convert all characters in each string to uppercase.

1845 Series.str.title : Convert each string to title case (capitalizing the first

1846 letter of each word).

1847 Series.str.strip : Remove leading and trailing whitespace from each string.

1848 Series.str.replace : Replace occurrences of a substring with another substring

1849 in each string.

1850 Series.str.ljust : Left-justify each string in the Series/Index by padding with

1851 a specified character.

1852 Series.str.rjust : Right-justify each string in the Series/Index by padding with

1853 a specified character.

1854

1855 Examples

1856 --------

1857 >>> s = pd.Series(["a", "b", "c"])

1858 >>> s

1859 0 a

1860 1 b

1861 2 c

1862 dtype: str

1863

1864 Single int repeats string in Series

1865

1866 >>> s.str.repeat(repeats=2)

1867 0 aa

1868 1 bb

1869 2 cc

1870 dtype: str

1871

1872 Sequence of int repeats corresponding string in Series

1873

1874 >>> s.str.repeat(repeats=[1, 2, 3])

1875 0 a

1876 1 bb

1877 2 ccc

1878 dtype: str

1879 """

1880 result = self._data.array._str_repeat(repeats)

1881 return self._wrap_result(result)

1882

1883 @forbid_nonstring_types(["bytes"])

1884 def pad(

1885 self,

1886 width: int,

1887 side: Literal["left", "right", "both"] = "left",

1888 fillchar: str = " ",

1889 ):

1890 """

1891 Pad strings in the Series/Index up to width.

1892

1893 This function pads strings in a Series or Index to a specified width,

1894 filling the extra space with a character of your choice. It provides

1895 flexibility in positioning the padding, allowing it to be added to the

1896 left, right, or both sides. This is useful for formatting strings to

1897 align text or ensure consistent string lengths in data processing.

1898

1899 Parameters

1900 ----------

1901 width : int

1902 Minimum width of resulting string; additional characters will be filled

1903 with character defined in `fillchar`.

1904 side : {'left', 'right', 'both'}, default 'left'

1905 Side from which to fill resulting string.

1906 fillchar : str, default ' '

1907 Additional character for filling, default is whitespace.

1908

1909 Returns

1910 -------

1911 Series or Index of object

1912 Returns Series or Index with minimum number of char in object.

1913

1914 See Also

1915 --------

1916 Series.str.rjust : Fills the left side of strings with an arbitrary

1917 character. Equivalent to ``Series.str.pad(side='left')``.

1918 Series.str.ljust : Fills the right side of strings with an arbitrary

1919 character. Equivalent to ``Series.str.pad(side='right')``.

1920 Series.str.center : Fills both sides of strings with an arbitrary

1921 character. Equivalent to ``Series.str.pad(side='both')``.

1922 Series.str.zfill : Pad strings in the Series/Index by prepending '0'

1923 character. Equivalent to ``Series.str.pad(side='left', fillchar='0')``.

1924

1925 Examples

1926 --------

1927 >>> s = pd.Series(["caribou", "tiger"])

1928 >>> s

1929 0 caribou

1930 1 tiger

1931 dtype: str

1932

1933 >>> s.str.pad(width=10)

1934 0 caribou

1935 1 tiger

1936 dtype: str

1937

1938 >>> s.str.pad(width=10, side="right", fillchar="-")

1939 0 caribou---

1940 1 tiger-----

1941 dtype: str

1942

1943 >>> s.str.pad(width=10, side="both", fillchar="-")

1944 0 -caribou--

1945 1 --tiger---

1946 dtype: str

1947 """

1948 if not isinstance(fillchar, str):

1949 msg = f"fillchar must be a character, not {type(fillchar).__name__}"

1950 raise TypeError(msg)

1951

1952 if len(fillchar) != 1:

1953 raise TypeError("fillchar must be a character, not str")

1954

1955 if not is_integer(width):

1956 msg = f"width must be of integer type, not {type(width).__name__}"

1957 raise TypeError(msg)

1958

1959 result = self._data.array._str_pad(width, side=side, fillchar=fillchar)

1960 return self._wrap_result(result)

1961

1962 @forbid_nonstring_types(["bytes"])

1963 def center(self, width: int, fillchar: str = " "):

1964 """

1965 Pad left and right side of strings in the Series/Index.

1966

1967 Equivalent to :meth:`str.center`.

1968

1969 Parameters

1970 ----------

1971 width : int

1972 Minimum width of resulting string; additional characters will be filled

1973 with ``fillchar``.

1974 fillchar : str

1975 Additional character for filling, default is whitespace.

1976

1977 Returns

1978 -------

1979 Series/Index of objects.

1980 A Series or Index where the strings are modified by :meth:`str.center`.

1981

1982 See Also

1983 --------

1984 Series.str.rjust : Fills the left side of strings with an arbitrary

1985 character.

1986 Series.str.ljust : Fills the right side of strings with an arbitrary

1987 character.

1988 Series.str.center : Fills both sides of strings with an arbitrary

1989 character.

1990 Series.str.zfill : Pad strings in the Series/Index by prepending '0'

1991 character.

1992

1993 Examples

1994 --------

1995 For Series.str.center:

1996

1997 >>> ser = pd.Series(["dog", "bird", "mouse"])

1998 >>> ser.str.center(8, fillchar=".")

1999 0 ..dog...

2000 1 ..bird..

2001 2 .mouse..

2002 dtype: str

2003

2004 For Series.str.ljust:

2005

2006 >>> ser = pd.Series(["dog", "bird", "mouse"])

2007 >>> ser.str.ljust(8, fillchar=".")

2008 0 dog.....

2009 1 bird....

2010 2 mouse...

2011 dtype: str

2012

2013 For Series.str.rjust:

2014

2015 >>> ser = pd.Series(["dog", "bird", "mouse"])

2016 >>> ser.str.rjust(8, fillchar=".")

2017 0 .....dog

2018 1 ....bird

2019 2 ...mouse

2020 dtype: str

2021 """

2022 return self.pad(width, side="both", fillchar=fillchar)

2023

2024 @forbid_nonstring_types(["bytes"])

2025 def ljust(self, width: int, fillchar: str = " "):

2026 """

2027 Pad right side of strings in the Series/Index.

2028

2029 Equivalent to :meth:`str.ljust`.

2030

2031 Parameters

2032 ----------

2033 width : int

2034 Minimum width of resulting string; additional characters will be filled

2035 with ``fillchar``.

2036 fillchar : str

2037 Additional character for filling, default is whitespace.

2038

2039 Returns

2040 -------

2041 Series/Index of objects.

2042 A Series or Index where the strings are modified by :meth:`str.ljust`.

2043

2044 See Also

2045 --------

2046 Series.str.rjust : Fills the left side of strings with an arbitrary

2047 character.

2048 Series.str.ljust : Fills the right side of strings with an arbitrary

2049 character.

2050 Series.str.center : Fills both sides of strings with an arbitrary

2051 character.

2052 Series.str.zfill : Pad strings in the Series/Index by prepending '0'

2053 character.

2054

2055 Examples

2056 --------

2057 For Series.str.center:

2058

2059 >>> ser = pd.Series(["dog", "bird", "mouse"])

2060 >>> ser.str.center(8, fillchar=".")

2061 0 ..dog...

2062 1 ..bird..

2063 2 .mouse..

2064 dtype: str

2065

2066 For Series.str.ljust:

2067

2068 >>> ser = pd.Series(["dog", "bird", "mouse"])

2069 >>> ser.str.ljust(8, fillchar=".")

2070 0 dog.....

2071 1 bird....

2072 2 mouse...

2073 dtype: str

2074

2075 For Series.str.rjust:

2076

2077 >>> ser = pd.Series(["dog", "bird", "mouse"])

2078 >>> ser.str.rjust(8, fillchar=".")

2079 0 .....dog

2080 1 ....bird

2081 2 ...mouse

2082 dtype: str

2083 """

2084 return self.pad(width, side="right", fillchar=fillchar)

2085

2086 @forbid_nonstring_types(["bytes"])

2087 def rjust(self, width: int, fillchar: str = " "):

2088 """

2089 Pad left side of strings in the Series/Index.

2090

2091 Equivalent to :meth:`str.rjust`.

2092

2093 Parameters

2094 ----------

2095 width : int

2096 Minimum width of resulting string; additional characters will be filled

2097 with ``fillchar``.

2098 fillchar : str

2099 Additional character for filling, default is whitespace.

2100

2101 Returns

2102 -------

2103 Series/Index of objects.

2104 A Series or Index where the strings are modified by :meth:`str.rjust`.

2105

2106 See Also

2107 --------

2108 Series.str.rjust : Fills the left side of strings with an arbitrary

2109 character.

2110 Series.str.ljust : Fills the right side of strings with an arbitrary

2111 character.

2112 Series.str.center : Fills both sides of strings with an arbitrary

2113 character.

2114 Series.str.zfill : Pad strings in the Series/Index by prepending '0'

2115 character.

2116

2117 Examples

2118 --------

2119 For Series.str.center:

2120

2121 >>> ser = pd.Series(["dog", "bird", "mouse"])

2122 >>> ser.str.center(8, fillchar=".")

2123 0 ..dog...

2124 1 ..bird..

2125 2 .mouse..

2126 dtype: str

2127

2128 For Series.str.ljust:

2129

2130 >>> ser = pd.Series(["dog", "bird", "mouse"])

2131 >>> ser.str.ljust(8, fillchar=".")

2132 0 dog.....

2133 1 bird....

2134 2 mouse...

2135 dtype: str

2136

2137 For Series.str.rjust:

2138

2139 >>> ser = pd.Series(["dog", "bird", "mouse"])

2140 >>> ser.str.rjust(8, fillchar=".")

2141 0 .....dog

2142 1 ....bird

2143 2 ...mouse

2144 dtype: str

2145 """

2146 return self.pad(width, side="left", fillchar=fillchar)

2147

2148 @forbid_nonstring_types(["bytes"])

2149 def zfill(self, width: int):

2150 """

2151 Pad strings in the Series/Index by prepending '0' characters.

2152

2153 Strings in the Series/Index are padded with '0' characters on the

2154 left of the string to reach a total string length `width`. Strings

2155 in the Series/Index with length greater or equal to `width` are

2156 unchanged.

2157

2158 Parameters

2159 ----------

2160 width : int

2161 Minimum length of resulting string; strings with length less

2162 than `width` be prepended with '0' characters.

2163

2164 Returns

2165 -------

2166 Series/Index of objects.

2167 A Series or Index where the strings are prepended with '0' characters.

2168

2169 See Also

2170 --------

2171 Series.str.rjust : Fills the left side of strings with an arbitrary

2172 character.

2173 Series.str.ljust : Fills the right side of strings with an arbitrary

2174 character.

2175 Series.str.pad : Fills the specified sides of strings with an arbitrary

2176 character.

2177 Series.str.center : Fills both sides of strings with an arbitrary

2178 character.

2179

2180 Notes

2181 -----

2182 Differs from :meth:`str.zfill` which has special handling

2183 for '+'/'-' in the string.

2184

2185 Examples

2186 --------

2187 >>> s = pd.Series(["-1", "1", "1000", 10, np.nan])

2188 >>> s

2189 0 -1

2190 1 1

2191 2 1000

2192 3 10

2193 4 NaN

2194 dtype: object

2195

2196 Note that ``10`` and ``NaN`` are not strings, therefore they are

2197 converted to ``NaN``. The minus sign in ``'-1'`` is treated as a

2198 special character and the zero is added to the right of it

2199 (:meth:`str.zfill` would have moved it to the left). ``1000``

2200 remains unchanged as it is longer than `width`.

2201

2202 >>> s.str.zfill(3)

2203 0 -01

2204 1 001

2205 2 1000

2206 3 NaN

2207 4 NaN

2208 dtype: object

2209 """

2210 if not is_integer(width):

2211 msg = f"width must be of integer type, not {type(width).__name__}"

2212 raise TypeError(msg)

2213

2214 result = self._data.array._str_zfill(width)

2215 return self._wrap_result(result)

2216

2217 def slice(self, start=None, stop=None, step=None):

2218 """

2219 Slice substrings from each element in the Series or Index.

2220

2221 Slicing substrings from strings in a Series or Index helps extract

2222 specific portions of data, making it easier to analyze or manipulate

2223 text. This is useful for tasks like parsing structured text fields or

2224 isolating parts of strings with a consistent format.

2225

2226 Parameters

2227 ----------

2228 start : int, optional

2229 Start position for slice operation.

2230 stop : int, optional

2231 Stop position for slice operation.

2232 step : int, optional

2233 Step size for slice operation.

2234

2235 Returns

2236 -------

2237 Series or Index of object

2238 Series or Index from sliced substring from original string object.

2239

2240 See Also

2241 --------

2242 Series.str.slice_replace : Replace a slice with a string.

2243 Series.str.get : Return element at position.

2244 Equivalent to `Series.str.slice(start=i, stop=i+1)` with `i`

2245 being the position.

2246

2247 Examples

2248 --------

2249 >>> s = pd.Series(["koala", "dog", "chameleon"])

2250 >>> s

2251 0 koala

2252 1 dog

2253 2 chameleon

2254 dtype: str

2255

2256 >>> s.str.slice(start=1)

2257 0 oala

2258 1 og

2259 2 hameleon

2260 dtype: str

2261

2262 >>> s.str.slice(start=-1)

2263 0 a

2264 1 g

2265 2 n

2266 dtype: str

2267

2268 >>> s.str.slice(stop=2)

2269 0 ko

2270 1 do

2271 2 ch

2272 dtype: str

2273

2274 >>> s.str.slice(step=2)

2275 0 kaa

2276 1 dg

2277 2 caeen

2278 dtype: str

2279

2280 >>> s.str.slice(start=0, stop=5, step=3)

2281 0 kl

2282 1 d

2283 2 cm

2284 dtype: str

2285

2286 Equivalent behaviour to:

2287

2288 >>> s.str[0:5:3]

2289 0 kl

2290 1 d

2291 2 cm

2292 dtype: str

2293 """

2294 result = self._data.array._str_slice(start, stop, step)

2295 return self._wrap_result(result)

2296

2297 @forbid_nonstring_types(["bytes"])

2298 def slice_replace(self, start=None, stop=None, repl=None):

2299 """

2300 Replace a positional slice of a string with another value.

2301

2302 This function allows replacing specific parts of a string in a Series

2303 or Index by specifying start and stop positions. It is useful for

2304 modifying substrings in a controlled way, such as updating sections of

2305 text based on their positions or patterns.

2306

2307 Parameters

2308 ----------

2309 start : int, optional

2310 Left index position to use for the slice. If not specified (None),

2311 the slice is unbounded on the left, i.e. slice from the start

2312 of the string.

2313 stop : int, optional

2314 Right index position to use for the slice. If not specified (None),

2315 the slice is unbounded on the right, i.e. slice until the

2316 end of the string.

2317 repl : str, optional

2318 String for replacement. If not specified (None), the sliced region

2319 is replaced with an empty string.

2320

2321 Returns

2322 -------

2323 Series or Index

2324 Same type as the original object.

2325

2326 See Also

2327 --------

2328 Series.str.slice : Just slicing without replacement.

2329

2330 Examples

2331 --------

2332 >>> s = pd.Series(["a", "ab", "abc", "abdc", "abcde"])

2333 >>> s

2334 0 a

2335 1 ab

2336 2 abc

2337 3 abdc

2338 4 abcde

2339 dtype: str

2340

2341 Specify just `start`, meaning replace `start` until the end of the

2342 string with `repl`.

2343

2344 >>> s.str.slice_replace(1, repl="X")

2345 0 aX

2346 1 aX

2347 2 aX

2348 3 aX

2349 4 aX

2350 dtype: str

2351

2352 Specify just `stop`, meaning the start of the string to `stop` is replaced

2353 with `repl`, and the rest of the string is included.

2354

2355 >>> s.str.slice_replace(stop=2, repl="X")

2356 0 X

2357 1 X

2358 2 Xc

2359 3 Xdc

2360 4 Xcde

2361 dtype: str

2362

2363 Specify `start` and `stop`, meaning the slice from `start` to `stop` is

2364 replaced with `repl`. Everything before or after `start` and `stop` is

2365 included as is.

2366

2367 >>> s.str.slice_replace(start=1, stop=3, repl="X")

2368 0 aX

2369 1 aX

2370 2 aX

2371 3 aXc

2372 4 aXde

2373 dtype: str

2374 """

2375 result = self._data.array._str_slice_replace(start, stop, repl)

2376 return self._wrap_result(result)

2377

2378 def decode(

2379 self, encoding, errors: str = "strict", dtype: str | DtypeObj | None = None

2380 ):

2381 """

2382 Decode character string in the Series/Index using indicated encoding.

2383

2384 Equivalent to :meth:`str.decode` in python2 and :meth:`bytes.decode` in

2385 python3.

2386

2387 Parameters

2388 ----------

2389 encoding : str

2390 Specifies the encoding to be used.

2391 errors : str, optional

2392 Specifies the error handling scheme.

2393 Possible values are those supported by :meth:`bytes.decode`.

2394 dtype : str or dtype, optional

2395 The dtype of the result. When not ``None``, must be either a string or

2396 object dtype. When ``None``, the dtype of the result is determined by

2397 ``pd.options.future.infer_string``.

2398

2399 .. versionadded:: 2.3.0

2400

2401 Returns

2402 -------

2403 Series or Index

2404 A Series or Index with decoded strings.

2405

2406 See Also

2407 --------

2408 Series.str.encode : Encodes strings into bytes in a Series/Index.

2409

2410 Examples

2411 --------

2412 For Series:

2413

2414 >>> ser = pd.Series([b"cow", b"123", b"()"])

2415 >>> ser.str.decode("ascii")

2416 0 cow

2417 1 123

2418 2 ()

2419 dtype: str

2420 """

2421 if dtype is not None and not is_string_dtype(dtype):

2422 raise ValueError(f"dtype must be string or object, got {dtype=}")

2423 if dtype is None and using_string_dtype():

2424 dtype = "str"

2425 # TODO: Add a similar _bytes interface.

2426 if encoding in _cpython_optimized_decoders:

2427 # CPython optimized implementation

2428 f = lambda x: x.decode(encoding, errors)

2429 else:

2430 decoder = codecs.getdecoder(encoding)

2431 f = lambda x: decoder(x, errors)[0]

2432 arr = self._data.array

2433 result = arr._str_map(f)

2434 return self._wrap_result(result, dtype=dtype)

2435

2436 @forbid_nonstring_types(["bytes"])

2437 def encode(self, encoding, errors: str = "strict"):

2438 """

2439 Encode character string in the Series/Index using indicated encoding.

2440

2441 Equivalent to :meth:`str.encode`.

2442

2443 Parameters

2444 ----------

2445 encoding : str

2446 Specifies the encoding to be used.

2447 errors : str, optional

2448 Specifies the error handling scheme.

2449 Possible values are those supported by :meth:`str.encode`.

2450

2451 Returns

2452 -------

2453 Series/Index of objects

2454 A Series or Index with strings encoded into bytes.

2455

2456 See Also

2457 --------

2458 Series.str.decode : Decodes bytes into strings in a Series/Index.

2459

2460 Examples

2461 --------

2462 >>> ser = pd.Series(["cow", "123", "()"])

2463 >>> ser.str.encode(encoding="ascii")

2464 0 b'cow'

2465 1 b'123'

2466 2 b'()'

2467 dtype: object

2468 """

2469 result = self._data.array._str_encode(encoding, errors)

2470 return self._wrap_result(result, returns_string=False)

2471

2472 @forbid_nonstring_types(["bytes"])

2473 def strip(self, to_strip=None):

2474 """

2475 Remove leading and trailing characters.

2476

2477 Strip whitespaces (including newlines) or a set of specified characters

2478 from each string in the Series/Index from left and right sides.

2479 Replaces any non-strings in Series with NaNs.

2480 Equivalent to :meth:`str.strip`.

2481

2482 Parameters

2483 ----------

2484 to_strip : str or None, default None

2485 Specifying the set of characters to be removed.

2486 All combinations of this set of characters will be stripped.

2487 If None then whitespaces are removed.

2488

2489 Returns

2490 -------

2491 Series or Index of object

2492 Series or Index with the strings being stripped from the left and

2493 right sides.

2494

2495 See Also

2496 --------

2497 Series.str.strip : Remove leading and trailing characters in Series/Index.

2498 Series.str.lstrip : Remove leading characters in Series/Index.

2499 Series.str.rstrip : Remove trailing characters in Series/Index.

2500

2501 Examples

2502 --------

2503 >>> s = pd.Series(["1. Ant. ", "2. Bee!\\n", "3. Cat?\\t", np.nan, 10, True])

2504 >>> s

2505 0 1. Ant.

2506 1 2. Bee!\\n

2507 2 3. Cat?\\t

2508 3 NaN

2509 4 10

2510 5 True

2511 dtype: object

2512

2513 >>> s.str.strip()

2514 0 1. Ant.

2515 1 2. Bee!

2516 2 3. Cat?

2517 3 NaN

2518 4 NaN

2519 5 NaN

2520 dtype: object

2521

2522 >>> s.str.lstrip("123.")

2523 0 Ant.

2524 1 Bee!\\n

2525 2 Cat?\\t

2526 3 NaN

2527 4 NaN

2528 5 NaN

2529 dtype: object

2530

2531 >>> s.str.rstrip(".!? \\n\\t")

2532 0 1. Ant

2533 1 2. Bee

2534 2 3. Cat

2535 3 NaN

2536 4 NaN

2537 5 NaN

2538 dtype: object

2539

2540 >>> s.str.strip("123.!? \\n\\t")

2541 0 Ant

2542 1 Bee

2543 2 Cat

2544 3 NaN

2545 4 NaN

2546 5 NaN

2547 dtype: object

2548 """

2549 result = self._data.array._str_strip(to_strip)

2550 return self._wrap_result(result)

2551

2552 @forbid_nonstring_types(["bytes"])

2553 def lstrip(self, to_strip=None):

2554 """

2555 Remove leading characters.

2556

2557 Strip whitespaces (including newlines) or a set of specified characters

2558 from each string in the Series/Index from left side.

2559 Replaces any non-strings in Series with NaNs.

2560 Equivalent to :meth:`str.lstrip`.

2561

2562 Parameters

2563 ----------

2564 to_strip : str or None, default None

2565 Specifying the set of characters to be removed.

2566 All combinations of this set of characters will be stripped.

2567 If None then whitespaces are removed.

2568

2569 Returns

2570 -------

2571 Series or Index of object

2572 Series or Index with the strings being stripped from the left side.

2573

2574 See Also

2575 --------

2576 Series.str.strip : Remove leading and trailing characters in Series/Index.

2577 Series.str.lstrip : Remove leading characters in Series/Index.

2578 Series.str.rstrip : Remove trailing characters in Series/Index.

2579

2580 Examples

2581 --------

2582 >>> s = pd.Series(["1. Ant. ", "2. Bee!\\n", "3. Cat?\\t", np.nan, 10, True])

2583 >>> s

2584 0 1. Ant.

2585 1 2. Bee!\\n

2586 2 3. Cat?\\t

2587 3 NaN

2588 4 10

2589 5 True

2590 dtype: object

2591

2592 >>> s.str.strip()

2593 0 1. Ant.

2594 1 2. Bee!

2595 2 3. Cat?

2596 3 NaN

2597 4 NaN

2598 5 NaN

2599 dtype: object

2600

2601 >>> s.str.lstrip("123.")

2602 0 Ant.

2603 1 Bee!\\n

2604 2 Cat?\\t

2605 3 NaN

2606 4 NaN

2607 5 NaN

2608 dtype: object

2609

2610 >>> s.str.rstrip(".!? \\n\\t")

2611 0 1. Ant

2612 1 2. Bee

2613 2 3. Cat

2614 3 NaN

2615 4 NaN

2616 5 NaN

2617 dtype: object

2618

2619 >>> s.str.strip("123.!? \\n\\t")

2620 0 Ant

2621 1 Bee

2622 2 Cat

2623 3 NaN

2624 4 NaN

2625 5 NaN

2626 dtype: object

2627 """

2628 result = self._data.array._str_lstrip(to_strip)

2629 return self._wrap_result(result)

2630

2631 @forbid_nonstring_types(["bytes"])

2632 def rstrip(self, to_strip=None):

2633 """

2634 Remove trailing characters.

2635

2636 Strip whitespaces (including newlines) or a set of specified characters

2637 from each string in the Series/Index from right side.

2638 Replaces any non-strings in Series with NaNs.

2639 Equivalent to :meth:`str.rstrip`.

2640

2641 Parameters

2642 ----------

2643 to_strip : str or None, default None

2644 Specifying the set of characters to be removed.

2645 All combinations of this set of characters will be stripped.

2646 If None then whitespaces are removed.

2647

2648 Returns

2649 -------

2650 Series or Index of object

2651 Series or Index with the strings being stripped from the right side.

2652

2653 See Also

2654 --------

2655 Series.str.strip : Remove leading and trailing characters in Series/Index.

2656 Series.str.lstrip : Remove leading characters in Series/Index.

2657 Series.str.rstrip : Remove trailing characters in Series/Index.

2658

2659 Examples

2660 --------

2661 >>> s = pd.Series(["1. Ant. ", "2. Bee!\\n", "3. Cat?\\t", np.nan, 10, True])

2662 >>> s

2663 0 1. Ant.

2664 1 2. Bee!\\n

2665 2 3. Cat?\\t

2666 3 NaN

2667 4 10

2668 5 True

2669 dtype: object

2670

2671 >>> s.str.strip()

2672 0 1. Ant.

2673 1 2. Bee!

2674 2 3. Cat?

2675 3 NaN

2676 4 NaN

2677 5 NaN

2678 dtype: object

2679

2680 >>> s.str.lstrip("123.")

2681 0 Ant.

2682 1 Bee!\\n

2683 2 Cat?\\t

2684 3 NaN

2685 4 NaN

2686 5 NaN

2687 dtype: object

2688

2689 >>> s.str.rstrip(".!? \\n\\t")

2690 0 1. Ant

2691 1 2. Bee

2692 2 3. Cat

2693 3 NaN

2694 4 NaN

2695 5 NaN

2696 dtype: object

2697

2698 >>> s.str.strip("123.!? \\n\\t")

2699 0 Ant

2700 1 Bee

2701 2 Cat

2702 3 NaN

2703 4 NaN

2704 5 NaN

2705 dtype: object

2706 """

2707 result = self._data.array._str_rstrip(to_strip)

2708 return self._wrap_result(result)

2709

2710 @forbid_nonstring_types(["bytes"])

2711 def removeprefix(self, prefix: str):

2712 """

2713 Remove a prefix from an object series.

2714

2715 If the prefix is not present, the original string will be returned.

2716

2717 Parameters

2718 ----------

2719 prefix : str

2720 Remove the prefix of the string.

2721

2722 Returns

2723 -------

2724 Series/Index: object

2725 The Series or Index with given prefix removed.

2726

2727 See Also

2728 --------

2729 Series.str.removesuffix : Remove a suffix from an object series.

2730

2731 Examples

2732 --------

2733 >>> s = pd.Series(["str_foo", "str_bar", "no_prefix"])

2734 >>> s

2735 0 str_foo

2736 1 str_bar

2737 2 no_prefix

2738 dtype: str

2739 >>> s.str.removeprefix("str_")

2740 0 foo

2741 1 bar

2742 2 no_prefix

2743 dtype: str

2744

2745 >>> s = pd.Series(["foo_str", "bar_str", "no_suffix"])

2746 >>> s

2747 0 foo_str

2748 1 bar_str

2749 2 no_suffix

2750 dtype: str

2751 >>> s.str.removesuffix("_str")

2752 0 foo

2753 1 bar

2754 2 no_suffix

2755 dtype: str

2756 """

2757 result = self._data.array._str_removeprefix(prefix)

2758 return self._wrap_result(result)

2759

2760 @forbid_nonstring_types(["bytes"])

2761 def removesuffix(self, suffix: str):

2762 """

2763 Remove a suffix from an object series.

2764

2765 If the suffix is not present, the original string will be returned.

2766

2767 Parameters

2768 ----------

2769 suffix : str

2770 Remove the suffix of the string.

2771

2772 Returns

2773 -------

2774 Series/Index: object

2775 The Series or Index with given suffix removed.

2776

2777 See Also

2778 --------

2779 Series.str.removeprefix : Remove a prefix from an object series.

2780

2781 Examples

2782 --------

2783 >>> s = pd.Series(["str_foo", "str_bar", "no_prefix"])

2784 >>> s

2785 0 str_foo

2786 1 str_bar

2787 2 no_prefix

2788 dtype: str

2789 >>> s.str.removeprefix("str_")

2790 0 foo

2791 1 bar

2792 2 no_prefix

2793 dtype: str

2794

2795 >>> s = pd.Series(["foo_str", "bar_str", "no_suffix"])

2796 >>> s

2797 0 foo_str

2798 1 bar_str

2799 2 no_suffix

2800 dtype: str

2801 >>> s.str.removesuffix("_str")

2802 0 foo

2803 1 bar

2804 2 no_suffix

2805 dtype: str

2806 """

2807 result = self._data.array._str_removesuffix(suffix)

2808 return self._wrap_result(result)

2809

2810 @forbid_nonstring_types(["bytes"])

2811 def wrap(

2812 self,

2813 width: int,

2814 expand_tabs: bool = True,

2815 tabsize: int = 8,

2816 replace_whitespace: bool = True,

2817 drop_whitespace: bool = True,

2818 initial_indent: str = "",

2819 subsequent_indent: str = "",

2820 fix_sentence_endings: bool = False,

2821 break_long_words: bool = True,

2822 break_on_hyphens: bool = True,

2823 max_lines: int | None = None,

2824 placeholder: str = " [...]",

2825 ):

2826 r"""

2827 Wrap strings in Series/Index at specified line width.

2828

2829 This method has the same keyword parameters and defaults as

2830 :class:`textwrap.TextWrapper`.

2831

2832 Parameters

2833 ----------

2834 width : int, optional

2835 Maximum line width.

2836 expand_tabs : bool, optional

2837 If True, tab characters will be expanded to spaces (default: True).

2838 tabsize : int, optional

2839 If expand_tabs is true, then all tab characters in text will be

2840 expanded to zero or more spaces, depending on the current column

2841 and the given tab size (default: 8).

2842 replace_whitespace : bool, optional

2843 If True, each whitespace character (as defined by string.whitespace)

2844 remaining after tab expansion will be replaced by a single space

2845 (default: True).

2846 drop_whitespace : bool, optional

2847 If True, whitespace that, after wrapping, happens to end up at the

2848 beginning or end of a line is dropped (default: True).

2849 initial_indent : str, optional

2850 String that will be prepended to the first line of wrapped output.

2851 Counts towards the length of the first line. The empty string is

2852 not indented (default: '').

2853 subsequent_indent : str, optional

2854 String that will be prepended to all lines of wrapped output except

2855 the first. Counts towards the length of each line except the first

2856 (default: '').

2857 fix_sentence_endings : bool, optional

2858 If true, TextWrapper attempts to detect sentence endings and ensure

2859 that sentences are always separated by exactly two spaces. This is

2860 generally desired for text in a monospaced font. However, the sentence

2861 detection algorithm is imperfect: it assumes that a sentence ending

2862 consists of a lowercase letter followed by one of '.', '!', or '?',

2863 possibly followed by one of '"' or "'", followed by a space. One

2864 problem with this algorithm is that it is unable to detect the

2865 difference between “Dr.” in `[...] Dr. Frankenstein's monster [...]`

2866 and “Spot.” in `[...] See Spot. See Spot run [...]`

2867 Since the sentence detection algorithm relies on string.lowercase

2868 for the definition of “lowercase letter”, and a convention of using

2869 two spaces after a period to separate sentences on the same line,

2870 it is specific to English-language texts (default: False).

2871 break_long_words : bool, optional

2872 If True, then words longer than width will be broken in order to ensure

2873 that no lines are longer than width. If it is false, long words will

2874 not be broken, and some lines may be longer than width (default: True).

2875 break_on_hyphens : bool, optional

2876 If True, wrapping will occur preferably on whitespace and right after

2877 hyphens in compound words, as it is customary in English. If false,

2878 only whitespaces will be considered as potentially good places for line

2879 breaks, but you need to set break_long_words to false if you want truly

2880 insecable words (default: True).

2881 max_lines : int, optional

2882 If not None, then the output will contain at most max_lines lines, with

2883 placeholder appearing at the end of the output (default: None).

2884 placeholder : str, optional

2885 String that will appear at the end of the output text if it has been

2886 truncated (default: ' [...]').

2887

2888 Returns

2889 -------

2890 Series or Index

2891 A Series or Index where the strings are wrapped at the specified line width.

2892

2893 See Also

2894 --------

2895 Series.str.strip : Remove leading and trailing characters in Series/Index.

2896 Series.str.lstrip : Remove leading characters in Series/Index.

2897 Series.str.rstrip : Remove trailing characters in Series/Index.

2898

2899 Notes

2900 -----

2901 Internally, this method uses a :class:`textwrap.TextWrapper` instance with

2902 default settings. To achieve behavior matching R's stringr library str_wrap

2903 function, use the arguments:

2904

2905 - expand_tabs = False

2906 - replace_whitespace = True

2907 - drop_whitespace = True

2908 - break_long_words = False

2909 - break_on_hyphens = False

2910

2911 Examples

2912 --------

2913 >>> s = pd.Series(["line to be wrapped", "another line to be wrapped"])

2914 >>> s.str.wrap(12)

2915 0 line to be\nwrapped

2916 1 another line\nto be\nwrapped

2917 dtype: str

2918 """

2919 result = self._data.array._str_wrap(

2920 width=width,

2921 expand_tabs=expand_tabs,

2922 tabsize=tabsize,

2923 replace_whitespace=replace_whitespace,

2924 drop_whitespace=drop_whitespace,

2925 initial_indent=initial_indent,

2926 subsequent_indent=subsequent_indent,

2927 fix_sentence_endings=fix_sentence_endings,

2928 break_long_words=break_long_words,

2929 break_on_hyphens=break_on_hyphens,

2930 max_lines=max_lines,

2931 placeholder=placeholder,

2932 )

2933 return self._wrap_result(result)

2934

2935 @forbid_nonstring_types(["bytes"])

2936 def get_dummies(

2937 self,

2938 sep: str = "|",

2939 dtype: NpDtype | None = None,

2940 ):

2941 """

2942 Return DataFrame of dummy/indicator variables for Series.

2943

2944 Each string in Series is split by sep and returned as a DataFrame

2945 of dummy/indicator variables.

2946

2947 Parameters

2948 ----------

2949 sep : str, default "|"

2950 String to split on.

2951 dtype : dtype, default np.int64

2952 Data type for new columns. Only a single dtype is allowed.

2953

2954 Returns

2955 -------

2956 DataFrame

2957 Dummy variables corresponding to values of the Series.

2958

2959 See Also

2960 --------

2961 get_dummies : Convert categorical variable into dummy/indicator

2962 variables.

2963

2964 Examples

2965 --------

2966 >>> pd.Series(["a|b", "a", "a|c"]).str.get_dummies()

2967 a b c

2968 0 1 1 0

2969 1 1 0 0

2970 2 1 0 1

2971

2972 >>> pd.Series(["a|b", np.nan, "a|c"]).str.get_dummies()

2973 a b c

2974 0 1 1 0

2975 1 0 0 0

2976 2 1 0 1

2977

2978 >>> pd.Series(["a|b", np.nan, "a|c"]).str.get_dummies(dtype=bool)

2979 a b c

2980 0 True True False

2981 1 False False False

2982 2 True False True

2983 """

2984 from pandas.core.frame import DataFrame

2985

2986 if dtype is not None and not (is_numeric_dtype(dtype) or is_bool_dtype(dtype)):

2987 raise ValueError("Only numeric or boolean dtypes are supported for 'dtype'")

2988 # we need to cast to Series of strings as only that has all

2989 # methods available for making the dummies...

2990 result, name = self._data.array._str_get_dummies(sep, dtype)

2991 if is_extension_array_dtype(dtype):

2992 return self._wrap_result(

2993 DataFrame(result, columns=name, dtype=dtype),

2994 name=name,

2995 returns_string=False,

2996 )

2997 return self._wrap_result(

2998 result,

2999 name=name,

3000 expand=True,

3001 returns_string=False,

3002 )

3003

3004 @forbid_nonstring_types(["bytes"])

3005 def translate(self, table):

3006 """

3007 Map all characters in the string through the given mapping table.

3008

3009 This method is equivalent to the standard :meth:`str.translate`

3010 method for strings. It maps each character in the string to a new

3011 character according to the translation table provided. Unmapped

3012 characters are left unchanged, while characters mapped to None

3013 are removed.

3014

3015 Parameters

3016 ----------

3017 table : dict

3018 Table is a mapping of Unicode ordinals to Unicode ordinals, strings, or

3019 None. Unmapped characters are left untouched.

3020 Characters mapped to None are deleted. :meth:`str.maketrans` is a

3021 helper function for making translation tables.

3022

3023 Returns

3024 -------

3025 Series or Index

3026 A new Series or Index with translated strings.

3027

3028 See Also

3029 --------

3030 Series.str.replace : Replace occurrences of pattern/regex in the

3031 Series with some other string.

3032 Index.str.replace : Replace occurrences of pattern/regex in the

3033 Index with some other string.

3034

3035 Examples

3036 --------

3037 >>> ser = pd.Series(["El niño", "Françoise"])

3038 >>> mytable = str.maketrans({"ñ": "n", "ç": "c"})

3039 >>> ser.str.translate(mytable)

3040 0 El nino

3041 1 Francoise

3042 dtype: str

3043 """

3044 result = self._data.array._str_translate(table)

3045 dtype = object if self._data.dtype == "object" else None

3046 return self._wrap_result(result, dtype=dtype)

3047

3048 @forbid_nonstring_types(["bytes"])

3049 def count(self, pat, flags: int = 0):

3050 r"""

3051 Count occurrences of pattern in each string of the Series/Index.

3052

3053 This function is used to count the number of times a particular regex

3054 pattern is repeated in each of the string elements of the

3055 :class:`~pandas.Series`.

3056

3057 Parameters

3058 ----------

3059 pat : str

3060 Valid regular expression.

3061 flags : int, default 0, meaning no flags

3062 Flags for the `re` module. For a complete list, `see here

3063 <https://docs.python.org/3/howto/regex.html#compilation-flags>`_.

3064

3065 Returns

3066 -------

3067 Series or Index

3068 Same type as the calling object containing the integer counts.

3069

3070 See Also

3071 --------

3072 re : Standard library module for regular expressions.

3073 str.count : Standard library version, without regular expression support.

3074

3075 Notes

3076 -----

3077 Some characters need to be escaped when passing in `pat`.

3078 eg. ``'$'`` has a special meaning in regex and must be escaped when

3079 finding this literal character.

3080

3081 Examples

3082 --------

3083 >>> s = pd.Series(["A", "B", "Aaba", "Baca", np.nan, "CABA", "cat"])

3084 >>> s.str.count("a")

3085 0 0.0

3086 1 0.0

3087 2 2.0

3088 3 2.0

3089 4 NaN

3090 5 0.0

3091 6 1.0

3092 dtype: float64

3093

3094 Escape ``'$'`` to find the literal dollar sign.

3095

3096 >>> s = pd.Series(["$", "B", "Aab$", "$$ca", "C$B$", "cat"])

3097 >>> s.str.count("\\$")

3098 0 1

3099 1 0

3100 2 1

3101 3 2

3102 4 2

3103 5 0

3104 dtype: int64

3105

3106 This is also available on Index

3107

3108 >>> pd.Index(["A", "A", "Aaba", "cat"]).str.count("a")

3109 Index([0, 0, 2, 1], dtype='int64')

3110 """

3111 result = self._data.array._str_count(pat, flags)

3112 return self._wrap_result(result, returns_string=False)

3113

3114 @forbid_nonstring_types(["bytes"])

3115 def startswith(

3116 self, pat: str | tuple[str, ...], na: Scalar | lib.NoDefault = lib.no_default

3117 ) -> Series | Index:

3118 """

3119 Test if the start of each string element matches a pattern.

3120

3121 Equivalent to :meth:`str.startswith`.

3122

3123 Parameters

3124 ----------

3125 pat : str or tuple[str, ...]

3126 Character sequence or tuple of strings. Regular expressions are not

3127 accepted.

3128 na : scalar, optional

3129 Object shown if element tested is not a string. The default depends

3130 on dtype of the array. For the ``"str"`` dtype, ``False`` is used.

3131 For object dtype, ``numpy.nan`` is used. For the nullable

3132 ``StringDtype``, ``pandas.NA`` is used.

3133

3134 Returns

3135 -------

3136 Series or Index of bool

3137 A Series of booleans indicating whether the given pattern matches

3138 the start of each string element.

3139

3140 See Also

3141 --------

3142 str.startswith : Python standard library string method.

3143 Series.str.endswith : Same as startswith, but tests the end of string.

3144 Series.str.contains : Tests if string element contains a pattern.

3145

3146 Examples

3147 --------

3148 >>> s = pd.Series(["bat", "Bear", "cat", np.nan])

3149 >>> s

3150 0 bat

3151 1 Bear

3152 2 cat

3153 3 NaN

3154 dtype: str

3155

3156 >>> s.str.startswith("b")

3157 0 True

3158 1 False

3159 2 False

3160 3 False

3161 dtype: bool

3162

3163 >>> s.str.startswith(("b", "B"))

3164 0 True

3165 1 True

3166 2 False

3167 3 False

3168 dtype: bool

3169 """

3170 if not isinstance(pat, (str, tuple)):

3171 msg = f"expected a string or tuple, not {type(pat).__name__}"

3172 raise TypeError(msg)

3173 result = self._data.array._str_startswith(pat, na=na)

3174 return self._wrap_result(result, returns_string=False)

3175

3176 @forbid_nonstring_types(["bytes"])

3177 def endswith(

3178 self, pat: str | tuple[str, ...], na: Scalar | lib.NoDefault = lib.no_default

3179 ) -> Series | Index:

3180 """

3181 Test if the end of each string element matches a pattern.

3182

3183 Equivalent to :meth:`str.endswith`.

3184

3185 Parameters

3186 ----------

3187 pat : str or tuple[str, ...]

3188 Character sequence or tuple of strings. Regular expressions are not

3189 accepted.

3190 na : scalar, optional

3191 Object shown if element tested is not a string. The default depends

3192 on dtype of the array. For the ``"str"`` dtype, ``False`` is used.

3193 For object dtype, ``numpy.nan`` is used. For the nullable

3194 ``StringDtype``, ``pandas.NA`` is used.

3195

3196 Returns

3197 -------

3198 Series or Index of bool

3199 A Series of booleans indicating whether the given pattern matches

3200 the end of each string element.

3201

3202 See Also

3203 --------

3204 str.endswith : Python standard library string method.

3205 Series.str.startswith : Same as endswith, but tests the start of string.

3206 Series.str.contains : Tests if string element contains a pattern.

3207

3208 Examples

3209 --------

3210 >>> s = pd.Series(["bat", "bear", "caT", np.nan])

3211 >>> s

3212 0 bat

3213 1 bear

3214 2 caT

3215 3 NaN

3216 dtype: str

3217

3218 >>> s.str.endswith("t")

3219 0 True

3220 1 False

3221 2 False

3222 3 False

3223 dtype: bool

3224

3225 >>> s.str.endswith(("t", "T"))

3226 0 True

3227 1 False

3228 2 True

3229 3 False

3230 dtype: bool

3231 """

3232 if not isinstance(pat, (str, tuple)):

3233 msg = f"expected a string or tuple, not {type(pat).__name__}"

3234 raise TypeError(msg)

3235 result = self._data.array._str_endswith(pat, na=na)

3236 return self._wrap_result(result, returns_string=False)

3237

3238 @forbid_nonstring_types(["bytes"])

3239 def findall(self, pat, flags: int = 0):

3240 """

3241 Find all occurrences of pattern or regular expression in the Series/Index.

3242

3243 Equivalent to applying :func:`re.findall` to all the elements in the

3244 Series/Index.

3245

3246 Parameters

3247 ----------

3248 pat : str

3249 Pattern or regular expression.

3250 flags : int, default 0

3251 Flags from ``re`` module, e.g. `re.IGNORECASE` (default is 0, which

3252 means no flags).

3253

3254 Returns

3255 -------

3256 Series/Index of lists of strings

3257 All non-overlapping matches of pattern or regular expression in each

3258 string of this Series/Index.

3259

3260 See Also

3261 --------

3262 count : Count occurrences of pattern or regular expression in each string

3263 of the Series/Index.

3264 extractall : For each string in the Series, extract groups from all matches

3265 of regular expression and return a DataFrame with one row for each

3266 match and one column for each group.

3267 re.findall : The equivalent ``re`` function to all non-overlapping matches

3268 of pattern or regular expression in string, as a list of strings.

3269

3270 Examples

3271 --------

3272 >>> s = pd.Series(["Lion", "Monkey", "Rabbit"])

3273

3274 The search for the pattern 'Monkey' returns one match:

3275

3276 >>> s.str.findall("Monkey")

3277 0 []

3278 1 [Monkey]

3279 2 []

3280 dtype: object

3281

3282 On the other hand, the search for the pattern 'MONKEY' doesn't return any

3283 match:

3284

3285 >>> s.str.findall("MONKEY")

3286 0 []

3287 1 []

3288 2 []

3289 dtype: object

3290

3291 Flags can be added to the pattern or regular expression. For instance,

3292 to find the pattern 'MONKEY' ignoring the case:

3293

3294 >>> import re

3295 >>> s.str.findall("MONKEY", flags=re.IGNORECASE)

3296 0 []

3297 1 [Monkey]

3298 2 []

3299 dtype: object

3300

3301 When the pattern matches more than one string in the Series, all matches

3302 are returned:

3303

3304 >>> s.str.findall("on")

3305 0 [on]

3306 1 [on]

3307 2 []

3308 dtype: object

3309

3310 Regular expressions are supported too. For instance, the search for all the

3311 strings ending with the word 'on' is shown next:

3312

3313 >>> s.str.findall("on$")

3314 0 [on]

3315 1 []

3316 2 []

3317 dtype: object

3318

3319 If the pattern is found more than once in the same string, then a list of

3320 multiple strings is returned:

3321

3322 >>> s.str.findall("b")

3323 0 []

3324 1 []

3325 2 [b, b]

3326 dtype: object

3327 """

3328 result = self._data.array._str_findall(pat, flags)

3329 return self._wrap_result(result, returns_string=False)

3330

3331 @forbid_nonstring_types(["bytes"])

3332 def extract(

3333 self, pat: str, flags: int = 0, expand: bool = True

3334 ) -> DataFrame | Series | Index:

3335 r"""

3336 Extract capture groups in the regex `pat` as columns in a DataFrame.

3337

3338 For each subject string in the Series, extract groups from the

3339 first match of regular expression `pat`.

3340

3341 Parameters

3342 ----------

3343 pat : str

3344 Regular expression pattern with capturing groups.

3345 flags : int, default 0 (no flags)

3346 Flags from the ``re`` module, e.g. ``re.IGNORECASE``, that

3347 modify regular expression matching for things like case,

3348 spaces, etc. For more details, see :mod:`re`.

3349 expand : bool, default True

3350 If True, return DataFrame with one column per capture group.

3351 If False, return a Series/Index if there is one capture group

3352 or DataFrame if there are multiple capture groups.

3353

3354 Returns

3355 -------

3356 DataFrame or Series or Index

3357 A DataFrame with one row for each subject string, and one

3358 column for each group. Any capture group names in regular

3359 expression pat will be used for column names; otherwise

3360 capture group numbers will be used. The dtype of each result

3361 column is always object, even when no match is found. If

3362 ``expand=False`` and pat has only one capture group, then

3363 return a Series (if subject is a Series) or Index (if subject

3364 is an Index).

3365

3366 See Also

3367 --------

3368 extractall : Returns all matches (not just the first match).

3369

3370 Examples

3371 --------

3372 A pattern with two groups will return a DataFrame with two columns.

3373 Non-matches will be NaN.

3374

3375 >>> s = pd.Series(["a1", "b2", "c3"])

3376 >>> s.str.extract(r"([ab])(\d)")

3377 0 1

3378 0 a 1

3379 1 b 2

3380 2 NaN NaN

3381

3382 A pattern may contain optional groups.

3383

3384 >>> s.str.extract(r"([ab])?(\d)")

3385 0 1

3386 0 a 1

3387 1 b 2

3388 2 NaN 3

3389

3390 Named groups will become column names in the result.

3391

3392 >>> s.str.extract(r"(?P<letter>[ab])(?P<digit>\d)")

3393 letter digit

3394 0 a 1

3395 1 b 2

3396 2 NaN NaN

3397

3398 A pattern with one group will return a DataFrame with one column

3399 if expand=True.

3400

3401 >>> s.str.extract(r"[ab](\d)", expand=True)

3402 0

3403 0 1

3404 1 2

3405 2 NaN

3406

3407 A pattern with one group will return a Series if expand=False.

3408

3409 >>> s.str.extract(r"[ab](\d)", expand=False)

3410 0 1

3411 1 2

3412 2 NaN

3413 dtype: str

3414 """

3415 from pandas import DataFrame

3416

3417 if not isinstance(expand, bool):

3418 raise ValueError("expand must be True or False")

3419

3420 regex = re.compile(pat, flags=flags)

3421 if regex.groups == 0:

3422 raise ValueError("pattern contains no capture groups")

3423

3424 if not expand and regex.groups > 1 and isinstance(self._data, ABCIndex):

3425 raise ValueError("only one regex group is supported with Index")

3426

3427 obj = self._data

3428 result_dtype = _result_dtype(obj)

3429

3430 returns_df = regex.groups > 1 or expand

3431

3432 if returns_df:

3433 name = None

3434 columns = _get_group_names(regex)

3435

3436 if obj.array.size == 0:

3437 result = DataFrame(columns=columns, dtype=result_dtype)

3438

3439 else:

3440 result_list = self._data.array._str_extract(

3441 pat, flags=flags, expand=returns_df

3442 )

3443

3444 result_index: Index | None

3445 if isinstance(obj, ABCSeries):

3446 result_index = obj.index

3447 else:

3448 result_index = None

3449

3450 result = DataFrame(

3451 result_list, columns=columns, index=result_index, dtype=result_dtype

3452 )

3453

3454 else:

3455 name = _get_single_group_name(regex)

3456 result = self._data.array._str_extract(pat, flags=flags, expand=returns_df)

3457 return self._wrap_result(result, name=name, dtype=result_dtype)

3458

3459 @forbid_nonstring_types(["bytes"])

3460 def extractall(self, pat, flags: int = 0) -> DataFrame:

3461 r"""

3462 Extract capture groups in the regex `pat` as columns in DataFrame.

3463

3464 For each subject string in the Series, extract groups from all

3465 matches of regular expression pat. When each subject string in the

3466 Series has exactly one match, extractall(pat).xs(0, level='match')

3467 is the same as extract(pat).

3468

3469 Parameters

3470 ----------

3471 pat : str

3472 Regular expression pattern with capturing groups.

3473 flags : int, default 0 (no flags)

3474 A ``re`` module flag, for example ``re.IGNORECASE``. These allow

3475 to modify regular expression matching for things like case, spaces,

3476 etc. Multiple flags can be combined with the bitwise OR operator,

3477 for example ``re.IGNORECASE | re.MULTILINE``.

3478

3479 Returns

3480 -------

3481 DataFrame

3482 A ``DataFrame`` with one row for each match, and one column for each

3483 group. Its rows have a ``MultiIndex`` with first levels that come from

3484 the subject ``Series``. The last level is named 'match' and indexes the

3485 matches in each item of the ``Series``. Any capture group names in

3486 regular expression pat will be used for column names; otherwise capture

3487 group numbers will be used.

3488

3489 See Also

3490 --------

3491 extract : Returns first match only (not all matches).

3492

3493 Examples

3494 --------

3495 A pattern with one group will return a DataFrame with one column.

3496 Indices with no matches will not appear in the result.

3497

3498 >>> s = pd.Series(["a1a2", "b1", "c1"], index=["A", "B", "C"])

3499 >>> s.str.extractall(r"[ab](\d)")

3500 0

3501 match

3502 A 0 1

3503 1 2

3504 B 0 1

3505

3506 Capture group names are used for column names of the result.

3507

3508 >>> s.str.extractall(r"[ab](?P<digit>\d)")

3509 digit

3510 match

3511 A 0 1

3512 1 2

3513 B 0 1

3514

3515 A pattern with two groups will return a DataFrame with two columns.

3516

3517 >>> s.str.extractall(r"(?P<letter>[ab])(?P<digit>\d)")

3518 letter digit

3519 match

3520 A 0 a 1

3521 1 a 2

3522 B 0 b 1

3523

3524 Optional groups that do not match are NaN in the result.

3525

3526 >>> s.str.extractall(r"(?P<letter>[ab])?(?P<digit>\d)")

3527 letter digit

3528 match

3529 A 0 a 1

3530 1 a 2

3531 B 0 b 1

3532 C 0 NaN 1

3533 """

3534 # TODO: dispatch

3535 return str_extractall(self._orig, pat, flags)

3536

3537 @forbid_nonstring_types(["bytes"])

3538 def find(self, sub, start: int = 0, end=None):

3539 """

3540 Return lowest indexes in each strings in the Series/Index.

3541

3542 Each of returned indexes corresponds to the position where the

3543 substring is fully contained between [start:end]. Return -1 on

3544 failure. Equivalent to standard :meth:`str.find`.

3545

3546 Parameters

3547 ----------

3548 sub : str

3549 Substring being searched.

3550 start : int

3551 Left edge index.

3552 end : int

3553 Right edge index.

3554

3555 Returns

3556 -------

3557 Series or Index of int.

3558 A Series (if the input is a Series) or an Index (if the input is an

3559 Index) of the lowest indexes corresponding to the positions where the

3560 substring is found in each string of the input.

3561

3562 See Also

3563 --------

3564 rfind : Return highest indexes in each strings.

3565

3566 Examples

3567 --------

3568 For Series.str.find:

3569

3570 >>> ser = pd.Series(["_cow_", "duck_", "do_v_e"])

3571 >>> ser.str.find("_")

3572 0 0

3573 1 4

3574 2 2

3575 dtype: int64

3576

3577 For Series.str.rfind:

3578

3579 >>> ser = pd.Series(["_cow_", "duck_", "do_v_e"])

3580 >>> ser.str.rfind("_")

3581 0 4

3582 1 4

3583 2 4

3584 dtype: int64

3585 """

3586 if not isinstance(sub, str):

3587 msg = f"expected a string object, not {type(sub).__name__}"

3588 raise TypeError(msg)

3589

3590 result = self._data.array._str_find(sub, start, end)

3591 return self._wrap_result(result, returns_string=False)

3592

3593 @forbid_nonstring_types(["bytes"])

3594 def rfind(self, sub, start: int = 0, end=None):

3595 """

3596 Return highest indexes in each strings in the Series/Index.

3597

3598 Each of returned indexes corresponds to the position where the

3599 substring is fully contained between [start:end]. Return -1 on

3600 failure. Equivalent to standard :meth:`str.rfind`.

3601

3602 Parameters

3603 ----------

3604 sub : str

3605 Substring being searched.

3606 start : int

3607 Left edge index.

3608 end : int

3609 Right edge index.

3610

3611 Returns

3612 -------

3613 Series or Index of int.

3614 A Series (if the input is a Series) or an Index (if the input is an

3615 Index) of the highest indexes corresponding to the positions where the

3616 substring is found in each string of the input.

3617

3618 See Also

3619 --------

3620 find : Return lowest indexes in each strings.

3621

3622 Examples

3623 --------

3624 For Series.str.find:

3625

3626 >>> ser = pd.Series(["_cow_", "duck_", "do_v_e"])

3627 >>> ser.str.find("_")

3628 0 0

3629 1 4

3630 2 2

3631 dtype: int64

3632

3633 For Series.str.rfind:

3634

3635 >>> ser = pd.Series(["_cow_", "duck_", "do_v_e"])

3636 >>> ser.str.rfind("_")

3637 0 4

3638 1 4

3639 2 4

3640 dtype: int64

3641 """

3642 if not isinstance(sub, str):

3643 msg = f"expected a string object, not {type(sub).__name__}"

3644 raise TypeError(msg)

3645

3646 result = self._data.array._str_rfind(sub, start=start, end=end)

3647 return self._wrap_result(result, returns_string=False)

3648

3649 @forbid_nonstring_types(["bytes"])

3650 def normalize(self, form):

3651 """

3652 Return the Unicode normal form for the strings in the Series/Index.

3653

3654 For more information on the forms, see the

3655 :func:`unicodedata.normalize`.

3656

3657 Parameters

3658 ----------

3659 form : {'NFC', 'NFKC', 'NFD', 'NFKD'}

3660 Unicode form.

3661

3662 Returns

3663 -------

3664 Series/Index of objects

3665 A Series or Index of strings in the same Unicode form specified by `form`.

3666 The returned object retains the same type as the input (Series or Index),

3667 and contains the normalized strings.

3668

3669 See Also

3670 --------

3671 Series.str.upper : Convert all characters in each string to uppercase.

3672 Series.str.lower : Convert all characters in each string to lowercase.

3673 Series.str.title : Convert each string to title case (capitalizing the

3674 first letter of each word).

3675 Series.str.strip : Remove leading and trailing whitespace from each string.

3676 Series.str.replace : Replace occurrences of a substring with another substring

3677 in each string.

3678

3679 Examples

3680 --------

3681 >>> ser = pd.Series(["ñ"])

3682 >>> ser.str.normalize("NFC") == ser.str.normalize("NFD")

3683 0 False

3684 dtype: bool

3685 """

3686 result = self._data.array._str_normalize(form)

3687 return self._wrap_result(result)

3688

3689 @forbid_nonstring_types(["bytes"])

3690 def index(self, sub, start: int = 0, end=None):

3691 """

3692 Return lowest indexes in each string in Series/Index.

3693

3694 Each of the returned indexes corresponds to the position where the

3695 substring is fully contained between [start:end]. This is the same

3696 as ``str.find`` except instead of returning -1, it raises a

3697 ValueError when the substring is not found. Equivalent to standard

3698 ``str.index``.

3699

3700 Parameters

3701 ----------

3702 sub : str

3703 Substring being searched.

3704 start : int

3705 Left edge index.

3706 end : int

3707 Right edge index.

3708

3709 Returns

3710 -------

3711 Series or Index of object

3712 Returns a Series or an Index of the lowest indexes

3713 in each string of the input.

3714

3715 See Also

3716 --------

3717 rindex : Return highest indexes in each strings.

3718

3719 Examples

3720 --------

3721 For Series.str.index:

3722

3723 >>> ser = pd.Series(["horse", "eagle", "donkey"])

3724 >>> ser.str.index("e")

3725 0 4

3726 1 0

3727 2 4

3728 dtype: int64

3729

3730 For Series.str.rindex:

3731

3732 >>> ser = pd.Series(["Deer", "eagle", "Sheep"])

3733 >>> ser.str.rindex("e")

3734 0 2

3735 1 4

3736 2 3

3737 dtype: int64

3738 """

3739 if not isinstance(sub, str):

3740 msg = f"expected a string object, not {type(sub).__name__}"

3741 raise TypeError(msg)

3742

3743 result = self._data.array._str_index(sub, start=start, end=end)

3744 return self._wrap_result(result, returns_string=False)

3745

3746 @forbid_nonstring_types(["bytes"])

3747 def rindex(self, sub, start: int = 0, end=None):

3748 """

3749 Return highest indexes in each string in Series/Index.

3750

3751 Each of the returned indexes corresponds to the position where the

3752 substring is fully contained between [start:end]. This is the same

3753 as ``str.rfind`` except instead of returning -1, it raises a

3754 ValueError when the substring is not found. Equivalent to standard

3755 ``str.rindex``.

3756

3757 Parameters

3758 ----------

3759 sub : str

3760 Substring being searched.

3761 start : int

3762 Left edge index.

3763 end : int

3764 Right edge index.

3765

3766 Returns

3767 -------

3768 Series or Index of object

3769 Returns a Series or an Index of the highest indexes

3770 in each string of the input.

3771

3772 See Also

3773 --------

3774 index : Return lowest indexes in each strings.

3775

3776 Examples

3777 --------

3778 For Series.str.index:

3779

3780 >>> ser = pd.Series(["horse", "eagle", "donkey"])

3781 >>> ser.str.index("e")

3782 0 4

3783 1 0

3784 2 4

3785 dtype: int64

3786

3787 For Series.str.rindex:

3788

3789 >>> ser = pd.Series(["Deer", "eagle", "Sheep"])

3790 >>> ser.str.rindex("e")

3791 0 2

3792 1 4

3793 2 3

3794 dtype: int64

3795 """

3796 if not isinstance(sub, str):

3797 msg = f"expected a string object, not {type(sub).__name__}"

3798 raise TypeError(msg)

3799

3800 result = self._data.array._str_rindex(sub, start=start, end=end)

3801 return self._wrap_result(result, returns_string=False)

3802

3803 def len(self):

3804 """

3805 Compute the length of each element in the Series/Index.

3806

3807 The element may be a sequence (such as a string, tuple or list) or a collection

3808 (such as a dictionary).

3809

3810 Returns

3811 -------

3812 Series or Index of int

3813 A Series or Index of integer values indicating the length of each

3814 element in the Series or Index.

3815

3816 See Also

3817 --------

3818 str.len : Python built-in function returning the length of an object.

3819 Series.size : Returns the length of the Series.

3820

3821 Examples

3822 --------

3823 Returns the length (number of characters) in a string. Returns the

3824 number of entries for dictionaries, lists or tuples.

3825

3826 >>> s = pd.Series(

3827 ... ["dog", "", 5, {"foo": "bar"}, [2, 3, 5, 7], ("one", "two", "three")]

3828 ... )

3829 >>> s

3830 0 dog

3831 1

3832 2 5

3833 3 {'foo': 'bar'}

3834 4 [2, 3, 5, 7]

3835 5 (one, two, three)

3836 dtype: object

3837 >>> s.str.len()

3838 0 3.0

3839 1 0.0

3840 2 NaN

3841 3 1.0

3842 4 4.0

3843 5 3.0

3844 dtype: float64

3845 """

3846 result = self._data.array._str_len()

3847 return self._wrap_result(result, returns_string=False)

3848

3849 @forbid_nonstring_types(["bytes"])

3850 def lower(self):

3851 """

3852 Convert strings in the Series/Index to lowercase.

3853

3854 Equivalent to :meth:`str.lower`.

3855

3856 Returns

3857 -------

3858 Series or Index of objects

3859 A Series or Index where the strings are modified by :meth:`str.lower`.

3860

3861 See Also

3862 --------

3863 Series.str.lower : Converts all characters to lowercase.

3864 Series.str.upper : Converts all characters to uppercase.

3865 Series.str.title : Converts first character of each word to uppercase and

3866 remaining to lowercase.

3867 Series.str.capitalize : Converts first character to uppercase and

3868 remaining to lowercase.

3869 Series.str.swapcase : Converts uppercase to lowercase and lowercase to

3870 uppercase.

3871 Series.str.casefold: Removes all case distinctions in the string.

3872

3873 Examples

3874 --------

3875 >>> s = pd.Series(["lower", "CAPITALS", "this is a sentence", "SwApCaSe"])

3876 >>> s

3877 0 lower

3878 1 CAPITALS

3879 2 this is a sentence

3880 3 SwApCaSe

3881 dtype: str

3882

3883 >>> s.str.lower()

3884 0 lower

3885 1 capitals

3886 2 this is a sentence

3887 3 swapcase

3888 dtype: str

3889

3890 >>> s.str.upper()

3891 0 LOWER

3892 1 CAPITALS

3893 2 THIS IS A SENTENCE

3894 3 SWAPCASE

3895 dtype: str

3896

3897 >>> s.str.title()

3898 0 Lower

3899 1 Capitals

3900 2 This Is A Sentence

3901 3 Swapcase

3902 dtype: str

3903

3904 >>> s.str.capitalize()

3905 0 Lower

3906 1 Capitals

3907 2 This is a sentence

3908 3 Swapcase

3909 dtype: str

3910

3911 >>> s.str.swapcase()

3912 0 LOWER

3913 1 capitals

3914 2 THIS IS A SENTENCE

3915 3 sWaPcAsE

3916 dtype: str

3917 """

3918 result = self._data.array._str_lower()

3919 return self._wrap_result(result)

3920

3921 @forbid_nonstring_types(["bytes"])

3922 def upper(self):

3923 """

3924 Convert strings in the Series/Index to uppercase.

3925

3926 Equivalent to :meth:`str.upper`.

3927

3928 Returns

3929 -------

3930 Series or Index of objects

3931 A Series or Index where the strings are modified by :meth:`str.upper`.

3932

3933 See Also

3934 --------

3935 Series.str.lower : Converts all characters to lowercase.

3936 Series.str.upper : Converts all characters to uppercase.

3937 Series.str.title : Converts first character of each word to uppercase and

3938 remaining to lowercase.

3939 Series.str.capitalize : Converts first character to uppercase and

3940 remaining to lowercase.

3941 Series.str.swapcase : Converts uppercase to lowercase and lowercase to

3942 uppercase.

3943 Series.str.casefold: Removes all case distinctions in the string.

3944

3945 Examples

3946 --------

3947 >>> s = pd.Series(["lower", "CAPITALS", "this is a sentence", "SwApCaSe"])

3948 >>> s

3949 0 lower

3950 1 CAPITALS

3951 2 this is a sentence

3952 3 SwApCaSe

3953 dtype: str

3954

3955 >>> s.str.lower()

3956 0 lower

3957 1 capitals

3958 2 this is a sentence

3959 3 swapcase

3960 dtype: str

3961

3962 >>> s.str.upper()

3963 0 LOWER

3964 1 CAPITALS

3965 2 THIS IS A SENTENCE

3966 3 SWAPCASE

3967 dtype: str

3968

3969 >>> s.str.title()

3970 0 Lower

3971 1 Capitals

3972 2 This Is A Sentence

3973 3 Swapcase

3974 dtype: str

3975

3976 >>> s.str.capitalize()

3977 0 Lower

3978 1 Capitals

3979 2 This is a sentence

3980 3 Swapcase

3981 dtype: str

3982

3983 >>> s.str.swapcase()

3984 0 LOWER

3985 1 capitals

3986 2 THIS IS A SENTENCE

3987 3 sWaPcAsE

3988 dtype: str

3989 """

3990 result = self._data.array._str_upper()

3991 return self._wrap_result(result)

3992

3993 @forbid_nonstring_types(["bytes"])

3994 def title(self):

3995 """

3996 Convert strings in the Series/Index to titlecase.

3997

3998 Equivalent to :meth:`str.title`.

3999

4000 Returns

4001 -------

4002 Series or Index of objects

4003 A Series or Index where the strings are modified by :meth:`str.title`.

4004

4005 See Also

4006 --------

4007 Series.str.lower : Converts all characters to lowercase.

4008 Series.str.upper : Converts all characters to uppercase.

4009 Series.str.title : Converts first character of each word to uppercase and

4010 remaining to lowercase.

4011 Series.str.capitalize : Converts first character to uppercase and

4012 remaining to lowercase.

4013 Series.str.swapcase : Converts uppercase to lowercase and lowercase to

4014 uppercase.

4015 Series.str.casefold: Removes all case distinctions in the string.

4016

4017 Examples

4018 --------

4019 >>> s = pd.Series(["lower", "CAPITALS", "this is a sentence", "SwApCaSe"])

4020 >>> s

4021 0 lower

4022 1 CAPITALS

4023 2 this is a sentence

4024 3 SwApCaSe

4025 dtype: str

4026

4027 >>> s.str.lower()

4028 0 lower

4029 1 capitals

4030 2 this is a sentence

4031 3 swapcase

4032 dtype: str

4033

4034 >>> s.str.upper()

4035 0 LOWER

4036 1 CAPITALS

4037 2 THIS IS A SENTENCE

4038 3 SWAPCASE

4039 dtype: str

4040

4041 >>> s.str.title()

4042 0 Lower

4043 1 Capitals

4044 2 This Is A Sentence

4045 3 Swapcase

4046 dtype: str

4047

4048 >>> s.str.capitalize()

4049 0 Lower

4050 1 Capitals

4051 2 This is a sentence

4052 3 Swapcase

4053 dtype: str

4054

4055 >>> s.str.swapcase()

4056 0 LOWER

4057 1 capitals

4058 2 THIS IS A SENTENCE

4059 3 sWaPcAsE

4060 dtype: str

4061 """

4062 result = self._data.array._str_title()

4063 return self._wrap_result(result)

4064

4065 @forbid_nonstring_types(["bytes"])

4066 def capitalize(self):

4067 """

4068 Convert strings in the Series/Index to be capitalized.

4069

4070 Equivalent to :meth:`str.capitalize`.

4071

4072 Returns

4073 -------

4074 Series or Index of objects

4075 A Series or Index where the strings are modified by :meth:`str.capitalize`.

4076

4077 See Also

4078 --------

4079 Series.str.lower : Converts all characters to lowercase.

4080 Series.str.upper : Converts all characters to uppercase.

4081 Series.str.title : Converts first character of each word to uppercase and

4082 remaining to lowercase.

4083 Series.str.capitalize : Converts first character to uppercase and

4084 remaining to lowercase.

4085 Series.str.swapcase : Converts uppercase to lowercase and lowercase to

4086 uppercase.

4087 Series.str.casefold: Removes all case distinctions in the string.

4088

4089 Examples

4090 --------

4091 >>> s = pd.Series(["lower", "CAPITALS", "this is a sentence", "SwApCaSe"])

4092 >>> s

4093 0 lower

4094 1 CAPITALS

4095 2 this is a sentence

4096 3 SwApCaSe

4097 dtype: str

4098

4099 >>> s.str.lower()

4100 0 lower

4101 1 capitals

4102 2 this is a sentence

4103 3 swapcase

4104 dtype: str

4105

4106 >>> s.str.upper()

4107 0 LOWER

4108 1 CAPITALS

4109 2 THIS IS A SENTENCE

4110 3 SWAPCASE

4111 dtype: str

4112

4113 >>> s.str.title()

4114 0 Lower

4115 1 Capitals

4116 2 This Is A Sentence

4117 3 Swapcase

4118 dtype: str

4119

4120 >>> s.str.capitalize()

4121 0 Lower

4122 1 Capitals

4123 2 This is a sentence

4124 3 Swapcase

4125 dtype: str

4126

4127 >>> s.str.swapcase()

4128 0 LOWER

4129 1 capitals

4130 2 THIS IS A SENTENCE

4131 3 sWaPcAsE

4132 dtype: str

4133 """

4134 result = self._data.array._str_capitalize()

4135 return self._wrap_result(result)

4136

4137 @forbid_nonstring_types(["bytes"])

4138 def swapcase(self):

4139 """

4140 Convert strings in the Series/Index to be swapcased.

4141

4142 Equivalent to :meth:`str.swapcase`.

4143

4144 Returns

4145 -------

4146 Series or Index of objects

4147 A Series or Index where the strings are modified by :meth:`str.swapcase`.

4148

4149 See Also

4150 --------

4151 Series.str.lower : Converts all characters to lowercase.

4152 Series.str.upper : Converts all characters to uppercase.

4153 Series.str.title : Converts first character of each word to uppercase and

4154 remaining to lowercase.

4155 Series.str.capitalize : Converts first character to uppercase and

4156 remaining to lowercase.

4157 Series.str.swapcase : Converts uppercase to lowercase and lowercase to

4158 uppercase.

4159 Series.str.casefold: Removes all case distinctions in the string.

4160

4161 Examples

4162 --------

4163 >>> s = pd.Series(["lower", "CAPITALS", "this is a sentence", "SwApCaSe"])

4164 >>> s

4165 0 lower

4166 1 CAPITALS

4167 2 this is a sentence

4168 3 SwApCaSe

4169 dtype: str

4170

4171 >>> s.str.lower()

4172 0 lower

4173 1 capitals

4174 2 this is a sentence

4175 3 swapcase

4176 dtype: str

4177

4178 >>> s.str.upper()

4179 0 LOWER

4180 1 CAPITALS

4181 2 THIS IS A SENTENCE

4182 3 SWAPCASE

4183 dtype: str

4184

4185 >>> s.str.title()

4186 0 Lower

4187 1 Capitals

4188 2 This Is A Sentence

4189 3 Swapcase

4190 dtype: str

4191

4192 >>> s.str.capitalize()

4193 0 Lower

4194 1 Capitals

4195 2 This is a sentence

4196 3 Swapcase

4197 dtype: str

4198

4199 >>> s.str.swapcase()

4200 0 LOWER

4201 1 capitals

4202 2 THIS IS A SENTENCE

4203 3 sWaPcAsE

4204 dtype: str

4205 """

4206 result = self._data.array._str_swapcase()

4207 return self._wrap_result(result)

4208

4209 @forbid_nonstring_types(["bytes"])

4210 def casefold(self):

4211 """

4212 Convert strings in the Series/Index to be casefolded.

4213

4214 Equivalent to :meth:`str.casefold`.

4215

4216 Returns

4217 -------

4218 Series or Index of objects

4219 A Series or Index where the strings are modified by :meth:`str.casefold`.

4220

4221 See Also

4222 --------

4223 Series.str.lower : Converts all characters to lowercase.

4224 Series.str.upper : Converts all characters to uppercase.

4225 Series.str.title : Converts first character of each word to uppercase and

4226 remaining to lowercase.

4227 Series.str.capitalize : Converts first character to uppercase and

4228 remaining to lowercase.

4229 Series.str.swapcase : Converts uppercase to lowercase and lowercase to

4230 uppercase.

4231 Series.str.casefold: Removes all case distinctions in the string.

4232

4233 Examples

4234 --------

4235 >>> s = pd.Series(["lower", "CAPITALS", "this is a sentence", "SwApCaSe"])

4236 >>> s

4237 0 lower

4238 1 CAPITALS

4239 2 this is a sentence

4240 3 SwApCaSe

4241 dtype: str

4242

4243 >>> s.str.lower()

4244 0 lower

4245 1 capitals

4246 2 this is a sentence

4247 3 swapcase

4248 dtype: str

4249

4250 >>> s.str.upper()

4251 0 LOWER

4252 1 CAPITALS

4253 2 THIS IS A SENTENCE

4254 3 SWAPCASE

4255 dtype: str

4256

4257 >>> s.str.title()

4258 0 Lower

4259 1 Capitals

4260 2 This Is A Sentence

4261 3 Swapcase

4262 dtype: str

4263

4264 >>> s.str.capitalize()

4265 0 Lower

4266 1 Capitals

4267 2 This is a sentence

4268 3 Swapcase

4269 dtype: str

4270

4271 >>> s.str.swapcase()

4272 0 LOWER

4273 1 capitals

4274 2 THIS IS A SENTENCE

4275 3 sWaPcAsE

4276 dtype: str

4277 """

4278 result = self._data.array._str_casefold()

4279 return self._wrap_result(result)

4280

4281 @forbid_nonstring_types(["bytes"])

4282 def isalnum(self):

4283 """

4284 Check whether all characters in each string are alphanumeric.

4285

4286 This is equivalent to running the Python string method

4287 :meth:`str.isalnum` for each element of the Series/Index. If a string

4288 has zero characters, ``False`` is returned for that check.

4289

4290 Returns

4291 -------

4292 Series or Index of bool

4293 Series or Index of boolean values with the same length as the original

4294 Series/Index.

4295

4296 See Also

4297 --------

4298 Series.str.isalpha : Check whether all characters are alphabetic.

4299 Series.str.isnumeric : Check whether all characters are numeric.

4300 Series.str.isdigit : Check whether all characters are digits.

4301 Series.str.isdecimal : Check whether all characters are decimal.

4302 Series.str.isspace : Check whether all characters are whitespace.

4303 Series.str.islower : Check whether all characters are lowercase.

4304 Series.str.isascii : Check whether all characters are ascii.

4305 Series.str.isupper : Check whether all characters are uppercase.

4306 Series.str.istitle : Check whether all characters are titlecase.

4307

4308 Examples

4309 --------

4310 >>> s1 = pd.Series(["one", "one1", "1", ""])

4311 >>> s1.str.isalnum()

4312 0 True

4313 1 True

4314 2 True

4315 3 False

4316 dtype: bool

4317

4318 Note that checks against characters mixed with any additional punctuation

4319 or whitespace will evaluate to false for an alphanumeric check.

4320

4321 >>> s2 = pd.Series(["A B", "1.5", "3,000"])

4322 >>> s2.str.isalnum()

4323 0 False

4324 1 False

4325 2 False

4326 dtype: bool

4327 """

4328 result = self._data.array._str_isalnum()

4329 return self._wrap_result(result, returns_string=False)

4330

4331 @forbid_nonstring_types(["bytes"])

4332 def isalpha(self):

4333 """

4334 Check whether all characters in each string are alphabetic.

4335

4336 This is equivalent to running the Python string method

4337 :meth:`str.isalpha` for each element of the Series/Index. If a string

4338 has zero characters, ``False`` is returned for that check.

4339

4340 Returns

4341 -------

4342 Series or Index of bool

4343 Series or Index of boolean values with the same length as the original

4344 Series/Index.

4345

4346 See Also

4347 --------

4348 Series.str.isnumeric : Check whether all characters are numeric.

4349 Series.str.isalnum : Check whether all characters are alphanumeric.

4350 Series.str.isdigit : Check whether all characters are digits.

4351 Series.str.isdecimal : Check whether all characters are decimal.

4352 Series.str.isspace : Check whether all characters are whitespace.

4353 Series.str.islower : Check whether all characters are lowercase.

4354 Series.str.isascii : Check whether all characters are ascii.

4355 Series.str.isupper : Check whether all characters are uppercase.

4356 Series.str.istitle : Check whether all characters are titlecase.

4357

4358 Examples

4359 --------

4360

4361 >>> s1 = pd.Series(["one", "one1", "1", ""])

4362 >>> s1.str.isalpha()

4363 0 True

4364 1 False

4365 2 False

4366 3 False

4367 dtype: bool

4368 """

4369 result = self._data.array._str_isalpha()

4370 return self._wrap_result(result, returns_string=False)

4371

4372 @forbid_nonstring_types(["bytes"])

4373 def isdigit(self):

4374 """

4375 Check whether all characters in each string are digits.

4376

4377 This is equivalent to running the Python string method

4378 :meth:`str.isdigit` for each element of the Series/Index. If a string

4379 has zero characters, ``False`` is returned for that check.

4380

4381 Returns

4382 -------

4383 Series or Index of bool

4384 Series or Index of boolean values with the same length as the original

4385 Series/Index.

4386

4387 See Also

4388 --------

4389 Series.str.isalpha : Check whether all characters are alphabetic.

4390 Series.str.isnumeric : Check whether all characters are numeric.

4391 Series.str.isalnum : Check whether all characters are alphanumeric.

4392 Series.str.isdecimal : Check whether all characters are decimal.

4393 Series.str.isspace : Check whether all characters are whitespace.

4394 Series.str.islower : Check whether all characters are lowercase.

4395 Series.str.isascii : Check whether all characters are ascii.

4396 Series.str.isupper : Check whether all characters are uppercase.

4397 Series.str.istitle : Check whether all characters are titlecase.

4398

4399 Notes

4400 -----

4401 Similar to ``str.isdecimal`` but also includes special digits, like

4402 superscripted and subscripted digits in unicode.

4403

4404 The exact behavior of this method, i.e. which unicode characters are

4405 considered as digits, depends on the backend used for string operations,

4406 and there can be small differences.

4407 For example, Python considers the ³ superscript character as a digit, but

4408 not the ⅕ fraction character, while PyArrow considers both as digits. For

4409 simple (ascii) decimal numbers, the behaviour is consistent.

4410

4411 Examples

4412 --------

4413

4414 >>> s3 = pd.Series(["23", "³", "⅕", ""])

4415 >>> s3.str.isdigit()

4416 0 True

4417 1 True

4418 2 True

4419 3 False

4420 dtype: bool

4421 """

4422 result = self._data.array._str_isdigit()

4423 return self._wrap_result(result, returns_string=False)

4424

4425 @forbid_nonstring_types(["bytes"])

4426 def isspace(self):

4427 """

4428 Check whether all characters in each string are whitespace.

4429

4430 This is equivalent to running the Python string method

4431 :meth:`str.isspace` for each element of the Series/Index. If a string

4432 has zero characters, ``False`` is returned for that check.

4433

4434 Returns

4435 -------

4436 Series or Index of bool

4437 Series or Index of boolean values with the same length as the original

4438 Series/Index.

4439

4440 See Also

4441 --------

4442 Series.str.isalpha : Check whether all characters are alphabetic.

4443 Series.str.isnumeric : Check whether all characters are numeric.

4444 Series.str.isalnum : Check whether all characters are alphanumeric.

4445 Series.str.isdigit : Check whether all characters are digits.

4446 Series.str.isdecimal : Check whether all characters are decimal.

4447 Series.str.islower : Check whether all characters are lowercase.

4448 Series.str.isascii : Check whether all characters are ascii.

4449 Series.str.isupper : Check whether all characters are uppercase.

4450 Series.str.istitle : Check whether all characters are titlecase.

4451

4452 Examples

4453 --------

4454

4455 >>> s4 = pd.Series([" ", "\\t\\r\\n ", ""])

4456 >>> s4.str.isspace()

4457 0 True

4458 1 True

4459 2 False

4460 dtype: bool

4461 """

4462 result = self._data.array._str_isspace()

4463 return self._wrap_result(result, returns_string=False)

4464

4465 @forbid_nonstring_types(["bytes"])

4466 def islower(self):

4467 """

4468 Check whether all characters in each string are lowercase.

4469

4470 This is equivalent to running the Python string method

4471 :meth:`str.islower` for each element of the Series/Index. If a string

4472 has zero characters, ``False`` is returned for that check.

4473

4474 Returns

4475 -------

4476 Series or Index of bool

4477 Series or Index of boolean values with the same length as the original

4478 Series/Index.

4479

4480 See Also

4481 --------

4482 Series.str.isalpha : Check whether all characters are alphabetic.

4483 Series.str.isnumeric : Check whether all characters are numeric.

4484 Series.str.isalnum : Check whether all characters are alphanumeric.

4485 Series.str.isdigit : Check whether all characters are digits.

4486 Series.str.isdecimal : Check whether all characters are decimal.

4487 Series.str.isspace : Check whether all characters are whitespace.

4488 Series.str.isascii : Check whether all characters are ascii.

4489 Series.str.isupper : Check whether all characters are uppercase.

4490 Series.str.istitle : Check whether all characters are titlecase.

4491

4492 Examples

4493 --------

4494

4495 >>> s5 = pd.Series(["leopard", "Golden Eagle", "SNAKE", ""])

4496 >>> s5.str.islower()

4497 0 True

4498 1 False

4499 2 False

4500 3 False

4501 dtype: bool

4502 """

4503 result = self._data.array._str_islower()

4504 return self._wrap_result(result, returns_string=False)

4505

4506 @forbid_nonstring_types(["bytes"])

4507 def isascii(self):

4508 """

4509 Check whether all characters in each string are ascii.

4510

4511 This is equivalent to running the Python string method

4512 :meth:`str.isascii` for each element of the Series/Index. If a string

4513 has zero characters, ``False`` is returned for that check.

4514

4515 Returns

4516 -------

4517 Series or Index of bool

4518 Series or Index of boolean values with the same length as the original

4519 Series/Index.

4520

4521 See Also

4522 --------

4523 Series.str.isalpha : Check whether all characters are alphabetic.

4524 Series.str.isnumeric : Check whether all characters are numeric.

4525 Series.str.isalnum : Check whether all characters are alphanumeric.

4526 Series.str.isdigit : Check whether all characters are digits.

4527 Series.str.isdecimal : Check whether all characters are decimal.

4528 Series.str.isspace : Check whether all characters are whitespace.

4529 Series.str.islower : Check whether all characters are lowercase.

4530 Series.str.isupper : Check whether all characters are uppercase.

4531 Series.str.istitle : Check whether all characters are titlecase.

4532

4533 Examples

4534 --------

4535 The ``s5.str.isascii`` method checks for whether all characters are ascii

4536 characters, which includes digits 0-9, capital and lowercase letters A-Z,

4537 and some other special characters.

4538

4539 >>> s5 = pd.Series(["ö", "see123", "hello world", ""])

4540 >>> s5.str.isascii()

4541 0 False

4542 1 True

4543 2 True

4544 3 True

4545 dtype: bool

4546 """

4547 result = self._data.array._str_isascii()

4548 return self._wrap_result(result, returns_string=False)

4549

4550 @forbid_nonstring_types(["bytes"])

4551 def isupper(self):

4552 """

4553 Check whether all characters in each string are uppercase.

4554

4555 This is equivalent to running the Python string method

4556 :meth:`str.isupper` for each element of the Series/Index. If a string

4557 has zero characters, ``False`` is returned for that check.

4558

4559 Returns

4560 -------

4561 Series or Index of bool

4562 Series or Index of boolean values with the same length as the original

4563 Series/Index.

4564

4565 See Also

4566 --------

4567 Series.str.isalpha : Check whether all characters are alphabetic.

4568 Series.str.isnumeric : Check whether all characters are numeric.

4569 Series.str.isalnum : Check whether all characters are alphanumeric.

4570 Series.str.isdigit : Check whether all characters are digits.

4571 Series.str.isdecimal : Check whether all characters are decimal.

4572 Series.str.isspace : Check whether all characters are whitespace.

4573 Series.str.islower : Check whether all characters are lowercase.

4574 Series.str.isascii : Check whether all characters are ascii.

4575 Series.str.istitle : Check whether all characters are titlecase.

4576

4577 Examples

4578 --------

4579

4580 >>> s5 = pd.Series(["leopard", "Golden Eagle", "SNAKE", ""])

4581 >>> s5.str.isupper()

4582 0 False

4583 1 False

4584 2 True

4585 3 False

4586 dtype: bool

4587 """

4588 result = self._data.array._str_isupper()

4589 return self._wrap_result(result, returns_string=False)

4590

4591 @forbid_nonstring_types(["bytes"])

4592 def istitle(self):

4593 """

4594 Check whether all characters in each string are titlecase.

4595

4596 This is equivalent to running the Python string method

4597 :meth:`str.istitle` for each element of the Series/Index. If a string

4598 has zero characters, ``False`` is returned for that check.

4599

4600 Returns

4601 -------

4602 Series or Index of bool

4603 Series or Index of boolean values with the same length as the original

4604 Series/Index.

4605

4606 See Also

4607 --------

4608 Series.str.isalpha : Check whether all characters are alphabetic.

4609 Series.str.isnumeric : Check whether all characters are numeric.

4610 Series.str.isalnum : Check whether all characters are alphanumeric.

4611 Series.str.isdigit : Check whether all characters are digits.

4612 Series.str.isdecimal : Check whether all characters are decimal.

4613 Series.str.isspace : Check whether all characters are whitespace.

4614 Series.str.islower : Check whether all characters are lowercase.

4615 Series.str.isascii : Check whether all characters are ascii.

4616 Series.str.isupper : Check whether all characters are uppercase.

4617

4618 Examples

4619 --------

4620 The ``s5.str.istitle`` method checks for whether all words are in title

4621 case (whether only the first letter of each word is capitalized). Words are

4622 assumed to be as any sequence of non-numeric characters separated by

4623 whitespace characters.

4624

4625 >>> s5 = pd.Series(["leopard", "Golden Eagle", "SNAKE", ""])

4626 >>> s5.str.istitle()

4627 0 False

4628 1 True

4629 2 False

4630 3 False

4631 dtype: bool

4632 """

4633 result = self._data.array._str_istitle()

4634 return self._wrap_result(result, returns_string=False)

4635

4636 @forbid_nonstring_types(["bytes"])

4637 def isnumeric(self):

4638 """

4639 Check whether all characters in each string are numeric.

4640

4641 This is equivalent to running the Python string method

4642 :meth:`str.isnumeric` for each element of the Series/Index. If a string

4643 has zero characters, ``False`` is returned for that check.

4644

4645 Returns

4646 -------

4647 Series or Index of bool

4648 Series or Index of boolean values with the same length as the original

4649 Series/Index.

4650

4651 See Also

4652 --------

4653 Series.str.isalpha : Check whether all characters are alphabetic.

4654 Series.str.isalnum : Check whether all characters are alphanumeric.

4655 Series.str.isdigit : Check whether all characters are digits.

4656 Series.str.isdecimal : Check whether all characters are decimal.

4657 Series.str.isspace : Check whether all characters are whitespace.

4658 Series.str.islower : Check whether all characters are lowercase.

4659 Series.str.isascii : Check whether all characters are ascii.

4660 Series.str.isupper : Check whether all characters are uppercase.

4661 Series.str.istitle : Check whether all characters are titlecase.

4662

4663 Examples

4664 --------

4665 The ``s.str.isnumeric`` method is the same as ``s3.str.isdigit`` but

4666 also includes other characters that can represent quantities such as

4667 unicode fractions.

4668

4669 >>> s1 = pd.Series(["one", "one1", "1", "", "³", "⅕"])

4670 >>> s1.str.isnumeric()

4671 0 False

4672 1 False

4673 2 True

4674 3 False

4675 4 True

4676 5 True

4677 dtype: bool

4678

4679 For a string to be considered numeric, all its characters must have a Unicode

4680 numeric property matching :py:meth:`str.is_numeric`. As a consequence,

4681 the following cases are **not** recognized as numeric:

4682

4683 - **Decimal numbers** (e.g., "1.1"): due to period ``"."``

4684 - **Negative numbers** (e.g., "-5"): due to minus sign ``"-"``

4685 - **Scientific notation** (e.g., "1e3"): due to characters like ``"e"``

4686

4687 >>> s2 = pd.Series(["1.1", "-5", "1e3"])

4688 >>> s2.str.isnumeric()

4689 0 False

4690 1 False

4691 2 False

4692 dtype: bool

4693 """

4694 result = self._data.array._str_isnumeric()

4695 return self._wrap_result(result, returns_string=False)

4696

4697 @forbid_nonstring_types(["bytes"])

4698 def isdecimal(self):

4699 """

4700 Check whether all characters in each string are decimal.

4701

4702 This is equivalent to running the Python string method

4703 :meth:`str.isdecimal` for each element of the Series/Index. If a string

4704 has zero characters, ``False`` is returned for that check.

4705

4706 Returns

4707 -------

4708 Series or Index of bool

4709 Series or Index of boolean values with the same length as the original

4710 Series/Index.

4711

4712 See Also

4713 --------

4714 Series.str.isalpha : Check whether all characters are alphabetic.

4715 Series.str.isnumeric : Check whether all characters are numeric.

4716 Series.str.isalnum : Check whether all characters are alphanumeric.

4717 Series.str.isdigit : Check whether all characters are digits.

4718 Series.str.isspace : Check whether all characters are whitespace.

4719 Series.str.islower : Check whether all characters are lowercase.

4720 Series.str.isascii : Check whether all characters are ascii.

4721 Series.str.isupper : Check whether all characters are uppercase.

4722 Series.str.istitle : Check whether all characters are titlecase.

4723

4724 Examples

4725 --------

4726 The ``s3.str.isdecimal`` method checks for characters used to form

4727 numbers in base 10.

4728

4729 >>> s3 = pd.Series(["23", "³", "⅕", ""])

4730 >>> s3.str.isdecimal()

4731 0 True

4732 1 False

4733 2 False

4734 3 False

4735 dtype: bool

4736 """

4737 result = self._data.array._str_isdecimal()

4738 return self._wrap_result(result, returns_string=False)

4739

4740

4741def cat_safe(list_of_columns: list[npt.NDArray[np.object_]], sep: str):

4742 """

4743 Auxiliary function for :meth:`str.cat`.

4744

4745 Same signature as cat_core, but handles TypeErrors in concatenation, which

4746 happen if the arrays in list_of columns have the wrong dtypes or content.

4747

4748 Parameters

4749 ----------

4750 list_of_columns : list of numpy arrays

4751 List of arrays to be concatenated with sep;

4752 these arrays may not contain NaNs!

4753 sep : string

4754 The separator string for concatenating the columns.

4755

4756 Returns

4757 -------

4758 nd.array

4759 The concatenation of list_of_columns with sep.

4760 """

4761 try:

4762 result = cat_core(list_of_columns, sep)

4763 except TypeError:

4764 # if there are any non-string values (wrong dtype or hidden behind

4765 # object dtype), np.sum will fail; catch and return with better message

4766 for column in list_of_columns:

4767 dtype = lib.infer_dtype(column, skipna=True)

4768 if dtype not in ["string", "empty"]:

4769 raise TypeError(

4770 "Concatenation requires list-likes containing only "

4771 "strings (or missing values). Offending values found in "

4772 f"column {dtype}"

4773 ) from None

4774 return result

4775

4776

4777def cat_core(list_of_columns: list, sep: str):

4778 """

4779 Auxiliary function for :meth:`str.cat`

4780

4781 Parameters

4782 ----------

4783 list_of_columns : list of numpy arrays

4784 List of arrays to be concatenated with sep;

4785 these arrays may not contain NaNs!

4786 sep : string

4787 The separator string for concatenating the columns.

4788

4789 Returns

4790 -------

4791 nd.array

4792 The concatenation of list_of_columns with sep.

4793 """

4794 if sep == "":

4795 # no need to interleave sep if it is empty

4796 arr_of_cols = np.asarray(list_of_columns, dtype=object)

4797 return np.sum(arr_of_cols, axis=0)

4798 list_with_sep = [sep] * (2 * len(list_of_columns) - 1)

4799 list_with_sep[::2] = list_of_columns

4800 arr_with_sep = np.asarray(list_with_sep, dtype=object)

4801 return np.sum(arr_with_sep, axis=0)

4802

4803

4804def _result_dtype(arr):

4805 # workaround #27953

4806 # ideally we just pass `dtype=arr.dtype` unconditionally, but this fails

4807 # when the list of values is empty.

4808 from pandas.core.arrays.string_ import StringDtype

4809

4810 if isinstance(arr.dtype, (ArrowDtype, StringDtype)):

4811 return arr.dtype

4812 return object

4813

4814

4815def _get_single_group_name(regex: re.Pattern) -> Hashable:

4816 if regex.groupindex:

4817 return next(iter(regex.groupindex))

4818 else:

4819 return None

4820

4821

4822def _get_group_names(regex: re.Pattern) -> list[Hashable] | range:

4823 """

4824 Get named groups from compiled regex.

4825

4826 Unnamed groups are numbered.

4827

4828 Parameters

4829 ----------

4830 regex : compiled regex

4831

4832 Returns

4833 -------

4834 list of column labels

4835 """

4836 rng = range(regex.groups)

4837 names = {v: k for k, v in regex.groupindex.items()}

4838 if not names:

4839 return rng

4840 result: list[Hashable] = [names.get(1 + i, i) for i in rng]

4841 arr = np.array(result)

4842 if arr.dtype.kind == "i" and lib.is_range_indexer(arr, len(arr)):

4843 return rng

4844 return result

4845

4846

4847def str_extractall(arr, pat, flags: int = 0) -> DataFrame:

4848 regex = re.compile(pat, flags=flags)

4849 # the regex must contain capture groups.

4850 if regex.groups == 0:

4851 raise ValueError("pattern contains no capture groups")

4852

4853 if isinstance(arr, ABCIndex):

4854 arr = arr.to_series().reset_index(drop=True).astype(arr.dtype)

4855

4856 columns = _get_group_names(regex)

4857 match_list = []

4858 index_list = []

4859 is_mi = arr.index.nlevels > 1

4860

4861 for subject_key, subject in arr.items():

4862 if isinstance(subject, str):

4863 if not is_mi:

4864 subject_key = (subject_key,)

4865

4866 for match_i, match_tuple in enumerate(regex.findall(subject)):

4867 if isinstance(match_tuple, str):

4868 match_tuple = (match_tuple,)

4869 na_tuple = [np.nan if group == "" else group for group in match_tuple]

4870 match_list.append(na_tuple)

4871 result_key = (*subject_key, match_i)

4872 index_list.append(result_key)

4873

4874 from pandas import MultiIndex

4875

4876 index = MultiIndex.from_tuples(index_list, names=[*arr.index.names, "match"])

4877 dtype = _result_dtype(arr)

4878

4879 result = arr._constructor_expanddim(

4880 match_list, index=index, columns=columns, dtype=dtype

4881 )

4882 return result