"""

This module contains a set of functions for vectorized string

operations.

"""

import functools

import sys

import numpy as np

from numpy import (

add,

equal,

greater,

greater_equal,

less,

less_equal,

multiply as _multiply_ufunc,

not_equal,

)

from numpy._core.multiarray import _vec_string

from numpy._core.overrides import array_function_dispatch, set_module

from numpy._core.umath import (

_center,

_expandtabs,

_expandtabs_length,

_ljust,

_lstrip_chars,

_lstrip_whitespace,

_partition,

_partition_index,

_replace,

_rjust,

_rpartition,

_rpartition_index,

_rstrip_chars,

_rstrip_whitespace,

_slice,

_strip_chars,

_strip_whitespace,

_zfill,

count as _count_ufunc,

endswith as _endswith_ufunc,

find as _find_ufunc,

index as _index_ufunc,

isalnum,

isalpha,

isdecimal,

isdigit,

islower,

isnumeric,

isspace,

istitle,

isupper,

rfind as _rfind_ufunc,

rindex as _rindex_ufunc,

startswith as _startswith_ufunc,

str_len,

)

def _override___module__():

for ufunc in [

isalnum, isalpha, isdecimal, isdigit, islower, isnumeric, isspace,

istitle, isupper, str_len,

]:

ufunc.__module__ = "numpy.strings"

ufunc.__qualname__ = ufunc.__name__

_override___module__()

__all__ = [

# UFuncs

"equal", "not_equal", "less", "less_equal", "greater", "greater_equal",

"add", "multiply", "isalpha", "isdigit", "isspace", "isalnum", "islower",

"isupper", "istitle", "isdecimal", "isnumeric", "str_len", "find",

"rfind", "index", "rindex", "count", "startswith", "endswith", "lstrip",

"rstrip", "strip", "replace", "expandtabs", "center", "ljust", "rjust",

"zfill", "partition", "rpartition", "slice",

# _vec_string - Will gradually become ufuncs as well

"upper", "lower", "swapcase", "capitalize", "title",

# _vec_string - Will probably not become ufuncs

"mod", "decode", "encode", "translate",

# Removed from namespace until behavior has been crystallized

# "join", "split", "rsplit", "splitlines",

]

MAX = np.iinfo(np.int64).max

array_function_dispatch = functools.partial(

array_function_dispatch, module='numpy.strings')

def _get_num_chars(a):

"""

Helper function that returns the number of characters per field in

a string or unicode array. This is to abstract out the fact that

for a unicode array this is itemsize / 4.

"""

if issubclass(a.dtype.type, np.str_):

return a.itemsize // 4

return a.itemsize

def _to_bytes_or_str_array(result, output_dtype_like):

"""

Helper function to cast a result back into an array

with the appropriate dtype if an object array must be used

as an intermediary.

"""

output_dtype_like = np.asarray(output_dtype_like)

if result.size == 0:

# Calling asarray & tolist in an empty array would result

# in losing shape information

return result.astype(output_dtype_like.dtype)

ret = np.asarray(result.tolist())

if isinstance(output_dtype_like.dtype, np.dtypes.StringDType):

return ret.astype(type(output_dtype_like.dtype))

return ret.astype(type(output_dtype_like.dtype)(_get_num_chars(ret)))

def _clean_args(*args):

"""

Helper function for delegating arguments to Python string

functions.

Many of the Python string operations that have optional arguments

do not use 'None' to indicate a default value. In these cases,

we need to remove all None arguments, and those following them.

"""

newargs = []

for chk in args:

if chk is None:

break

newargs.append(chk)

return newargs

def _multiply_dispatcher(a, i):

return (a,)

@set_module("numpy.strings")

@array_function_dispatch(_multiply_dispatcher)

def multiply(a, i):

"""

Return (a * i), that is string multiple concatenation,

element-wise.

Values in ``i`` of less than 0 are treated as 0 (which yields an

empty string).

Parameters

----------

a : array_like, with ``StringDType``, ``bytes_`` or ``str_`` dtype

i : array_like, with any integer dtype

Returns

-------

out : ndarray

Output array of ``StringDType``, ``bytes_`` or ``str_`` dtype,

depending on input types

Examples

--------

>>> import numpy as np

>>> a = np.array(["a", "b", "c"])

>>> np.strings.multiply(a, 3)

array(['aaa', 'bbb', 'ccc'], dtype='<U3')

>>> i = np.array([1, 2, 3])

>>> np.strings.multiply(a, i)

array(['a', 'bb', 'ccc'], dtype='<U3')

>>> np.strings.multiply(np.array(['a']), i)

array(['a', 'aa', 'aaa'], dtype='<U3')

>>> a = np.array(['a', 'b', 'c', 'd', 'e', 'f']).reshape((2, 3))

>>> np.strings.multiply(a, 3)

array([['aaa', 'bbb', 'ccc'],

['ddd', 'eee', 'fff']], dtype='<U3')

>>> np.strings.multiply(a, i)

array([['a', 'bb', 'ccc'],

['d', 'ee', 'fff']], dtype='<U3')

"""

a = np.asanyarray(a)

i = np.asanyarray(i)

if not np.issubdtype(i.dtype, np.integer):

raise TypeError(f"unsupported type {i.dtype} for operand 'i'")

i = np.maximum(i, 0)

# delegate to stringdtype loops that also do overflow checking

if a.dtype.char == "T":

return a * i

a_len = str_len(a)

# Ensure we can do a_len * i without overflow.

if np.any(a_len > sys.maxsize / np.maximum(i, 1)):

raise OverflowError("Overflow encountered in string multiply")

buffersizes = a_len * i

out_dtype = f"{a.dtype.char}{buffersizes.max()}"

out = np.empty_like(a, shape=buffersizes.shape, dtype=out_dtype)

return _multiply_ufunc(a, i, out=out)

def _mod_dispatcher(a, values):

return (a, values)

@set_module("numpy.strings")

@array_function_dispatch(_mod_dispatcher)

def mod(a, values):

"""

Return (a % i), that is pre-Python 2.6 string formatting

(interpolation), element-wise for a pair of array_likes of str

or unicode.

Parameters

----------

a : array_like, with ``bytes_`` or ``str_`` dtype

values : array_like of values

These values will be element-wise interpolated into the string.

Returns

-------

out : ndarray

Output array of ``StringDType``, ``bytes_`` or ``str_`` dtype,

depending on input types

Examples

--------

>>> import numpy as np

>>> a = np.array(["NumPy is a %s library"])

>>> np.strings.mod(a, values=["Python"])

array(['NumPy is a Python library'], dtype='<U25')

>>> a = np.array([b'%d bytes', b'%d bits'])

>>> values = np.array([8, 64])

>>> np.strings.mod(a, values)

array([b'8 bytes', b'64 bits'], dtype='|S7')

"""

return _to_bytes_or_str_array(

_vec_string(a, np.object_, '__mod__', (values,)), a)

@set_module("numpy.strings")

def find(a, sub, start=0, end=None):

"""

For each element, return the lowest index in the string where

substring ``sub`` is found, such that ``sub`` is contained in the

range [``start``, ``end``).

Parameters

----------

a : array_like, with ``StringDType``, ``bytes_`` or ``str_`` dtype

sub : array_like, with ``bytes_`` or ``str_`` dtype

The substring to search for.

start, end : array_like, with any integer dtype

The range to look in, interpreted as in slice notation.

Returns

-------

y : ndarray

Output array of ints

See Also

--------

str.find

Examples

--------

>>> import numpy as np

>>> a = np.array(["NumPy is a Python library"])

>>> np.strings.find(a, "Python")

array([11])

"""

end = end if end is not None else MAX

return _find_ufunc(a, sub, start, end)

@set_module("numpy.strings")

def rfind(a, sub, start=0, end=None):

"""

For each element, return the highest index in the string where

substring ``sub`` is found, such that ``sub`` is contained in the

range [``start``, ``end``).

Parameters

----------

a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype

sub : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype

The substring to search for.

start, end : array_like, with any integer dtype

The range to look in, interpreted as in slice notation.

Returns

-------

y : ndarray

Output array of ints

See Also

--------

str.rfind

Examples

--------

>>> import numpy as np

>>> a = np.array(["Computer Science"])

>>> np.strings.rfind(a, "Science", start=0, end=None)

array([9])

>>> np.strings.rfind(a, "Science", start=0, end=8)

array([-1])

>>> b = np.array(["Computer Science", "Science"])

>>> np.strings.rfind(b, "Science", start=0, end=None)

array([9, 0])

"""

end = end if end is not None else MAX

return _rfind_ufunc(a, sub, start, end)

@set_module("numpy.strings")

def index(a, sub, start=0, end=None):

"""

Like `find`, but raises :exc:`ValueError` when the substring is not found.

Parameters

----------

a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype

sub : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype

start, end : array_like, with any integer dtype, optional

Returns

-------

out : ndarray

Output array of ints.

See Also

--------

find, str.index

Examples

--------

>>> import numpy as np

>>> a = np.array(["Computer Science"])

>>> np.strings.index(a, "Science", start=0, end=None)

array([9])

"""

end = end if end is not None else MAX

return _index_ufunc(a, sub, start, end)

@set_module("numpy.strings")

def rindex(a, sub, start=0, end=None):

"""

Like `rfind`, but raises :exc:`ValueError` when the substring `sub` is

not found.

Parameters

----------

a : array-like, with ``bytes_`` or ``str_`` dtype

sub : array-like, with ``bytes_`` or ``str_`` dtype

start, end : array-like, with any integer dtype, optional

Returns

-------

out : ndarray

Output array of ints.

See Also

--------

rfind, str.rindex

Examples

--------

>>> a = np.array(["Computer Science"])

>>> np.strings.rindex(a, "Science", start=0, end=None)

array([9])

"""

end = end if end is not None else MAX

return _rindex_ufunc(a, sub, start, end)

@set_module("numpy.strings")

def count(a, sub, start=0, end=None):

"""

Returns an array with the number of non-overlapping occurrences of

substring ``sub`` in the range [``start``, ``end``).

Parameters

----------

a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype

sub : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype

The substring to search for.

start, end : array_like, with any integer dtype

The range to look in, interpreted as in slice notation.

Returns

-------

y : ndarray

Output array of ints

See Also

--------

str.count

Examples

--------

>>> import numpy as np

>>> c = np.array(['aAaAaA', ' aA ', 'abBABba'])

>>> c

array(['aAaAaA', ' aA ', 'abBABba'], dtype='<U7')

>>> np.strings.count(c, 'A')

array([3, 1, 1])

>>> np.strings.count(c, 'aA')

array([3, 1, 0])

>>> np.strings.count(c, 'A', start=1, end=4)

array([2, 1, 1])

>>> np.strings.count(c, 'A', start=1, end=3)

array([1, 0, 0])

"""

end = end if end is not None else MAX

return _count_ufunc(a, sub, start, end)

@set_module("numpy.strings")

def startswith(a, prefix, start=0, end=None):

"""

Returns a boolean array which is `True` where the string element

in ``a`` starts with ``prefix``, otherwise `False`.

Parameters

----------

a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype

prefix : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype

start, end : array_like, with any integer dtype

With ``start``, test beginning at that position. With ``end``,

stop comparing at that position.

Returns

-------

out : ndarray

Output array of bools

See Also

--------

str.startswith

Examples

--------

>>> import numpy as np

>>> s = np.array(['foo', 'bar'])

>>> s

array(['foo', 'bar'], dtype='<U3')

>>> np.strings.startswith(s, 'fo')

array([True, False])

>>> np.strings.startswith(s, 'o', start=1, end=2)

array([True, False])

"""

end = end if end is not None else MAX

return _startswith_ufunc(a, prefix, start, end)

@set_module("numpy.strings")

def endswith(a, suffix, start=0, end=None):

"""

Returns a boolean array which is `True` where the string element

in ``a`` ends with ``suffix``, otherwise `False`.

Parameters

----------

a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype

suffix : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype

start, end : array_like, with any integer dtype

With ``start``, test beginning at that position. With ``end``,

stop comparing at that position.

Returns

-------

out : ndarray

Output array of bools

See Also

--------

str.endswith

Examples

--------

>>> import numpy as np

>>> s = np.array(['foo', 'bar'])

>>> s

array(['foo', 'bar'], dtype='<U3')

>>> np.strings.endswith(s, 'ar')

array([False, True])

>>> np.strings.endswith(s, 'a', start=1, end=2)

array([False, True])

"""

end = end if end is not None else MAX

return _endswith_ufunc(a, suffix, start, end)

def _code_dispatcher(a, encoding=None, errors=None):

return (a,)

@set_module("numpy.strings")

@array_function_dispatch(_code_dispatcher)

def decode(a, encoding=None, errors=None):

r"""

Calls :meth:`bytes.decode` element-wise.

The set of available codecs comes from the Python standard library,

and may be extended at runtime. For more information, see the

:mod:`codecs` module.

Parameters

----------

a : array_like, with ``bytes_`` dtype

encoding : str, optional

The name of an encoding

errors : str, optional

Specifies how to handle encoding errors

Returns

-------

out : ndarray

See Also

--------

:py:meth:`bytes.decode`

Notes

-----

The type of the result will depend on the encoding specified.

Examples

--------

>>> import numpy as np

>>> c = np.array([b'\x81\xc1\x81\xc1\x81\xc1', b'@@\x81\xc1@@',

... b'\x81\x82\xc2\xc1\xc2\x82\x81'])

>>> c

array([b'\x81\xc1\x81\xc1\x81\xc1', b'@@\x81\xc1@@',

b'\x81\x82\xc2\xc1\xc2\x82\x81'], dtype='|S7')

>>> np.strings.decode(c, encoding='cp037')

array(['aAaAaA', ' aA ', 'abBABba'], dtype='<U7')

"""

return _to_bytes_or_str_array(

_vec_string(a, np.object_, 'decode', _clean_args(encoding, errors)),

np.str_(''))

@set_module("numpy.strings")

@array_function_dispatch(_code_dispatcher)

def encode(a, encoding=None, errors=None):

"""

Calls :meth:`str.encode` element-wise.

The set of available codecs comes from the Python standard library,

and may be extended at runtime. For more information, see the

:mod:`codecs` module.

Parameters

----------

a : array_like, with ``StringDType`` or ``str_`` dtype

encoding : str, optional

The name of an encoding

errors : str, optional

Specifies how to handle encoding errors

Returns

-------

out : ndarray

See Also

--------

str.encode

Notes

-----

The type of the result will depend on the encoding specified.

Examples

--------

>>> import numpy as np

>>> a = np.array(['aAaAaA', ' aA ', 'abBABba'])

>>> np.strings.encode(a, encoding='cp037')

array([b'\x81\xc1\x81\xc1\x81\xc1', b'@@\x81\xc1@@',

b'\x81\x82\xc2\xc1\xc2\x82\x81'], dtype='|S7')

"""

return _to_bytes_or_str_array(

_vec_string(a, np.object_, 'encode', _clean_args(encoding, errors)),

np.bytes_(b''))

def _expandtabs_dispatcher(a, tabsize=None):

return (a,)

@set_module("numpy.strings")

@array_function_dispatch(_expandtabs_dispatcher)

def expandtabs(a, tabsize=8):

"""

Return a copy of each string element where all tab characters are

replaced by one or more spaces.

Calls :meth:`str.expandtabs` element-wise.

Return a copy of each string element where all tab characters are

replaced by one or more spaces, depending on the current column

and the given `tabsize`. The column number is reset to zero after

each newline occurring in the string. This doesn't understand other

non-printing characters or escape sequences.

Parameters

----------

a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype

Input array

tabsize : int, optional

Replace tabs with `tabsize` number of spaces. If not given defaults

to 8 spaces.

Returns

-------

out : ndarray

Output array of ``StringDType``, ``bytes_`` or ``str_`` dtype,

depending on input type

See Also

--------

str.expandtabs

Examples

--------

>>> import numpy as np

>>> a = np.array(['\t\tHello\tworld'])

>>> np.strings.expandtabs(a, tabsize=4) # doctest: +SKIP

array([' Hello world'], dtype='<U21') # doctest: +SKIP

"""

a = np.asanyarray(a)

tabsize = np.asanyarray(tabsize)

if a.dtype.char == "T":

return _expandtabs(a, tabsize)

buffersizes = _expandtabs_length(a, tabsize)

out_dtype = f"{a.dtype.char}{buffersizes.max()}"

out = np.empty_like(a, shape=buffersizes.shape, dtype=out_dtype)

return _expandtabs(a, tabsize, out=out)

def _just_dispatcher(a, width, fillchar=None):

return (a,)

@set_module("numpy.strings")

@array_function_dispatch(_just_dispatcher)

def center(a, width, fillchar=' '):

"""

Return a copy of `a` with its elements centered in a string of

length `width`.

Parameters

----------

a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype

width : array_like, with any integer dtype

The length of the resulting strings, unless ``width < str_len(a)``.

fillchar : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype

Optional padding character to use (default is space).

Returns

-------

out : ndarray

Output array of ``StringDType``, ``bytes_`` or ``str_`` dtype,

depending on input types

See Also

--------

str.center

Notes

-----

While it is possible for ``a`` and ``fillchar`` to have different dtypes,

passing a non-ASCII character in ``fillchar`` when ``a`` is of dtype "S"

is not allowed, and a ``ValueError`` is raised.

Examples

--------

>>> import numpy as np

>>> c = np.array(['a1b2','1b2a','b2a1','2a1b']); c

array(['a1b2', '1b2a', 'b2a1', '2a1b'], dtype='<U4')

>>> np.strings.center(c, width=9)

array([' a1b2 ', ' 1b2a ', ' b2a1 ', ' 2a1b '], dtype='<U9')

>>> np.strings.center(c, width=9, fillchar='*')

array(['***a1b2**', '***1b2a**', '***b2a1**', '***2a1b**'], dtype='<U9')

>>> np.strings.center(c, width=1)

array(['a1b2', '1b2a', 'b2a1', '2a1b'], dtype='<U4')

"""

width = np.asanyarray(width)

if not np.issubdtype(width.dtype, np.integer):

raise TypeError(f"unsupported type {width.dtype} for operand 'width'")

a = np.asanyarray(a)

fillchar = np.asanyarray(fillchar)

if np.any(str_len(fillchar) != 1):

raise TypeError(

"The fill character must be exactly one character long")

if np.result_type(a, fillchar).char == "T":

return _center(a, width, fillchar)

fillchar = fillchar.astype(a.dtype, copy=False)

width = np.maximum(str_len(a), width)

out_dtype = f"{a.dtype.char}{width.max()}"

shape = np.broadcast_shapes(a.shape, width.shape, fillchar.shape)

out = np.empty_like(a, shape=shape, dtype=out_dtype)

return _center(a, width, fillchar, out=out)

@set_module("numpy.strings")

@array_function_dispatch(_just_dispatcher)

def ljust(a, width, fillchar=' '):

"""

Return an array with the elements of `a` left-justified in a

string of length `width`.

Parameters

----------

a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype

width : array_like, with any integer dtype

The length of the resulting strings, unless ``width < str_len(a)``.

fillchar : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype

Optional character to use for padding (default is space).

Returns

-------

out : ndarray

Output array of ``StringDType``, ``bytes_`` or ``str_`` dtype,

depending on input types

See Also

--------

str.ljust

Notes

-----

While it is possible for ``a`` and ``fillchar`` to have different dtypes,

passing a non-ASCII character in ``fillchar`` when ``a`` is of dtype "S"

is not allowed, and a ``ValueError`` is raised.

Examples

--------

>>> import numpy as np

>>> c = np.array(['aAaAaA', ' aA ', 'abBABba'])

>>> np.strings.ljust(c, width=3)

array(['aAaAaA', ' aA ', 'abBABba'], dtype='<U7')

>>> np.strings.ljust(c, width=9)

array(['aAaAaA ', ' aA ', 'abBABba '], dtype='<U9')

"""

width = np.asanyarray(width)

if not np.issubdtype(width.dtype, np.integer):

raise TypeError(f"unsupported type {width.dtype} for operand 'width'")

a = np.asanyarray(a)

fillchar = np.asanyarray(fillchar)

if np.any(str_len(fillchar) != 1):

raise TypeError(

"The fill character must be exactly one character long")

if np.result_type(a, fillchar).char == "T":

return _ljust(a, width, fillchar)

fillchar = fillchar.astype(a.dtype, copy=False)

width = np.maximum(str_len(a), width)

shape = np.broadcast_shapes(a.shape, width.shape, fillchar.shape)

out_dtype = f"{a.dtype.char}{width.max()}"

out = np.empty_like(a, shape=shape, dtype=out_dtype)

return _ljust(a, width, fillchar, out=out)

@set_module("numpy.strings")

@array_function_dispatch(_just_dispatcher)

def rjust(a, width, fillchar=' '):

"""

Return an array with the elements of `a` right-justified in a

string of length `width`.

Parameters

----------

a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype

width : array_like, with any integer dtype

The length of the resulting strings, unless ``width < str_len(a)``.

fillchar : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype

Optional padding character to use (default is space).

Returns

-------

out : ndarray

Output array of ``StringDType``, ``bytes_`` or ``str_`` dtype,

depending on input types

See Also

--------

str.rjust

Notes

-----

While it is possible for ``a`` and ``fillchar`` to have different dtypes,

passing a non-ASCII character in ``fillchar`` when ``a`` is of dtype "S"

is not allowed, and a ``ValueError`` is raised.

Examples

--------

>>> import numpy as np

>>> a = np.array(['aAaAaA', ' aA ', 'abBABba'])

>>> np.strings.rjust(a, width=3)

array(['aAaAaA', ' aA ', 'abBABba'], dtype='<U7')

>>> np.strings.rjust(a, width=9)

array([' aAaAaA', ' aA ', ' abBABba'], dtype='<U9')

"""

width = np.asanyarray(width)

if not np.issubdtype(width.dtype, np.integer):

raise TypeError(f"unsupported type {width.dtype} for operand 'width'")

a = np.asanyarray(a)

fillchar = np.asanyarray(fillchar)

if np.any(str_len(fillchar) != 1):

raise TypeError(

"The fill character must be exactly one character long")

if np.result_type(a, fillchar).char == "T":

return _rjust(a, width, fillchar)

fillchar = fillchar.astype(a.dtype, copy=False)

width = np.maximum(str_len(a), width)

shape = np.broadcast_shapes(a.shape, width.shape, fillchar.shape)

out_dtype = f"{a.dtype.char}{width.max()}"

out = np.empty_like(a, shape=shape, dtype=out_dtype)

return _rjust(a, width, fillchar, out=out)

def _zfill_dispatcher(a, width):

return (a,)

@set_module("numpy.strings")

@array_function_dispatch(_zfill_dispatcher)

def zfill(a, width):

"""

Return the numeric string left-filled with zeros. A leading

sign prefix (``+``/``-``) is handled by inserting the padding

after the sign character rather than before.

Parameters

----------

a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype

width : array_like, with any integer dtype

Width of string to left-fill elements in `a`.

Returns

-------

out : ndarray

Output array of ``StringDType``, ``bytes_`` or ``str_`` dtype,

depending on input type

See Also

--------

str.zfill

Examples

--------

>>> import numpy as np

>>> np.strings.zfill(['1', '-1', '+1'], 3)

array(['001', '-01', '+01'], dtype='<U3')

"""

width = np.asanyarray(width)

if not np.issubdtype(width.dtype, np.integer):

raise TypeError(f"unsupported type {width.dtype} for operand 'width'")

a = np.asanyarray(a)

if a.dtype.char == "T":

return _zfill(a, width)

width = np.maximum(str_len(a), width)

shape = np.broadcast_shapes(a.shape, width.shape)

out_dtype = f"{a.dtype.char}{width.max()}"

out = np.empty_like(a, shape=shape, dtype=out_dtype)

return _zfill(a, width, out=out)

@set_module("numpy.strings")

def lstrip(a, chars=None):

"""

For each element in `a`, return a copy with the leading characters

removed.

Parameters

----------

a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype

chars : scalar with the same dtype as ``a``, optional

The ``chars`` argument is a string specifying the set of

characters to be removed. If ``None``, the ``chars``

argument defaults to removing whitespace. The ``chars`` argument

is not a prefix or suffix; rather, all combinations of its

values are stripped.

Returns

-------

out : ndarray

Output array of ``StringDType``, ``bytes_`` or ``str_`` dtype,

depending on input types

See Also

--------

str.lstrip

Examples

--------

>>> import numpy as np

>>> c = np.array(['aAaAaA', ' aA ', 'abBABba'])

>>> c

array(['aAaAaA', ' aA ', 'abBABba'], dtype='<U7')

# The 'a' variable is unstripped from c[1] because of leading whitespace.

>>> np.strings.lstrip(c, 'a')

array(['AaAaA', ' aA ', 'bBABba'], dtype='<U7')

>>> np.strings.lstrip(c, 'A') # leaves c unchanged

array(['aAaAaA', ' aA ', 'abBABba'], dtype='<U7')

>>> (np.strings.lstrip(c, ' ') == np.strings.lstrip(c, '')).all()

np.False_

>>> (np.strings.lstrip(c, ' ') == np.strings.lstrip(c)).all()

np.True_

"""

if chars is None:

return _lstrip_whitespace(a)

return _lstrip_chars(a, chars)

@set_module("numpy.strings")

def rstrip(a, chars=None):

"""

For each element in `a`, return a copy with the trailing characters

removed.

Parameters

----------

a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype

chars : scalar with the same dtype as ``a``, optional

The ``chars`` argument is a string specifying the set of