diff --git a/pandas/core/strings.py b/pandas/core/strings.py index b27cfdfe3f1bd..93e6f8a53c804 100644 --- a/pandas/core/strings.py +++ b/pandas/core/strings.py @@ -2473,18 +2473,63 @@ 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 '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 ---------- 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` be prepended with '0' characters. Returns ------- - filled : Series/Index of objects + 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. + + Notes + ----- + Differs from :meth:`str.zfill` which has special handling + for '+'/'-' in the string. + + Examples + -------- + >>> s = pd.Series(['-1', '1', '1000', 10, np.nan]) + >>> s + 0 -1 + 1 1 + 2 1000 + 3 10 + 4 NaN + dtype: object + + 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)