From 1e165408acbaaa5b08f4c63f000e229be54276e3 Mon Sep 17 00:00:00 2001 From: alkamid Date: Sun, 29 Apr 2018 12:19:12 +0100 Subject: [PATCH 1/5] DOC: Improve the docstring of String.str.zfill() --- pandas/core/strings.py | 43 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 39 insertions(+), 4 deletions(-) diff --git a/pandas/core/strings.py b/pandas/core/strings.py index c6d45ce5413ac..57fd4f2e042c0 100644 --- a/pandas/core/strings.py +++ b/pandas/core/strings.py @@ -2114,19 +2114,54 @@ def rjust(self, width, fillchar=' '): def zfill(self, width): """ - Filling left side of strings in the Series/Index with 0. - Equivalent to :meth:`str.zfill`. + Pad strings in the Series/Index by prepending '0' characters. + Strings in the Series/Index are padded with prepending '0' characeters + (i.e. on the left of the string) to reach a total string length of `width`. + Strings in the Series/Index with length greater than `width` are unchanged. + + Note: Differs from :meth:`str.zfill` which has special handling for '+'/'-' + characters in the string. + Parameters ---------- width : int - Minimum width of resulting string; additional characters will be - filled with 0 + Minimum length of resulting string; strings with length less than `width` + will be prepended with '0' characters. Returns ------- filled : Series/Index of objects + + See Also + -------- + Series.str.rjust: Fills the left side of strings with an arbitrary + character. + Series.str.ljust: Fills the right side of strings with an arbitrary + character. + Series.str.pad: Fills the specified sides of strings with an arbitrary + character. + Series.str.center: Fills boths sides of strings with an arbitrary + character. + + Examples + -------- + >>> s = pd.Series(['-2', '+5', '10', '127', '423523']) + >>> s.str.zfill(5) + 0 000-2 + 1 000+5 + 2 00010 + 3 00127 + 4 423523 + dtype: object + + >>> s = pd.Series([-2, 5], dtype=str) + >>> s.str.zfill(5) + 0 000-2 + 1 00005 + dtype: object """ + result = str_pad(self._data, width, side='left', fillchar='0') return self._wrap_result(result) From b89cd54aa0e829422f76c6d139e139f8b186b599 Mon Sep 17 00:00:00 2001 From: alkamid Date: Sun, 29 Apr 2018 12:22:55 +0100 Subject: [PATCH 2/5] Fix PEP8 errors --- pandas/core/strings.py | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/pandas/core/strings.py b/pandas/core/strings.py index 57fd4f2e042c0..e07b95a1b0683 100644 --- a/pandas/core/strings.py +++ b/pandas/core/strings.py @@ -2117,17 +2117,18 @@ def zfill(self, width): Pad strings in the Series/Index by prepending '0' characters. Strings in the Series/Index are padded with prepending '0' characeters - (i.e. on the left of the string) to reach a total string length of `width`. - Strings in the Series/Index with length greater than `width` are unchanged. + (i.e. on the left of the string) to reach a total string length + of `width`. in the Series/Index with length greater than `width` + are unchanged. + + Note: Differs from :meth:`str.zfill` which has special handling + for '+'/'-' in the string. - Note: Differs from :meth:`str.zfill` which has special handling for '+'/'-' - characters in the string. - Parameters ---------- width : int - Minimum length of resulting string; strings with length less than `width` - will be prepended with '0' characters. + Minimum length of resulting string; strings with length less + than `width` be prepended with '0' characters. Returns ------- From 07f41898bd96aa000e2394675b03fb86f81dbadb Mon Sep 17 00:00:00 2001 From: alkamid Date: Mon, 30 Apr 2018 22:24:18 +0100 Subject: [PATCH 3/5] Correct language, add more concise example --- pandas/core/strings.py | 38 +++++++++++++++++++++----------------- 1 file changed, 21 insertions(+), 17 deletions(-) diff --git a/pandas/core/strings.py b/pandas/core/strings.py index e07b95a1b0683..3285b8151cfd5 100644 --- a/pandas/core/strings.py +++ b/pandas/core/strings.py @@ -2116,13 +2116,9 @@ def zfill(self, width): """ Pad strings in the Series/Index by prepending '0' characters. - Strings in the Series/Index are padded with prepending '0' characeters - (i.e. on the left of the string) to reach a total string length - of `width`. in the Series/Index with length greater than `width` - are unchanged. - - Note: Differs from :meth:`str.zfill` which has special handling - for '+'/'-' in the string. + Strings in the Series/Index are padded with '0' characters on the + left of the string to reach a total string length `width`. Strings + in the Series/Index with length greater or equal to `width` are unchanged. Parameters ---------- @@ -2132,7 +2128,7 @@ def zfill(self, width): Returns ------- - filled : Series/Index of objects + Series/Index of objects See Also -------- @@ -2145,21 +2141,29 @@ def zfill(self, width): Series.str.center: Fills boths sides of strings with an arbitrary character. + Notes + ----- + Differs from :meth:`str.zfill` which has special handling + for '+'/'-' in the string. + Examples -------- - >>> s = pd.Series(['-2', '+5', '10', '127', '423523']) + >>> s = pd.Series(['-2', '+5', '10', '423523', 127, np.nan]) + >>> s + 0 -2 + 1 +5 + 2 10 + 3 423523 + 4 127 + 5 NaN + dtype: object >>> s.str.zfill(5) 0 000-2 1 000+5 2 00010 - 3 00127 - 4 423523 - dtype: object - - >>> s = pd.Series([-2, 5], dtype=str) - >>> s.str.zfill(5) - 0 000-2 - 1 00005 + 3 423523 + 4 NaN + 5 NaN dtype: object """ From 8034856acd2f412a9fb0ed1e286f97edc4720e3d Mon Sep 17 00:00:00 2001 From: alkamid Date: Mon, 30 Apr 2018 22:26:32 +0100 Subject: [PATCH 4/5] Fix PEP8 errors --- pandas/core/strings.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/pandas/core/strings.py b/pandas/core/strings.py index 3285b8151cfd5..6c00dd605d640 100644 --- a/pandas/core/strings.py +++ b/pandas/core/strings.py @@ -2118,7 +2118,8 @@ def zfill(self, width): Strings in the Series/Index are padded with '0' characters on the left of the string to reach a total string length `width`. Strings - in the Series/Index with length greater or equal to `width` are unchanged. + in the Series/Index with length greater or equal to `width` are + unchanged. Parameters ---------- @@ -2144,7 +2145,7 @@ def zfill(self, width): Notes ----- Differs from :meth:`str.zfill` which has special handling - for '+'/'-' in the string. + for '+'/'-' in the string. Examples -------- From 60ea781803f91a31bdddb67b19a954fbebdc3102 Mon Sep 17 00:00:00 2001 From: alkamid Date: Wed, 2 May 2018 22:29:41 +0100 Subject: [PATCH 5/5] Explain behaviour in the example --- pandas/core/strings.py | 34 +++++++++++++++++++--------------- 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/pandas/core/strings.py b/pandas/core/strings.py index 6c00dd605d640..e6ff4643784b9 100644 --- a/pandas/core/strings.py +++ b/pandas/core/strings.py @@ -2149,25 +2149,29 @@ def zfill(self, width): Examples -------- - >>> s = pd.Series(['-2', '+5', '10', '423523', 127, np.nan]) + >>> s = pd.Series(['-1', '1', '1000', 10, np.nan]) >>> s - 0 -2 - 1 +5 - 2 10 - 3 423523 - 4 127 - 5 NaN + 0 -1 + 1 1 + 2 1000 + 3 10 + 4 NaN dtype: object - >>> s.str.zfill(5) - 0 000-2 - 1 000+5 - 2 00010 - 3 423523 - 4 NaN - 5 NaN + + Note that ``10`` and ``NaN`` are not strings, therefore they are + converted to ``NaN``. The minus sign in ``'-1'`` is treated as a + regular character and the zero is added to the left of it + (:meth:`str.zfill` would have moved it to the left). ``1000`` + remains unchanged as it is longer than `width`. + + >>> s.str.zfill(3) + 0 0-1 + 1 001 + 2 1000 + 3 NaN + 4 NaN dtype: object """ - result = str_pad(self._data, width, side='left', fillchar='0') return self._wrap_result(result)