DOC: Add examples to Series.str.slice() with negative arguments GH27802

[phillipwalters]

• closes DOC: Series.str.slice() should show that negative values for start are allowed #27802
• tests added / passed
• passes black pandas
• passes git diff upstream/master -u -- "*.py" | flake8 --diff
• [N/A] whatsnew entry

[pep8speaks]

Hello @phillipwalters! Thanks for updating this PR. We checked the lines you've touched for PEP 8 issues, and found:

There are currently no PEP 8 issues detected in this Pull Request. Cheers! 🍻

Comment last updated at 2019-08-09 04:50:22 UTC

[phillipwalters]

$ python scripts/validate_docstrings.py pandas.Series.str.slice

################################################################################
##################### Docstring (pandas.Series.str.slice) #####################
################################################################################

Slice substrings from each element in the Series or Index.

Parameters

start : int, optional
Start position for slice operation.
stop : int, optional
Stop position for slice operation.
step : int, optional
Step size for slice operation.

Returns

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

See Also

Series.str.slice_replace : Replace a slice with a string.
Series.str.get : Return element at position.
Equivalent to Series.str.slice(start=i, stop=i+1) with i
being the position.

Examples

s = pd.Series(["koala", "fox", "chameleon"])
s
0 koala
1 fox
2 chameleon
dtype: object

s.str.slice(start=1)
0 oala
1 ox
2 hameleon
dtype: object

s.str.slice(stop=2)
0 ko
1 fo
2 ch
dtype: object

s.str.slice(step=2)
0 kaa
1 fx
2 caeen
dtype: object

Negative values can be used for any of the three parameters. For start or stop, a value of -1 will be the last
character of the string, -2 the second to last, and so on. Examples:

s.str.slice(start=-3)
0 ala
1 fox
2 eon
dtype: object

s.str.slice(stop=-2)
0 koa
1 f
2 chamele
dtype: object

A negative value for step will simply step in the other direction.

s.str.slice(step=-1)
0 alaok
1 xof
2 noelemahc
dtype: object

s.str.slice(stop=1, step=-1)
0 ala
1 x
2 noelema
dtype: object

s.str.slice(start=0, stop=5, step=3)
0 kl
1 f
2 cm
dtype: object

Equivalent behaviour to:

s.str[0:5:3]
0 kl
1 f
2 cm
dtype: object

################################################################################
################################## Validation ##################################
################################################################################

1 Warnings found:
No extended summary found
Docstring for "pandas.Series.str.slice" correct. :)

[topper-123]

This is a bit too much, and a single example with negative indexes is enough. If you wantvto to rebase and add the text snippet, that would be nice.

[TomAugspurger]

Seems like https://github.com/pandas-dev/pandas/pull/27832/files also worked on this. @phillipwalters perhaps just add one more example showing a negative slice to reverse the string?

[Dr-Irv]

@phillipwalters Maybe add an example that uses the shorthand notation, e.g.:

In [6]: s.str[:-1]
Out[6]:
0      A
1     BC
2    DEF
dtype: object

[phillipwalters]

I saw his PR shortly after I submitted this one, and it looks like you guys went with that one. Sounds like the right choice to me. Thanks for your guys' suggestions, though!