From 3445712afcd71d2a3d61973de45aa94c38613dd5 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Sat, 7 Jul 2012 14:37:02 +0200 Subject: DOC: merge wiki edits for chararray. Thanks to Tim Cera. --- numpy/core/defchararray.py | 114 +++++++++++++++++++++++++++++---------------- 1 file changed, 73 insertions(+), 41 deletions(-) (limited to 'numpy/core/defchararray.py') diff --git a/numpy/core/defchararray.py b/numpy/core/defchararray.py index b2deb6318..1f4b3bef8 100644 --- a/numpy/core/defchararray.py +++ b/numpy/core/defchararray.py @@ -259,19 +259,22 @@ def str_len(a): def add(x1, x2): """ - Return (x1 + x2), that is string concatenation, element-wise for a - pair of array_likes of str or unicode. + Return element-wise string concatenation for two arrays of str or unicode. + + Arrays `x1` and `x2` must have the same shape. Parameters ---------- x1 : array_like of str or unicode - + Input array. x2 : array_like of str or unicode + Input array. Returns ------- add : ndarray Output array of `string_` or `unicode_`, depending on input types + of the same shape as `x1` and `x2`. """ arr1 = numpy.asarray(x1) @@ -346,6 +349,7 @@ def capitalize(a): Parameters ---------- a : array_like of str or unicode + Input array of strings to capitalize. Returns ------- @@ -365,6 +369,7 @@ def capitalize(a): >>> np.char.capitalize(c) array(['A1b2', '1b2a', 'B2a1', '2a1b'], dtype='|S4') + """ a_arr = numpy.asarray(a) return _vec_string(a_arr, a_arr.dtype, 'capitalize') @@ -960,7 +965,7 @@ else: def lower(a): """ - Return an array with the elements of `a` converted to lowercase. + Return an array with the elements converted to lowercase. Call `str.lower` element-wise. @@ -968,11 +973,12 @@ def lower(a): Parameters ---------- - a : array-like of str or unicode + a : array_like, {str, unicode} + Input array. Returns ------- - out : ndarray, str or unicode + out : ndarray, {str, unicode} Output array of str or unicode, depending on input type See also @@ -987,6 +993,7 @@ def lower(a): >>> np.char.lower(c) array(['a1b c', '1bca', 'bca1'], dtype='|S5') + """ a_arr = numpy.asarray(a) return _vec_string(a_arr, a_arr.dtype, 'lower') @@ -1000,18 +1007,19 @@ def lstrip(a, chars=None): Parameters ---------- - a : array-like of str or unicode + a : array-like, {str, unicode} + Input array. - chars : str or unicode, optional - The `chars` argument is a string specifying the set of - characters to be removed. If omitted or None, the `chars` - argument defaults to removing whitespace. The `chars` argument - is not a prefix; rather, all combinations of its values are - stripped. + chars : {str, unicode}, optional + The `chars` argument is a string specifying the set of + characters to be removed. If omitted or None, the `chars` + argument defaults to removing whitespace. The `chars` argument + is not a prefix; rather, all combinations of its values are + stripped. Returns ------- - out : ndarray, str or unicode + out : ndarray, {str, unicode} Output array of str or unicode, depending on input type See also @@ -1024,9 +1032,14 @@ def lstrip(a, chars=None): >>> c array(['aAaAaA', ' aA ', 'abBABba'], dtype='|S7') - >>> np.char.lstrip(c, 'a') # 'a' unstripped from c[1] because whitespace leading + + The 'a' variable is unstripped from c[1] because whitespace leading. + + >>> np.char.lstrip(c, 'a') array(['AaAaA', ' aA ', 'bBABba'], dtype='|S7') + + >>> np.char.lstrip(c, 'A') # leaves c unchanged array(['aAaAaA', ' aA ', 'abBABba'], dtype='|S7') @@ -1056,12 +1069,14 @@ if sys.version_info >= (2, 5): Parameters ---------- - a : array-like of str or unicode - sep : str or unicode + a : array_like, {str, unicode} + Input array + sep : {str, unicode} + Separator to split each string element in `a`. Returns ------- - out : ndarray + out : ndarray, {str, unicode} Output array of str or unicode, depending on input type. The output array will have an extra dimension with 3 elements per input element. @@ -1069,6 +1084,7 @@ if sys.version_info >= (2, 5): See also -------- str.partition + """ return _to_string_or_unicode_array( _vec_string(a, object_, 'partition', (sep,))) @@ -1229,7 +1245,7 @@ else: if sys.version_info >= (2, 5): def rpartition(a, sep): """ - Partition each element in `a` around `sep`. + Partition (split) each element around the right-most separator. Calls `str.rpartition` element-wise. @@ -1241,8 +1257,10 @@ if sys.version_info >= (2, 5): Parameters ---------- - a : array-like of str or unicode + a : array_like of str or unicode + Input array sep : str or unicode + Right-most separator to split each element in array. Returns ------- @@ -1254,6 +1272,7 @@ if sys.version_info >= (2, 5): See also -------- str.rpartition + """ return _to_string_or_unicode_array( _vec_string(a, object_, 'rpartition', (sep,))) @@ -1478,7 +1497,7 @@ def strip(a, chars=None): def swapcase(a): """ - For each element in `a`, return a copy of the string with + Return element-wise a copy of the string with uppercase characters converted to lowercase and vice versa. Calls `str.swapcase` element-wise. @@ -1487,11 +1506,12 @@ def swapcase(a): Parameters ---------- - a : array-like of str or unicode + a : array_like, {str, unicode} + Input array. Returns ------- - out : ndarray + out : ndarray, {str, unicode} Output array of str or unicode, depending on input type See also @@ -1506,14 +1526,16 @@ def swapcase(a): >>> np.char.swapcase(c) array(['A1b C', '1B cA', 'B cA1', 'Ca1B'], dtype='|S5') + """ a_arr = numpy.asarray(a) return _vec_string(a_arr, a_arr.dtype, 'swapcase') def title(a): """ - For each element in `a`, return a titlecased version of the - string: words start with uppercase characters, all remaining cased + Return element-wise title cased version of string or unicode. + + Title case words start with uppercase characters, all remaining cased characters are lowercase. Calls `str.title` element-wise. @@ -1522,7 +1544,8 @@ def title(a): Parameters ---------- - a : array-like of str or unicode + a : array_like, {str, unicode} + Input array. Returns ------- @@ -1541,6 +1564,7 @@ def title(a): >>> np.char.title(c) array(['A1B C', '1B Ca', 'B Ca1', 'Ca1B'], dtype='|S5') + """ a_arr = numpy.asarray(a) return _vec_string(a_arr, a_arr.dtype, 'title') @@ -1582,7 +1606,7 @@ def translate(a, table, deletechars=None): def upper(a): """ - Return an array with the elements of `a` converted to uppercase. + Return an array with the elements converted to uppercase. Calls `str.upper` element-wise. @@ -1590,11 +1614,12 @@ def upper(a): Parameters ---------- - a : array-like of str or unicode + a : array_like, {str, unicode} + Input array. Returns ------- - out : ndarray + out : ndarray, {str, unicode} Output array of str or unicode, depending on input type See also @@ -1609,30 +1634,33 @@ def upper(a): >>> np.char.upper(c) array(['A1B C', '1BCA', 'BCA1'], dtype='|S5') + """ a_arr = numpy.asarray(a) return _vec_string(a_arr, a_arr.dtype, 'upper') def zfill(a, width): """ - Return the numeric string left-filled with zeros in a string of - length `width`. + Return the numeric string left-filled with zeros Calls `str.zfill` element-wise. Parameters ---------- - a : array-like of str or unicode + a : array_like, {str, unicode} + Input array. width : int + Width of string to left-fill elements in `a`. Returns ------- - out : ndarray + out : ndarray, {str, unicode} Output array of str or unicode, depending on input type See also -------- str.zfill + """ a_arr = numpy.asarray(a) width_arr = numpy.asarray(width) @@ -1642,7 +1670,7 @@ def zfill(a, width): def isnumeric(a): """ - For each element in `a`, return True if there are only numeric + For each element, return True if there are only numeric characters in the element. Calls `unicode.isnumeric` element-wise. @@ -1653,16 +1681,18 @@ def isnumeric(a): Parameters ---------- - a : array-like of unicode + a : array_like, unicode + Input array. Returns ------- - out : ndarray - Array of booleans + out : ndarray, bool + Array of booleans of same shape as `a`. See also -------- unicode.isnumeric + """ if _use_unicode(a) != unicode_: raise TypeError("isnumeric is only available for Unicode strings and arrays") @@ -1670,7 +1700,7 @@ def isnumeric(a): def isdecimal(a): """ - For each element in `a`, return True if there are only decimal + For each element, return True if there are only decimal characters in the element. Calls `unicode.isdecimal` element-wise. @@ -1681,16 +1711,18 @@ def isdecimal(a): Parameters ---------- - a : array-like of unicode + a : array_like, unicode + Input array. Returns ------- - out : ndarray - Array of booleans + out : ndarray, bool + Array of booleans identical in shape to `a`. See also -------- unicode.isdecimal + """ if _use_unicode(a) != unicode_: raise TypeError("isnumeric is only available for Unicode strings and arrays") -- cgit v1.2.1