Class np.strings

Namespace: NumSharp

Assembly: NumSharp.dll

NumPy's numpy.strings module: elementwise comparisons, concatenation, repetition, search, stripping, padding, replacement, slicing, Unicode properties, case conversion, formatting and codecs over fixed-width S / U and variable-width StringDType text. Arguments broadcast; each operation determines its result width and handling of missing values.

[ModuleName("np.strings")]
public static class np.strings

Inheritance: object

np.strings

Inherited Members: object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

A C# string argument of a numpy.strings function is NumPy's Python str — a 0-d U scalar of its length (Scalar(object)), just as the ordinary implicit string → NDArray conversion is. It neither parses numeric text nor constructs a vector of chars. A byte[] stays a numeric uint8 array here; build an S scalar with Scalar(object) for NumPy's bytes. This differs from the text-specific np.@char arguments, which interpret a byte[] as one bytestring.

[ModuleName("np.strings")] files its members under NumPy's numpy.strings in the API inventory (coverage/NumSharp.Tools.ApiInventory), whose guard refuses a public nested static class of np that names no module.

Methods

add(NDArray, NDArray, NDArray, NDArray, DType)

Element-wise string concatenation: NumPy's np.strings.add, which IS the np.add ufunc (probed: np.strings.add is np.add). Two strings of one class concatenate at width width(x1) + width(x2).

public static NDArray add(NDArray x1, NDArray x2, NDArray @out = null, NDArray where = null, DType dtype = null)

Parameters

x1 NDArray: The first operand.
x2 NDArray: The second operand.
out NDArray: An output to write into and return (a narrower or wider text array receives the result truncated / zero-padded, NumPy's output cast), or null.
where NDArray: A bool mask: only elements where it is True are computed, or null.
dtype DType: NumPy's dtype= (the string add promoter ignores it for two strings of one class).

Returns

NDArray: The concatenation, or out.

Exceptions

TypeError: A bytes / str mix ("ufunc 'add' cannot use operands with types …"), a string and a number (NumPy's no-loop text), or a result wider than 2^31 - 1 bytes ("addition result string of length … is too large to store inside array.").
TypeError: out cannot receive the result (the same_kind output cast, e.g. a U result into an S out).
ArgumentException: The operands do not broadcast with out / where.
IncorrectShapeException: The two operands do not broadcast.
UnicodeDecodeError: An S result cast into a U out meets a byte ≥ 0x80.

add(NDArray, string, NDArray, NDArray, DType)

Concatenation of an array and a C# string (NumPy's Python str, a 0-d U scalar).

public static NDArray add(NDArray x1, string x2, NDArray @out = null, NDArray where = null, DType dtype = null)

Parameters

x1 NDArray: The first operand.
x2 string: The string (not null).
out NDArray: An output to write into and return, or null.
where NDArray: A bool mask, or null.
dtype DType: NumPy's dtype=.

Returns

NDArray: The concatenation, or out.

Exceptions

ArgumentNullException: x2 is null.
TypeError: An S or numeric x1 (see add(NDArray, NDArray, NDArray, NDArray, DType)).

add(string, NDArray, NDArray, NDArray, DType)

Concatenation of a C# string (NumPy's Python str) and an array, the string first.

public static NDArray add(string x1, NDArray x2, NDArray @out = null, NDArray where = null, DType dtype = null)

Parameters

x1 string: The string (not null).
x2 NDArray: The second operand.
out NDArray: An output to write into and return, or null.
where NDArray: A bool mask, or null.
dtype DType: NumPy's dtype=.

Returns

NDArray: The concatenation, or out.

Exceptions

ArgumentNullException: x1 is null.
TypeError: An S or numeric x2.

add(string, string)

Concatenation of two C# strings: a 0-d U result (NumPy: np.strings.add('a', 'b') is np.str_('ab')).

public static NDArray add(string x1, string x2)

Parameters

x1 string: The first string (not null).
x2 string: The second string (not null).

Returns

NDArray: The 0-d concatenation.

Exceptions

ArgumentNullException: A string is null.

capitalize(NDArray)

NumPy's np.strings.capitalize: each element's first character in titlecase and the rest lowered (CPython 3.8+'s str.capitalize: 'ǆemal' becomes 'ǅemal'); bytes.capitalize uppercases the first byte and lowers the other ASCII letters.

public static NDArray capitalize(NDArray a)

Parameters

a NDArray: The strings: S, U or StringDType.

Returns

NDArray: A fresh C-ordered array of a's dtype (an S / U result cut to the element width).

Remarks

The first character is the element's first one even when it is not a letter: '1abc' stays '1abc', and a leading NUL stays first.

Exceptions

ArgumentNullException: a is null.
TypeError: a is not text; a StringDType NA whose NA object is not a str.
SystemError: A U element holding a code unit past U+10FFFF.

center(NDArray, NDArray, NDArray)

NumPy's np.strings.center(a, width, fillchar=' '): each element centered in a string of width characters, padded with fillchar (an odd padding puts the extra character on the left when the width is odd, on the right otherwise — CPython's rule). An element longer than the width is unchanged.

public static NDArray center(NDArray a, NDArray width, NDArray fillchar = null)

Parameters

a NDArray: The strings (S, U or StringDType).
width NDArray: The widths: an integer array (any width, not bool) or literal, broadcast.
fillchar NDArray: The fill characters, each exactly one character long; null is NumPy's default ' '. A U fill beside an S operand is cast to S (ASCII only).

Returns

NDArray: A fresh array: for S / U the class of a at the widest result width, laid out like a; for StringDType a StringDType array.

Exceptions

ArgumentNullException: a or width is null.
TypeError: width is not an integer array (unsupported type float64 for operand 'width'); a fill that is not one character (The fill character must be exactly one character long); a non-text operand; no common dtype or no loop for the classes; a uint64 width (NumPy builds a 'U6.0' descriptor: data type 'U6.0' not understood).
IncorrectShapeException: The operands do not broadcast.
ValueError: An empty broadcast (zero-size array to reduction operation maximum which has no identity); a StringDType NA its rule refuses; a chararray a or fillchar beside a StringDType one that NumPy's trivial loop copies into StringDType() (0-d, or 1-d with at most np.getbufsize() elements: Can only create a chararray from string data.).
UnicodeEncodeError: A non-ASCII fill for an S operand.
OverflowException: A StringDType result past sys.maxsize bytes.

count(NDArray, NDArray, NDArray, NDArray)

NumPy's np.strings.count(a, sub, start=0, end=None): the number of NON-OVERLAPPING occurrences of sub in a[start:end], counted greedily from the left (count('aaaa', 'aa') is 2); an empty substring occurs len + 1 times in the range.

public static NDArray count(NDArray a, NDArray sub, NDArray start = null, NDArray end = null)

Parameters

a NDArray: The searched strings.
sub NDArray: The substrings (see find(NDArray, NDArray, NDArray, NDArray)).
start NDArray: The range start (null = 0).
end NDArray: The range end (null = the whole string).

Returns

NDArray: An int64 array of the broadcast shape.

Exceptions

TypeError: No loop for the operand classes; two different StringDType NA objects.
TypeError: A start / end that cannot reach int64 by a same_kind cast.
OverflowException: A start / end literal past int64.
IncorrectShapeException: The operands do not broadcast.
ValueError: A StringDType NA whose NA object is not a string; a chararray operand beside a StringDType one that NumPy's trivial loop copies into StringDType() (0-d, or 1-d with at most np.getbufsize() elements: Can only create a chararray from string data.).

decode(NDArray, object, object)

NumPy's np.strings.decode: CPython's bytes.decode(encoding, errors) per element of an S array, the results as a U array.

public static NDArray decode(NDArray a, object encoding = null, object errors = null)

Parameters

a NDArray: The bytes: an S array (build a 0-d one with Scalar(object) of a byte[]).
encoding object: The codec name, or null for UTF-8 (the codecs of encode(NDArray, object, object)); broadcast against a.
errors object: The error handler, or null for strict: "strict", "ignore", "replace" (one U+FFFD per bad sequence), "backslashreplace" (\xff per byte), "surrogateescape" (each byte 0x80..0xFF as U+DC80..U+DCFF) or "surrogatepass" (an encoded surrogate decoded, UTF-8 / 16 / 32 only); "xmlcharrefreplace" and "namereplace" raise CPython's TypeError at the first error. An unknown name raises LookupError only at the first error. Ignored when encoding is null.

Returns

NDArray: A fresh C-ordered U array over the broadcast shape, as wide as the longest decoding (at least 1); an empty U1 array when the broadcast is empty.

Remarks

An element is its bytes without the trailing NULs (NumPy's np.bytes_), so an empty element decodes to '' before the codec is even looked up — an unknown encoding over empty elements is no error, as in NumPy — and UTF-16 / UTF-32 text whose last unit ends in a zero byte loses that byte (NumPy's truncated data error, reproduced).

np.strings.decode(np.array(new[] { "a\xff"u8.ToArray() }), "utf-8", "replace") is ["a�"] (U2).

Exceptions

ArgumentNullException: a is null.
AttributeError: a is U or StringDType: type object 'str' has no attribute 'decode'.
TypeError: a is not text; an argument that is not a str (decode() argument 'encoding' must be str, not numpy.int64); xmlcharrefreplace / namereplace at an error (don't know how to handle UnicodeDecodeError in error callback).
ValueError: An argument holding a NUL; a ragged argument list.
UnicodeDecodeError: Bytes the codec cannot decode under strict ('utf-8' codec can't decode byte 0xff in position 0: invalid start byte), or a handler that re-raises it.
UnicodeEncodeError: A surrogate in an argument.
UnicodeError: The undefined codec over a non-empty element.
LookupError: An unknown or non-text codec; an unknown handler name at the first error.
IncorrectShapeException: The operands do not broadcast.
NotSupportedException: A Python codec NumSharp does not implement; an object array of lists as an argument.

encode(NDArray, object, object)

NumPy's np.strings.encode: CPython's str.encode(encoding, errors) per element of a U / StringDType array, the results as an S array.

public static NDArray encode(NDArray a, object encoding = null, object errors = null)

Parameters

a NDArray: The text: U or StringDType (a C# string converts to a 0-d U array).
encoding object: The codec name, or null for UTF-8. Any name and alias CPython's codecs.lookup accepts ("utf-8", "UTF8", "latin-1", "cp1252", "utf-16-le", "ascii" …) for the codecs NumSharp implements: UTF-8, utf-8-sig, UTF-16 and UTF-32 (with a BOM, little- or big-endian), Latin-1, ASCII, the single-byte code pages and undefined. Converted as NumPy's np.asarray converts it and broadcast against a: an array gives one encoding per element; an element that is not a str (a byte[], a number, null in an object list) is CPython's TypeError.
errors object: The error handler, or null for strict: "strict", "ignore", "replace" (?), "backslashreplace" (\xe9, €, \U0001f600), "xmlcharrefreplace" (é), "namereplace" (\N{EURO SIGN}, CPython 3.12's Unicode 15.0 names), "surrogateescape" (U+DC80..U+DCFF back to their bytes) or "surrogatepass" (lone surrogates encoded, UTF-8 / 16 / 32 only). An unknown name raises LookupError only at the first character the codec cannot encode. Ignored when encoding is null (NumPy's _clean_args). Broadcast like encoding.

Returns

NDArray: A fresh C-ordered S array over the broadcast shape, as wide as the longest encoding (at least 1; a trailing NUL byte counts: encode(["a"], "utf-16-le") is S2 holding b"a"); an empty S1 array when the broadcast is empty.

Remarks

An element is the text without its trailing NULs (U, NumPy's np.str_) or the whole cell (StringDType). The first element (C order) that raises ends the call, as in NumPy; an argument is checked at every element it reaches, so an invalid encoding raises at the first element.

np.strings.encode(np.array(new[] { "a€", "b" }), "ascii", "xmlcharrefreplace") is [b"a€", b"b"] (S8); "utf-16" writes a byte-order mark before every element.

Exceptions

ArgumentNullException: a is null.
AttributeError: a is S: type object 'bytes' has no attribute 'encode'.
TypeError: a is not text (string operation on non-string array); a StringDType NA object that is not a str (descriptor 'encode' for 'str' objects doesn't apply to a 'NoneType' object); an argument that is not a str (encode() argument 'encoding' must be str, not numpy.bytes_).
ValueError: An argument holding a NUL (embedded null character); a ragged argument list.
UnicodeEncodeError: A character the codec cannot encode under strict ('ascii' codec can't encode character '\xe9' in position 1: ordinal not in range(128); a run of them reads characters in position 1-3; a code page's errors name 'charmap'), a handler that re-raises it, or a surrogate in an argument.
UnicodeError: The undefined codec (undefined encoding).
LookupError: unknown encoding: nope; 'base64' is not a text encoding; use codecs.encode() to handle arbitrary codecs; unknown error handler name 'x' at the first error.
SystemError: A U element of one unit past U+10FFFF.
IncorrectShapeException: The operands do not broadcast (NumPy's shape mismatch text).
NotSupportedException: A Python codec NumSharp does not implement (the multi-byte CJK codecs, utf-7, the escape codecs, idna, mbcs …); an object array of lists as an argument.

endswith(NDArray, NDArray, NDArray, NDArray)

NumPy's np.strings.endswith(a, suffix, start=0, end=None): whether each element's a[start:end] ends with suffix.

public static NDArray endswith(NDArray a, NDArray suffix, NDArray start = null, NDArray end = null)

Parameters

a NDArray: The tested strings.
suffix NDArray: The suffixes (see find(NDArray, NDArray, NDArray, NDArray) for the classes).
start NDArray: The range start (null = 0).
end NDArray: The range end (null = the whole string).

Returns

NDArray: A bool array of the broadcast shape.

Exceptions

TypeError: No loop for the operand classes; two different StringDType NA objects.
TypeError: A start / end that cannot reach int64 by a same_kind cast.
OverflowException: A start / end literal past int64.
IncorrectShapeException: The operands do not broadcast.
ValueError: A StringDType NA whose NA object is neither a string nor NaN-like; a chararray operand beside a StringDType one that NumPy's trivial loop copies into StringDType() (0-d, or 1-d with at most np.getbufsize() elements: Can only create a chararray from string data.).

equal(NDArray, NDArray, NDArray, NDArray, DType)

NumPy's np.strings.equal, which IS the np.equal ufunc (np.strings.equal is np.equal).

public static NDArray equal(NDArray x1, NDArray x2, NDArray @out = null, NDArray where = null, DType dtype = null)

Parameters

x1 NDArray: The first operand.
x2 NDArray: The second operand.
out NDArray: An output to write into and return, or null.
where NDArray: A bool mask, or null.
dtype DType: NumPy's dtype= (bool loops only).

Returns

NDArray: The bool result, or out.

Exceptions

TypeError: No comparison loop for the operands (NumPy's no-loop text).
IncorrectShapeException: The operands do not broadcast.

expandtabs(NDArray, NDArray)

NumPy's np.strings.expandtabs(a, tabsize=8): each tab replaced by spaces up to the next multiple of tabsize columns (the column restarts after '\n' and '\r'; a tab size of 0 or less removes the tabs).

public static NDArray expandtabs(NDArray a, NDArray tabsize = null)

Parameters

a NDArray: The strings (S, U or StringDType).
tabsize NDArray: The tab sizes (any integer dtype), broadcast; null is NumPy's default 8.

Returns

NDArray: A fresh array (for S / U at the widest result width, laid out like a).

Exceptions

ArgumentNullException: a is null.
TypeError: A non-text operand (NumPy's no-loop text).
TypeError: A tab size that cannot reach int64 by a same_kind cast (a float).
IncorrectShapeException: The operands do not broadcast.
OverflowException: An expanded string longer than 2^31 - 1 (new string is too long).
ValueError: An empty broadcast; a StringDType NA whose NA object is not a string.

find(NDArray, NDArray, NDArray, NDArray)

NumPy's np.strings.find(a, sub, start=0, end=None): for each element, the lowest index where sub occurs inside a[start:end], or -1. Indices are characters (code points for StringDType); trailing NULs of either string never count.

public static NDArray find(NDArray a, NDArray sub, NDArray start = null, NDArray end = null)

Parameters

a NDArray: The searched strings (S, U or StringDType).
sub NDArray: The substrings: the same class as a (a U one with a StringDType a, or the reverse, is cast to StringDType).
start NDArray: The range start, slice notation (negative counts from the end), any integer dtype; null is NumPy's default 0.
end NDArray: The range end, slice notation; null is NumPy's None (the whole string).

Returns

NDArray: An int64 array of the broadcast shape (0-d for scalar operands).

Exceptions

TypeError: No loop for the operand classes (an S array with a str substring, a number, …: NumPy's no-loop text); two StringDType operands with different NA objects.
TypeError: start / end cannot reach int64 by a same_kind cast (a float: Cannot cast ufunc 'find' input 2 from dtype('float64') …).
OverflowException: A start / end literal past int64 (Python int too large to convert to C long).
IncorrectShapeException: The four operands do not broadcast.
ValueError: A StringDType NA whose NA object is not a string; a chararray operand beside a StringDType one that NumPy's trivial loop copies into StringDType() (0-d, or 1-d with at most np.getbufsize() elements: Can only create a chararray from string data.).

greater(NDArray, NDArray, NDArray, NDArray, DType)

NumPy's np.strings.greater, which IS the np.greater ufunc.

public static NDArray greater(NDArray x1, NDArray x2, NDArray @out = null, NDArray where = null, DType dtype = null)

Parameters

x1 NDArray: The first operand.
x2 NDArray: The second operand.
out NDArray: An output to write into and return, or null.
where NDArray: A bool mask, or null.
dtype DType: NumPy's dtype= (bool loops only).

Returns

NDArray: The bool result, or out.

Exceptions

TypeError: No comparison loop for the operands.
IncorrectShapeException: The operands do not broadcast.

greater_equal(NDArray, NDArray, NDArray, NDArray, DType)

NumPy's np.strings.greater_equal, which IS the np.greater_equal ufunc.

public static NDArray greater_equal(NDArray x1, NDArray x2, NDArray @out = null, NDArray where = null, DType dtype = null)

Parameters

x1 NDArray: The first operand.
x2 NDArray: The second operand.
out NDArray: An output to write into and return, or null.
where NDArray: A bool mask, or null.
dtype DType: NumPy's dtype= (bool loops only).

Returns

NDArray: The bool result, or out.

Exceptions

TypeError: No comparison loop for the operands.
IncorrectShapeException: The operands do not broadcast.

index(NDArray, NDArray, NDArray, NDArray)

NumPy's np.strings.index(a, sub, start=0, end=None): find(NDArray, NDArray, NDArray, NDArray), but an element with no match raises ValueError: substring not found.

public static NDArray index(NDArray a, NDArray sub, NDArray start = null, NDArray end = null)

Parameters

a NDArray: The searched strings.
sub NDArray: The substrings (see find(NDArray, NDArray, NDArray, NDArray)).
start NDArray: The range start (null = 0).
end NDArray: The range end (null = the whole string).

Returns

NDArray: An int64 array of the broadcast shape.

Exceptions

TypeError: No loop for the operand classes; two different StringDType NA objects.
TypeError: A start / end that cannot reach int64 by a same_kind cast.
OverflowException: A start / end literal past int64.
IncorrectShapeException: The operands do not broadcast.
ValueError: An element without a match (substring not found); a StringDType NA whose NA object is not a string; a chararray operand beside a StringDType one that NumPy's trivial loop copies into StringDType() (0-d, or 1-d with at most np.getbufsize() elements: Can only create a chararray from string data.).

isalnum(NDArray, NDArray, NDArray, DType)

NumPy's np.strings.isalnum ufunc: True for each element whose text has at least one character and only alphanumeric characters (CPython's str.isalnum: alphabetic, decimal, digit or numeric). The text is the element's characters without its trailing NULs (an embedded NUL is a character, with no property).

public static NDArray isalnum(NDArray x, NDArray @out = null, NDArray where = null, DType dtype = null)

Parameters

x NDArray: The strings: S (NumPy's ASCII rules: a byte at or past 0x80 has no property; whitespace is space and \t–\r only), U or StringDType.
out NDArray: An output to write into and return (any dtype bool casts to under same_kind: a number receives 0 / 1, a text output 'True' / 'False' cut to its width), or null.
where NDArray: A bool mask: only elements where it is True are computed, the others keep out's values (uninitialized in a fresh result), or null.
dtype DType: NumPy's dtype=: only bool has a loop.

Returns

NDArray: The bool results (0-d for a 0-d operand), or out.

Remarks

np.strings.isalnum(np.array(new[] { "a1", "½", "a b" })) is [True, True, False]. A numpy.char.chararray operand gives a plain bool result (chararray.array_wrap keeps only text results); a chararray out comes back as a new view of it.

Exceptions

ArgumentNullException: x is null.
TypeError: x is not text, or dtype is not bool (NumPy's no-loop text: ufunc 'isalnum' did not contain a loop with signature matching types <class 'numpy.dtypes.Int64DType'> -> None).
TypeError: out cannot receive bool (the same_kind output cast).
ArgumentException: A non-bool where; operands that do not broadcast with out / where.
ValueError: A read-only out; a selected StringDType NA whose descriptor's NA object is neither NaN-like nor a string (Cannot use the isalnum function with a null that is not a nan-like value; a NaN-like NA is False, a string NA reads as its string).
IncorrectShapeException: The operands do not broadcast.

isalpha(NDArray, NDArray, NDArray, DType)

NumPy's np.strings.isalpha ufunc: True for each element whose text has at least one character and only alphabetic characters (CPython's str.isalpha: the Unicode letter categories Lu, Ll, Lt, Lm, Lo). The text is the element's characters without its trailing NULs (an embedded NUL is a character, with no property).

public static NDArray isalpha(NDArray x, NDArray @out = null, NDArray where = null, DType dtype = null)

Parameters

x NDArray: The strings: S (NumPy's ASCII rules: a byte at or past 0x80 has no property; whitespace is space and \t–\r only), U or StringDType.
out NDArray: An output to write into and return (any dtype bool casts to under same_kind: a number receives 0 / 1, a text output 'True' / 'False' cut to its width), or null.
where NDArray: A bool mask: only elements where it is True are computed, the others keep out's values (uninitialized in a fresh result), or null.
dtype DType: NumPy's dtype=: only bool has a loop.

Returns

NDArray: The bool results (0-d for a 0-d operand), or out.

Remarks

np.strings.isalpha(np.array(new[] { "abc", "a1", "" })) is [True, False, False]. A numpy.char.chararray operand gives a plain bool result (chararray.array_wrap keeps only text results); a chararray out comes back as a new view of it.

Exceptions

ArgumentNullException: x is null.
TypeError: x is not text, or dtype is not bool (NumPy's no-loop text: ufunc 'isalpha' did not contain a loop with signature matching types <class 'numpy.dtypes.Int64DType'> -> None).
TypeError: out cannot receive bool (the same_kind output cast).
ArgumentException: A non-bool where; operands that do not broadcast with out / where.
ValueError: A read-only out; a selected StringDType NA whose descriptor's NA object is neither NaN-like nor a string (Cannot use the isalpha function with a null that is not a nan-like value; a NaN-like NA is False, a string NA reads as its string).
IncorrectShapeException: The operands do not broadcast.

isdecimal(NDArray, NDArray, NDArray, DType)

NumPy's np.strings.isdecimal ufunc: True for each element whose text has at least one character and only decimal characters (CPython's str.isdecimal: '٣' is one, '²' is not). The text is the element's characters without its trailing NULs (an embedded NUL is a character, with no property).

public static NDArray isdecimal(NDArray x, NDArray @out = null, NDArray where = null, DType dtype = null)

Parameters

x NDArray: The strings: U or StringDType (NumPy has no S loop).
out NDArray: An output to write into and return (any dtype bool casts to under same_kind: a number receives 0 / 1, a text output 'True' / 'False' cut to its width), or null.
where NDArray: A bool mask: only elements where it is True are computed, the others keep out's values (uninitialized in a fresh result), or null.
dtype DType: NumPy's dtype=: only bool has a loop.

Returns

NDArray: The bool results (0-d for a 0-d operand), or out.

Remarks

np.strings.isdecimal(np.array(new[] { "123", "²", "٣" })) is [True, False, True]. A numpy.char.chararray operand gives a plain bool result (chararray.array_wrap keeps only text results); a chararray out comes back as a new view of it.

Exceptions

ArgumentNullException: x is null.
TypeError: x is not U / StringDType (an S operand included: ufunc 'isdecimal' did not contain a loop with signature matching types <class 'numpy.dtypes.BytesDType'> -> None), or dtype is not bool.
TypeError: out cannot receive bool (the same_kind output cast).
ArgumentException: A non-bool where; operands that do not broadcast with out / where.
ValueError: A read-only out; a selected StringDType NA whose descriptor's NA object is neither NaN-like nor a string (Cannot use the isdecimal function with a null that is not a nan-like value; a NaN-like NA is False, a string NA reads as its string).
IncorrectShapeException: The operands do not broadcast.

isdigit(NDArray, NDArray, NDArray, DType)

NumPy's np.strings.isdigit ufunc: True for each element whose text has at least one character and only digits (CPython's str.isdigit: the decimal digits and the other digits, such as '²'; not '½'). The text is the element's characters without its trailing NULs (an embedded NUL is a character, with no property).

public static NDArray isdigit(NDArray x, NDArray @out = null, NDArray where = null, DType dtype = null)

Parameters

x NDArray: The strings: S (NumPy's ASCII rules: a byte at or past 0x80 has no property; whitespace is space and \t–\r only), U or StringDType.
out NDArray: An output to write into and return (any dtype bool casts to under same_kind: a number receives 0 / 1, a text output 'True' / 'False' cut to its width), or null.
where NDArray: A bool mask: only elements where it is True are computed, the others keep out's values (uninitialized in a fresh result), or null.
dtype DType: NumPy's dtype=: only bool has a loop.

Returns

NDArray: The bool results (0-d for a 0-d operand), or out.

Remarks

np.strings.isdigit(np.array(new[] { "123", "²", "½" })) is [True, True, False]. A numpy.char.chararray operand gives a plain bool result (chararray.array_wrap keeps only text results); a chararray out comes back as a new view of it.

Exceptions

ArgumentNullException: x is null.
TypeError: x is not text, or dtype is not bool (NumPy's no-loop text: ufunc 'isdigit' did not contain a loop with signature matching types <class 'numpy.dtypes.Int64DType'> -> None).
TypeError: out cannot receive bool (the same_kind output cast).
ArgumentException: A non-bool where; operands that do not broadcast with out / where.
ValueError: A read-only out; a selected StringDType NA whose descriptor's NA object is neither NaN-like nor a string (Cannot use the isdigit function with a null that is not a nan-like value; a NaN-like NA is False, a string NA reads as its string).
IncorrectShapeException: The operands do not broadcast.

islower(NDArray, NDArray, NDArray, DType)

NumPy's np.strings.islower ufunc: True for each element whose text has at least one cased character and every cased character lowercase (an uppercase or titlecase character makes it False). The text is the element's characters without its trailing NULs (an embedded NUL is a character, with no property).

public static NDArray islower(NDArray x, NDArray @out = null, NDArray where = null, DType dtype = null)

Parameters

x NDArray: The strings: S (NumPy's ASCII rules: a byte at or past 0x80 has no property; whitespace is space and \t–\r only), U or StringDType.
out NDArray: An output to write into and return (any dtype bool casts to under same_kind: a number receives 0 / 1, a text output 'True' / 'False' cut to its width), or null.
where NDArray: A bool mask: only elements where it is True are computed, the others keep out's values (uninitialized in a fresh result), or null.
dtype DType: NumPy's dtype=: only bool has a loop.

Returns

NDArray: The bool results (0-d for a 0-d operand), or out.

Remarks

np.strings.islower(np.array(new[] { "abc", "aBc", "1a" })) is [True, False, True]. A numpy.char.chararray operand gives a plain bool result (chararray.array_wrap keeps only text results); a chararray out comes back as a new view of it.

Exceptions

ArgumentNullException: x is null.
TypeError: x is not text, or dtype is not bool (NumPy's no-loop text: ufunc 'islower' did not contain a loop with signature matching types <class 'numpy.dtypes.Int64DType'> -> None).
TypeError: out cannot receive bool (the same_kind output cast).
ArgumentException: A non-bool where; operands that do not broadcast with out / where.
ValueError: A read-only out; a selected StringDType NA whose descriptor's NA object is neither NaN-like nor a string (Cannot use the islower function with a null that is not a nan-like value; a NaN-like NA is False, a string NA reads as its string).
IncorrectShapeException: The operands do not broadcast.

isnumeric(NDArray, NDArray, NDArray, DType)

NumPy's np.strings.isnumeric ufunc: True for each element whose text has at least one character and only numeric characters (CPython's str.isnumeric: digits, fractions such as '½', Roman numerals 'Ⅻ', CJK numerals '万'). The text is the element's characters without its trailing NULs (an embedded NUL is a character, with no property).

public static NDArray isnumeric(NDArray x, NDArray @out = null, NDArray where = null, DType dtype = null)

Parameters

x NDArray: The strings: U or StringDType (NumPy has no S loop).
out NDArray: An output to write into and return (any dtype bool casts to under same_kind: a number receives 0 / 1, a text output 'True' / 'False' cut to its width), or null.
where NDArray: A bool mask: only elements where it is True are computed, the others keep out's values (uninitialized in a fresh result), or null.
dtype DType: NumPy's dtype=: only bool has a loop.

Returns

NDArray: The bool results (0-d for a 0-d operand), or out.

Remarks

np.strings.isnumeric(np.array(new[] { "123", "½", "a" })) is [True, True, False]. A numpy.char.chararray operand gives a plain bool result (chararray.array_wrap keeps only text results); a chararray out comes back as a new view of it.

Exceptions

ArgumentNullException: x is null.
TypeError: x is not U / StringDType (an S operand included: ufunc 'isnumeric' did not contain a loop with signature matching types <class 'numpy.dtypes.BytesDType'> -> None), or dtype is not bool.
TypeError: out cannot receive bool (the same_kind output cast).
ArgumentException: A non-bool where; operands that do not broadcast with out / where.
ValueError: A read-only out; a selected StringDType NA whose descriptor's NA object is neither NaN-like nor a string (Cannot use the isnumeric function with a null that is not a nan-like value; a NaN-like NA is False, a string NA reads as its string).
IncorrectShapeException: The operands do not broadcast.

isspace(NDArray, NDArray, NDArray, DType)

NumPy's np.strings.isspace ufunc: True for each element whose text has at least one character and only whitespace (CPython's str.isspace: space, \t–\r, U+001C–U+001F, NEL, the no-break, Ogham, ideographic and U+2000–U+200A spaces, the line and paragraph separators). The text is the element's characters without its trailing NULs (an embedded NUL is a character, with no property).

public static NDArray isspace(NDArray x, NDArray @out = null, NDArray where = null, DType dtype = null)

Parameters

x NDArray: The strings: S (NumPy's ASCII rules: a byte at or past 0x80 has no property; whitespace is space and \t–\r only), U or StringDType.
out NDArray: An output to write into and return (any dtype bool casts to under same_kind: a number receives 0 / 1, a text output 'True' / 'False' cut to its width), or null.
where NDArray: A bool mask: only elements where it is True are computed, the others keep out's values (uninitialized in a fresh result), or null.
dtype DType: NumPy's dtype=: only bool has a loop.

Returns

NDArray: The bool results (0-d for a 0-d operand), or out.

Remarks

np.strings.isspace(np.array(new[] { " \t", "\x1c", "a " })) is [True, True, False]. A numpy.char.chararray operand gives a plain bool result (chararray.array_wrap keeps only text results); a chararray out comes back as a new view of it.

Exceptions

ArgumentNullException: x is null.
TypeError: x is not text, or dtype is not bool (NumPy's no-loop text: ufunc 'isspace' did not contain a loop with signature matching types <class 'numpy.dtypes.Int64DType'> -> None).
TypeError: out cannot receive bool (the same_kind output cast).
ArgumentException: A non-bool where; operands that do not broadcast with out / where.
ValueError: A read-only out; a selected StringDType NA whose descriptor's NA object is neither NaN-like nor a string (Cannot use the isspace function with a null that is not a nan-like value; a NaN-like NA is False, a string NA reads as its string).
IncorrectShapeException: The operands do not broadcast.

istitle(NDArray, NDArray, NDArray, DType)

NumPy's np.strings.istitle ufunc: True for each element whose text is titlecased: an uppercase or titlecase character ('ǅ') never follows a cased character, a lowercase one always does, and at least one character is cased. The text is the element's characters without its trailing NULs (an embedded NUL is a character, with no property).

public static NDArray istitle(NDArray x, NDArray @out = null, NDArray where = null, DType dtype = null)

Parameters

x NDArray: The strings: S (NumPy's ASCII rules: a byte at or past 0x80 has no property; whitespace is space and \t–\r only), U or StringDType.
out NDArray: An output to write into and return (any dtype bool casts to under same_kind: a number receives 0 / 1, a text output 'True' / 'False' cut to its width), or null.
where NDArray: A bool mask: only elements where it is True are computed, the others keep out's values (uninitialized in a fresh result), or null.
dtype DType: NumPy's dtype=: only bool has a loop.

Returns

NDArray: The bool results (0-d for a 0-d operand), or out.

Remarks

np.strings.istitle(np.array(new[] { "Hello World", "Hello world", "1A" })) is [True, False, True]. A numpy.char.chararray operand gives a plain bool result (chararray.array_wrap keeps only text results); a chararray out comes back as a new view of it.

Exceptions

ArgumentNullException: x is null.
TypeError: x is not text, or dtype is not bool (NumPy's no-loop text: ufunc 'istitle' did not contain a loop with signature matching types <class 'numpy.dtypes.Int64DType'> -> None).
TypeError: out cannot receive bool (the same_kind output cast).
ArgumentException: A non-bool where; operands that do not broadcast with out / where.
ValueError: A read-only out; a selected StringDType NA whose descriptor's NA object is neither NaN-like nor a string (Cannot use the istitle function with a null that is not a nan-like value; a NaN-like NA is False, a string NA reads as its string).
IncorrectShapeException: The operands do not broadcast.

isupper(NDArray, NDArray, NDArray, DType)

NumPy's np.strings.isupper ufunc: True for each element whose text has at least one cased character and every cased character uppercase (a lowercase or titlecase character makes it False). The text is the element's characters without its trailing NULs (an embedded NUL is a character, with no property).

public static NDArray isupper(NDArray x, NDArray @out = null, NDArray where = null, DType dtype = null)

Parameters

x NDArray: The strings: S (NumPy's ASCII rules: a byte at or past 0x80 has no property; whitespace is space and \t–\r only), U or StringDType.
out NDArray: An output to write into and return (any dtype bool casts to under same_kind: a number receives 0 / 1, a text output 'True' / 'False' cut to its width), or null.
where NDArray: A bool mask: only elements where it is True are computed, the others keep out's values (uninitialized in a fresh result), or null.
dtype DType: NumPy's dtype=: only bool has a loop.

Returns

NDArray: The bool results (0-d for a 0-d operand), or out.

Remarks

np.strings.isupper(np.array(new[] { "ABC", "aBc", "1A" })) is [True, False, True]. A numpy.char.chararray operand gives a plain bool result (chararray.array_wrap keeps only text results); a chararray out comes back as a new view of it.

Exceptions

ArgumentNullException: x is null.
TypeError: x is not text, or dtype is not bool (NumPy's no-loop text: ufunc 'isupper' did not contain a loop with signature matching types <class 'numpy.dtypes.Int64DType'> -> None).
TypeError: out cannot receive bool (the same_kind output cast).
ArgumentException: A non-bool where; operands that do not broadcast with out / where.
ValueError: A read-only out; a selected StringDType NA whose descriptor's NA object is neither NaN-like nor a string (Cannot use the isupper function with a null that is not a nan-like value; a NaN-like NA is False, a string NA reads as its string).
IncorrectShapeException: The operands do not broadcast.

less(NDArray, NDArray, NDArray, NDArray, DType)

NumPy's np.strings.less, which IS the np.less ufunc.

public static NDArray less(NDArray x1, NDArray x2, NDArray @out = null, NDArray where = null, DType dtype = null)

Parameters

x1 NDArray: The first operand.
x2 NDArray: The second operand.
out NDArray: An output to write into and return, or null.
where NDArray: A bool mask, or null.
dtype DType: NumPy's dtype= (bool loops only).

Returns

NDArray: The bool result, or out.

Exceptions

TypeError: No comparison loop for the operands.
IncorrectShapeException: The operands do not broadcast.

less_equal(NDArray, NDArray, NDArray, NDArray, DType)

NumPy's np.strings.less_equal, which IS the np.less_equal ufunc.

public static NDArray less_equal(NDArray x1, NDArray x2, NDArray @out = null, NDArray where = null, DType dtype = null)

Parameters

x1 NDArray: The first operand.
x2 NDArray: The second operand.
out NDArray: An output to write into and return, or null.
where NDArray: A bool mask, or null.
dtype DType: NumPy's dtype= (bool loops only).

Returns

NDArray: The bool result, or out.

Exceptions

TypeError: No comparison loop for the operands.
IncorrectShapeException: The operands do not broadcast.

ljust(NDArray, NDArray, NDArray)

NumPy's np.strings.ljust(a, width, fillchar=' '): each element left-justified in a string of width characters, padded on the right with fillchar.

public static NDArray ljust(NDArray a, NDArray width, NDArray fillchar = null)

Parameters

a NDArray: The strings.
width NDArray: The integer widths, broadcast.
fillchar NDArray: The one-character fills (null = ' ').

Returns

NDArray: A fresh array (see center(NDArray, NDArray, NDArray)).

Exceptions

ArgumentNullException: a or width is null.
TypeError: See center(NDArray, NDArray, NDArray).
IncorrectShapeException: The operands do not broadcast.
ValueError: An empty broadcast; a StringDType NA its rule refuses; the trivial-loop copy of a chararray operand (see center(NDArray, NDArray, NDArray)).
UnicodeEncodeError: A non-ASCII fill for an S operand.
OverflowException: A StringDType result past sys.maxsize bytes.

lower(NDArray)

NumPy's np.strings.lower: each element's text lowercased — CPython's str.lower (the full mappings, 'İ' becomes 'i̇', and the final sigma: 'ΑΣ' becomes 'ας') for U and StringDType, bytes.lower (ASCII letters only) for S.

public static NDArray lower(NDArray a)

Parameters

a NDArray: The strings: S, U or StringDType.

Returns

NDArray: A fresh C-ordered array of a's dtype (an S / U result cut to the element width; a StringDType result with a's NA object and coercion).

Remarks

U+03A3 lowers to the final sigma U+03C2 when a cased character precedes it (case-ignorable characters skipped) and none follows, else to U+03C3, as CPython's lower_ucs4 decides.

Exceptions

ArgumentNullException: a is null.
TypeError: a is not text; a StringDType NA whose NA object is not a str (descriptor 'lower' for 'str' objects doesn't apply to a 'NoneType' object).
SystemError: A U element holding a code unit past U+10FFFF.

lstrip(NDArray, NDArray)

NumPy's np.strings.lstrip(a, chars=None): each element without its LEADING characters found in chars (whitespace for null).

public static NDArray lstrip(NDArray a, NDArray chars = null)

Parameters

a NDArray: The strings.
chars NDArray: The characters to remove (see strip(NDArray, NDArray)), or null for whitespace.

Returns

NDArray: A fresh array of a's dtype.

Exceptions

ArgumentNullException: a is null.
TypeError: No loop for the operand classes; two different StringDType NA objects.
IncorrectShapeException: The operands do not broadcast.
ValueError: A StringDType NA its rule refuses; a chararray operand beside a StringDType one that NumPy's trivial loop copies into StringDType() (0-d, or 1-d with at most np.getbufsize() elements: Can only create a chararray from string data.).

mod(NDArray, object)

NumPy's np.strings.mod: a % values element-wise — CPython's % formatting of each element of a with the broadcast element of values (bytes.mod for S, str.mod for U and StringDType).

public static NDArray mod(NDArray a, object values)

Parameters

a NDArray: The format strings: S, U or StringDType (a C# string converts to a 0-d U array).
values object: The values, converted as NumPy's np.asarray converts them and broadcast against a, ONE value per element: an NDArray as it is (each element reaches % as its NumPy scalar — %r of an int64 element is np.int64(5)); a C# number as a Python number (an integer is int64, a float / double float64); a string a str; a byte[] bytes; a bool a bool; a C# array, list or tuple of values an array of them — a tuple is a SEQUENCE, as NumPy's np.asarray reads one, never one tuple of arguments per element (that takes an object array of tuples, which no C# value spells); null Python's None; an IDictionary a dict, which feeds %(key)s specs; a list holding a null, a dict or a Python int past uint64 NumPy's object array, whose elements are those objects.

Returns

NDArray: A fresh C-ordered array over the broadcast shape: U / S (by a's kind) as wide as the longest result, at least 1; a default StringDType array (no NA object, whatever a's descriptor holds) for a StringDType operand; an empty array of a's own dtype when the broadcast is empty.

Remarks

The format element is the text without its trailing NULs for S / U (NumPy's scalar), the whole text for StringDType. An error ends the call at the first element (C order) that raises, as in NumPy; CPython parses as it formats, so '%s %y' over one value is the argument-count error and '%y %s' the unsupported character.

np.strings.mod(np.array(new[] { "%d bytes", "%.2f%%" }), np.array(new[] { 8.0, 99.5 })) is ["8 bytes", "99.50%"] (U7). Over S, %s writes a NumPy scalar's raw bytes (the buffer protocol): b"%s" of an int64 5 is b"\x05\x00\x00\x00\x00\x00\x00\x00", read back as b"\x05" in an S8 result.

Exceptions

ArgumentNullException: a is null.
TypeError: a is not text (string operation on non-string array); the value count does not fit the format (not enough arguments for format string, not all arguments converted during string formatting — a NumPy numeric scalar, a bytes value, a list or a dict is a mapping and never raises the second); a conversion the value's type refuses (%x format: an integer is required, not numpy.float64, %c requires int or char, %b requires a bytes-like object, or an object that implements bytes, not 'str', float argument required, not str); %(key)s without a mapping (format requires a mapping); a width that is not a Python int ( wants int); a StringDType NA that is not a str (descriptor 'mod' requires a 'str' object but received a 'NoneType'); a StringDType result holding a surrogate (Invalid unicode code point found).
ValueError: A malformed format (incomplete format, incomplete format key, unsupported format character 'y' (0x79) at index 1, width too big, precision too big); a NaN under an integer conversion (cannot convert float NaN to integer); a ragged values list.
OverflowException: An infinity under an integer conversion; a %c argument out of range (%c arg not in range(0x110000), %c arg not in range(256)); an int too large for a float; precision too large; an S format's unsupported conversion byte past 0x7F (character argument not in range(0x110000)).
IndexError: A %(key)s lookup on a NumPy scalar (invalid index to scalar variable.).
KeyError: A %(key)s missing from a dict (the text is the key's repr).
SystemError: A U element of one unit past U+10FFFF (CPython's invalid maximum character passed to PyUnicode_New).
IncorrectShapeException: The operands do not broadcast (shape mismatch: objects cannot be broadcast to a single shape. Mismatch is between arg 0 with shape (2,) and arg 1 with shape (3,).).
NotSupportedException: A value with no NumSharp form (an object array of lists).

multiply(NDArray, NDArray)

NumPy's np.strings.multiply(a, i): every string repeated i times (a count below 1 gives an empty string), the result sized to the longest repetition — NumPy's two passes, statement for statement: the length of every string, an overflow check, the output width max(len(a) * max(i, 0)), then the multiply loop into an array laid out like a (np.empty_like(a, shape=…)).

public static NDArray multiply(NDArray a, NDArray i)

Parameters

a NDArray: The strings (S or U).
i NDArray: The repeat counts: an integer array (any width, not bool), broadcast against a.

Returns

NDArray: A fresh text array of a's class (0-d for a 0-d operand pair). A numpy.char.chararray operand gives a chararray VIEW of a text result (NumPy's array_wrap: OWNDATA False); a result of another dtype stays plain.

Remarks

A NEP 55 StringDType a takes NumPy's a * i branch after the count check: multiply(NDArray, NDArray, NDArray, NDArray, DType)'s StringDType loop, whose result keeps a's descriptor and whose NA rules and Overflow encountered in string multiply are its own (see that member's exceptions).

Exceptions

ArgumentNullException: An operand is null.
TypeError: i is not an integer array ("unsupported type float64 for operand 'i'", checked first); a is not text (str_len's no-loop text); or the output width is not a valid descriptor (NumPy builds it from a string: a uint64 count makes the sizes float64, so 'U6.0' is "data type 'U6.0' not understood", as in NumPy 2.4.2).
OverflowException: A string's len * i exceeds sys.maxsize ("Overflow encountered in string multiply").
ValueError: The broadcast result is empty ("zero-size array to reduction operation maximum which has no identity": NumPy takes the max of the sizes).
IncorrectShapeException: a and i do not broadcast.

multiply(string, NDArray)

NumPy's np.strings.multiply of a C# string (NumPy's Python str): a 0-d text operand.

public static NDArray multiply(string a, NDArray i)

Parameters

a string: The string (not null).
i NDArray: The repeat counts (an integer array).

Returns

NDArray: The repetitions (0-d for a scalar count).

Exceptions

ArgumentNullException: An operand is null.
TypeError: i is not an integer array.
OverflowException: A repetition exceeds sys.maxsize characters.

not_equal(NDArray, NDArray, NDArray, NDArray, DType)

NumPy's np.strings.not_equal, which IS the np.not_equal ufunc.

public static NDArray not_equal(NDArray x1, NDArray x2, NDArray @out = null, NDArray where = null, DType dtype = null)

Parameters

x1 NDArray: The first operand.
x2 NDArray: The second operand.
out NDArray: An output to write into and return, or null.
where NDArray: A bool mask, or null.
dtype DType: NumPy's dtype= (bool loops only).

Returns

NDArray: The bool result, or out.

Exceptions

TypeError: No comparison loop for the operands.
IncorrectShapeException: The operands do not broadcast.

partition(NDArray, NDArray)

NumPy's np.strings.partition(a, sep): each element split around the FIRST occurrence of sep into (before, separator, after); without a match, (the element, empty, empty).

public static (NDArray Before, NDArray Separator, NDArray After) partition(NDArray a, NDArray sep)

Parameters

a NDArray: The strings (S, U or StringDType).
sep NDArray: The separators: cast to a's dtype for S / U; for StringDType it must be StringDType too.

Returns

(NDArray, NDArray, NDArray): The three parts of the broadcast shape. For S / U each part has its own width (the widest of its values, 1 at least) and is laid out like a.

Remarks

NumPy returns three field views of one structured array for S / U; NumSharp has no structured dtype, so the parts are three arrays: NumPy's values and descriptors, not its strides or OWNDATA, and a part NumPy sizes at width 0 has width 1.

Exceptions

ArgumentNullException: An operand is null.
TypeError: No common dtype or no loop for the classes; two different StringDType NA objects.
IncorrectShapeException: The operands do not broadcast.
ValueError: An empty separator (empty separator); an empty broadcast; a numeric operand cast to text; a StringDType NA whose NA object is not a string.
UnicodeEncodeError: A non-ASCII separator cast to S.

replace(NDArray, NDArray, NDArray, NDArray)

NumPy's np.strings.replace(a, old, new, count=-1): each element with its occurrences of old replaced by new, left to right, at most count of them (a negative count replaces all). An empty old inserts new between every character and at both ends.

public static NDArray replace(NDArray a, NDArray old, NDArray @new, NDArray count = null)

Parameters

a NDArray: The strings (S, U or StringDType).
old NDArray: The searched strings. A C# string (NumPy's Python str, which has no dtype) is cast to a's dtype first — truncated to its width; an array keeps its own.
new NDArray: The replacements (the same rule as old).
count NDArray: The maximum replacements: an integer array or literal, broadcast; null is NumPy's -1.

Returns

NDArray: A fresh array (for S / U of a's class at the widest result, laid out like a).

Exceptions

ArgumentNullException: a, old or new is null.
TypeError: count is not an integer array (unsupported type float64 for operand 'count'); no common dtype or no loop for the classes; a uint64 count (the float descriptor); two different StringDType NA objects.
IncorrectShapeException: A statement's operands do not broadcast.
ValueError: An empty broadcast; a numeric operand cast to text; a StringDType NA its rule refuses; a chararray text operand beside a StringDType one that NumPy's trivial loop copies into StringDType() (Can only create a chararray from string data.).
UnicodeEncodeError: A non-ASCII old / new cast to S.

rfind(NDArray, NDArray, NDArray, NDArray)

NumPy's np.strings.rfind(a, sub, start=0, end=None): for each element, the highest index where sub occurs inside a[start:end], or -1 (an empty substring is found at the end).

public static NDArray rfind(NDArray a, NDArray sub, NDArray start = null, NDArray end = null)

Parameters

a NDArray: The searched strings.
sub NDArray: The substrings (see find(NDArray, NDArray, NDArray, NDArray)).
start NDArray: The range start (null = 0).
end NDArray: The range end (null = the whole string).

Returns

NDArray: An int64 array of the broadcast shape.

Exceptions

TypeError: No loop for the operand classes; two different StringDType NA objects.
TypeError: A start / end that cannot reach int64 by a same_kind cast.
OverflowException: A start / end literal past int64.
IncorrectShapeException: The operands do not broadcast.
ValueError: A StringDType NA whose NA object is not a string; a chararray operand beside a StringDType one that NumPy's trivial loop copies into StringDType() (0-d, or 1-d with at most np.getbufsize() elements: Can only create a chararray from string data.).

rindex(NDArray, NDArray, NDArray, NDArray)

NumPy's np.strings.rindex(a, sub, start=0, end=None): rfind(NDArray, NDArray, NDArray, NDArray), but an element with no match raises ValueError: substring not found.

public static NDArray rindex(NDArray a, NDArray sub, NDArray start = null, NDArray end = null)

Parameters

a NDArray: The searched strings.
sub NDArray: The substrings (see find(NDArray, NDArray, NDArray, NDArray)).
start NDArray: The range start (null = 0).
end NDArray: The range end (null = the whole string).

Returns

NDArray: An int64 array of the broadcast shape.

Exceptions

TypeError: No loop for the operand classes; two different StringDType NA objects.
TypeError: A start / end that cannot reach int64 by a same_kind cast.
OverflowException: A start / end literal past int64.
IncorrectShapeException: The operands do not broadcast.
ValueError: An element without a match; a StringDType NA whose NA object is not a string; a chararray operand beside a StringDType one that NumPy's trivial loop copies into StringDType() (0-d, or 1-d with at most np.getbufsize() elements: Can only create a chararray from string data.).

rjust(NDArray, NDArray, NDArray)

NumPy's np.strings.rjust(a, width, fillchar=' '): each element right-justified in a string of width characters, padded on the left with fillchar.

public static NDArray rjust(NDArray a, NDArray width, NDArray fillchar = null)

Parameters

a NDArray: The strings.
width NDArray: The integer widths, broadcast.
fillchar NDArray: The one-character fills (null = ' ').

Returns

NDArray: A fresh array (see center(NDArray, NDArray, NDArray)).

Exceptions

ArgumentNullException: a or width is null.
TypeError: See center(NDArray, NDArray, NDArray).
IncorrectShapeException: The operands do not broadcast.
ValueError: An empty broadcast; a StringDType NA its rule refuses; the trivial-loop copy of a chararray operand (see center(NDArray, NDArray, NDArray)).
UnicodeEncodeError: A non-ASCII fill for an S operand.
OverflowException: A StringDType result past sys.maxsize bytes.

rpartition(NDArray, NDArray)

NumPy's np.strings.rpartition(a, sep): each element split around the LAST occurrence of sep into (before, separator, after); without a match, (empty, empty, the element).

public static (NDArray Before, NDArray Separator, NDArray After) rpartition(NDArray a, NDArray sep)

Parameters

a NDArray: The strings.
sep NDArray: The separators (see partition(NDArray, NDArray)).

Returns

(NDArray, NDArray, NDArray): The three parts of the broadcast shape.

Exceptions

ArgumentNullException: An operand is null.
TypeError: No common dtype or no loop for the classes; two different StringDType NA objects.
IncorrectShapeException: The operands do not broadcast.
ValueError: An empty separator; an empty broadcast; a numeric operand cast to text; a StringDType NA whose NA object is not a string.
UnicodeEncodeError: A non-ASCII separator cast to S.

rstrip(NDArray, NDArray)

NumPy's np.strings.rstrip(a, chars=None): each element without its TRAILING characters found in chars (whitespace for null).

public static NDArray rstrip(NDArray a, NDArray chars = null)

Parameters

a NDArray: The strings.
chars NDArray: The characters to remove (see strip(NDArray, NDArray)), or null for whitespace.

Returns

NDArray: A fresh array of a's dtype.

Exceptions

ArgumentNullException: a is null.
TypeError: No loop for the operand classes; two different StringDType NA objects.
IncorrectShapeException: The operands do not broadcast.
ValueError: A StringDType NA its rule refuses; a chararray operand beside a StringDType one that NumPy's trivial loop copies into StringDType() (0-d, or 1-d with at most np.getbufsize() elements: Can only create a chararray from string data.).

slice(NDArray)

NumPy's np.strings.slice(a): every element whole (a[:] of each string).

public static NDArray slice(NDArray a)

Parameters

a NDArray: The strings (S, U or StringDType).

Returns

NDArray: A fresh array of a's dtype.

Exceptions

ArgumentNullException: a is null.
TypeError: A non-text operand; a StringDType NA (Cannot slice null string).

slice(NDArray, NDArray)

NumPy's np.strings.slice(a, stop): one argument after a is the STOP, as in Python's slice(stop) — each element's s[:stop]; null is NumPy's None (the whole string).

public static NDArray slice(NDArray a, NDArray stop)

Parameters

a NDArray: The strings.
stop NDArray: The stops (characters; negative counts from the end), any integer dtype, or null.

Returns

NDArray: A fresh array of a's dtype.

Exceptions

ArgumentNullException: a is null.
TypeError: A non-text operand; a StringDType NA.
TypeError: A stop that cannot reach int64 by a same_kind cast.
OverflowException: A stop literal past int64.
IncorrectShapeException: The operands do not broadcast.

slice(NDArray, NDArray, NDArray)

NumPy's np.strings.slice(a, start, stop): each element's s[start:stop] (null bounds are NumPy's None).

public static NDArray slice(NDArray a, NDArray start, NDArray stop)

Parameters

a NDArray: The strings.
start NDArray: The starts, or null.
stop NDArray: The stops, or null.

Returns

NDArray: A fresh array of a's dtype.

Exceptions

ArgumentNullException: a is null.
TypeError: A non-text operand; a StringDType NA.
TypeError: A bound that cannot reach int64 by a same_kind cast.
OverflowException: A bound literal past int64.
IncorrectShapeException: The operands do not broadcast.

slice(NDArray, NDArray, NDArray, NDArray)

NumPy's np.strings.slice(a, start, stop, step): each element's s[start:stop:step], characters (code points for StringDType), every argument broadcast.

public static NDArray slice(NDArray a, NDArray start, NDArray stop, NDArray step)

Parameters

a NDArray: The strings.
start NDArray: The starts, or null (NumPy's None: the end for a negative step, 0 otherwise).
stop NDArray: The stops, or null (past the beginning for a negative step, past the end otherwise).
step NDArray: The steps (an integer array or literal, never 0), or null for 1.

Returns

NDArray: A fresh array of a's dtype.

Exceptions

ArgumentNullException: a is null.
TypeError: step is not an integer array (unsupported type float64 for operand 'step'); a non-text operand; a StringDType NA (Cannot slice null string).
ValueError: A zero step (slice step cannot be zero).
TypeError: A bound that cannot reach int64 by a same_kind cast.
OverflowException: A bound literal past int64.
IncorrectShapeException: The operands do not broadcast.

startswith(NDArray, NDArray, NDArray, NDArray)

NumPy's np.strings.startswith(a, prefix, start=0, end=None): whether each element's a[start:end] begins with prefix.

public static NDArray startswith(NDArray a, NDArray prefix, NDArray start = null, NDArray end = null)

Parameters

a NDArray: The tested strings.
prefix NDArray: The prefixes (see find(NDArray, NDArray, NDArray, NDArray) for the classes).
start NDArray: The range start (null = 0).
end NDArray: The range end (null = the whole string).

Returns

NDArray: A bool array of the broadcast shape.

Exceptions

TypeError: No loop for the operand classes; two different StringDType NA objects.
TypeError: A start / end that cannot reach int64 by a same_kind cast.
OverflowException: A start / end literal past int64.
IncorrectShapeException: The operands do not broadcast.
ValueError: A StringDType NA whose NA object is neither a string nor NaN-like (a NaN-like NA is False); a chararray operand beside a StringDType one that NumPy's trivial loop copies into StringDType() (0-d, or 1-d with at most np.getbufsize() elements: Can only create a chararray from string data.).

str_len(NDArray, NDArray, NDArray, DType)

NumPy's np.strings.str_len ufunc: the length of every element as int64 — characters for U, bytes for S, code points for StringDType. Trailing NULs never count, embedded ones do ('a\0b' has length 3, 'ab\0' length 2).

public static NDArray str_len(NDArray x, NDArray @out = null, NDArray where = null, DType dtype = null)

Parameters

x NDArray: The strings (S, U or StringDType).
out NDArray: An output to write into and return (any dtype int64 casts to under same_kind), or null.
where NDArray: A bool mask: only elements where it is True are computed, the others keep out's values (uninitialized in a fresh result), or null.
dtype DType: NumPy's dtype=: only int64 has a loop.

Returns

NDArray: The lengths, or out.

Remarks

A numpy.char.chararray operand gives a plain int64 result (chararray.array_wrap keeps only text results); a chararray out comes back as a new view of it.

Exceptions

ArgumentNullException: x is null.
TypeError: x is not text, or dtype is not int64 (NumPy's no-loop text).
TypeError: out cannot receive int64 (the same_kind output cast).
ArgumentException: A non-bool where; operands that do not broadcast with out / where.
ValueError: A read-only out; a StringDType NA whose descriptor's NA object is not a string (The length of a null string is undefined).
IncorrectShapeException: The operands do not broadcast.

strip(NDArray, NDArray)

NumPy's np.strings.strip(a, chars=None): each element without its leading and trailing characters found in chars (Python's whitespace for null), keeping a's dtype.

public static NDArray strip(NDArray a, NDArray chars = null)

Parameters

a NDArray: The strings (S, U or StringDType).
chars NDArray: The characters to remove, as a set (the same class as a, or U with a StringDType a); null strips whitespace (NumPy's None).

Returns

NDArray: A fresh array of a's dtype and the broadcast shape (a StringDType result takes the compatible NA object).

Remarks

Whitespace is the class's: ASCII whitespace for S, Python's str.isspace for U / StringDType. NumPy's trailing scan also strips NUL characters, its leading scan does not (strip(' \0ab') is '\0ab'). A numpy.char.chararray operand gives a chararray view of the result.

Exceptions

ArgumentNullException: a is null.
TypeError: No loop for the operand classes (NumPy's no-loop text); two different StringDType NA objects.
IncorrectShapeException: The operands do not broadcast.
ValueError: A StringDType NA its rule refuses; a chararray operand beside a StringDType one that NumPy's trivial loop copies into StringDType() (0-d, or 1-d with at most np.getbufsize() elements: Can only create a chararray from string data.).

swapcase(NDArray)

NumPy's np.strings.swapcase: each element's uppercase characters lowered and lowercase characters uppercased (CPython's str.swapcase / bytes.swapcase); a titlecase character such as 'ǅ' is neither and stays.

public static NDArray swapcase(NDArray a)

Parameters

a NDArray: The strings: S, U or StringDType.

Returns

NDArray: A fresh C-ordered array of a's dtype (an S / U result cut to the element width).

Remarks

swapcase applied twice is not always the identity: 'ß' swaps to 'SS', which swaps back to 'ss'.

Exceptions

ArgumentNullException: a is null.
TypeError: a is not text; a StringDType NA whose NA object is not a str.
SystemError: A U element holding a code unit past U+10FFFF.

title(NDArray)

NumPy's np.strings.title: each element in titlecase — a character after a cased character lowered, any other titlecased (CPython's str.title; bytes.title over ASCII letters).

public static NDArray title(NDArray a)

Parameters

a NDArray: The strings: S, U or StringDType.

Returns

NDArray: A fresh C-ordered array of a's dtype (an S / U result cut to the element width).

Remarks

Words are not detected: any uncased character starts a new "word", so "they're bill's" becomes "They'Re Bill'S" and "hello2world" "Hello2World", as in Python.

Exceptions

ArgumentNullException: a is null.
TypeError: a is not text; a StringDType NA whose NA object is not a str.
SystemError: A U element holding a code unit past U+10FFFF.

translate(NDArray, object, object)

NumPy's np.strings.translate: every character of each element mapped through table — CPython's str.translate for U and StringDType (a dict keyed by code point: a str value replaces the character, an int names a code point, null deletes it, a missing key keeps it), bytes.translate for S (a 256-byte table, or null; then the bytes of deletechars are deleted).

public static NDArray translate(NDArray a, object table, object deletechars = null)

Parameters

a NDArray: The strings: S, U or StringDType (a C# string converts to a 0-d U array).
table object: The table, read as the Python object it stands for (NumPy converts it with np.asarray and broadcasts it against a, one table per element): an IDictionary is a dict (keys equal to an integer under Python's == — 97, 97.0, true for 1 — map that code point; a string key never does); a string is a str and a byte[] bytes (a str table maps code point c to table[c]; an S table must be exactly 256 bytes); null is None; a C# array or list of tables is an array of tables; an NDArray is used as it is.
deletechars object: The bytes to delete (an S operand only): a byte[] or string (its UCS-4 bytes, as NumPy reads an np.str_). Null (Python's None) passes nothing. NumPy ignores it for U, and passes it to str.translate for StringDType, which refuses it.

Returns

NDArray: A fresh C-ordered array of a's dtype over the broadcast shape. An S / U result keeps the element width, so a translation that grows is cut ({97: "XYZ"} over a U3 "abc" is "XYZ"). A StringDType result has a's NA object and coercion.

Remarks

The element is the text without its trailing NULs for S / U (NumPy's scalar), the whole text for StringDType. An error ends the call at the first element (C order) that raises, as in NumPy.

np.strings.translate(np.array(new[] { "abc", "cab" }), new Dictionary<int, string> { [97] = "x", [98] = null }) is ["xc", "cx"] (U3). A C# char argument is NumSharp's Char scalar, a 16-bit number to NumPy: as a U table it keeps every character.

Exceptions

ArgumentNullException: a is null.
TypeError: a is not text (string operation on non-string array); a U table that cannot be indexed ('NoneType' object is not subscriptable, raised only when a character is looked up); a dict value that is not an int, None or str (character mapping must return integer, None or str); an S table or delete set that is not bytes-like (a bytes-like object is required, not 'dict'); a StringDType NA whose NA object is not a str (descriptor 'translate' for 'str' objects doesn't apply to a 'NoneType' object); deletechars with a StringDType operand (str.translate() takes exactly one argument (2 given)); a StringDType result holding a lone surrogate (result array type does not match underlying function).
ValueError: A mapping outside range(0x110000) (character mapping must be in range(0x110000)); an S table that is not 256 bytes long (translation table must be 256 characters long, raised for any non-empty array, even of empty strings).
SystemError: A U unit past U+10FFFF that the call would keep in a str (CPython's invalid maximum character passed to PyUnicode_New).
IncorrectShapeException: The arguments do not broadcast (shape mismatch: objects cannot be broadcast to a single shape. Mismatch is between arg 0 with shape (3,) and arg 1 with shape (2,).).
NotSupportedException: An argument with no NumSharp form (an object array of lists).

upper(NDArray)

NumPy's np.strings.upper: each element's text uppercased — CPython's str.upper (the full mappings of Unicode 15.0.0: 'ß' becomes 'SS', 'ﬃ' 'FFI') for U and StringDType, bytes.upper (ASCII letters only) for S.

public static NDArray upper(NDArray a)

Parameters

a NDArray: The strings: S, U or StringDType (a C# string converts to a 0-d U array).

Returns

NDArray: A fresh C-ordered array of a's dtype. An S / U result keeps the element width, so a mapping that grows is cut: upper of 'ß' in a U1 array is 'S'. A StringDType result has a's NA object and coercion.

Remarks

The element is the text without its trailing NULs for S / U (NumPy's scalar), the whole text for StringDType (a NUL is a character there). Under a string NA object (StringDType(na_object: "N/A")) an NA is uppercased as that text, and any result equal to the NA's text is stored as the NA, as NumPy's setitem stores it.

np.strings.upper(np.array(new[] { "aBc", "straße" })) is ["ABC", "STRASS"] (U6). A numpy.char.chararray operand gives a plain array (NumPy's np.asarray).

Exceptions

ArgumentNullException: a is null.
TypeError: a is not text (string operation on non-string array); a StringDType NA whose NA object is not a str (descriptor 'upper' for 'str' objects doesn't apply to a 'float' object, quoting the object's Python type).
SystemError: A U element holding a code unit past U+10FFFF (CPython's invalid maximum character passed to PyUnicode_New).

zfill(NDArray, NDArray)

NumPy's np.strings.zfill(a, width): each element left-filled with '0' to width characters, a leading '+' / '-' moved in front of the zeros (zfill('-42', 5) is '-0042').

public static NDArray zfill(NDArray a, NDArray width)

Parameters

a NDArray: The strings (S, U or StringDType).
width NDArray: The widths: an integer array or literal, broadcast.

Returns

NDArray: A fresh array (for S / U at the widest result width, laid out like a).

Exceptions

ArgumentNullException: a or width is null.
TypeError: width is not an integer array; a non-text operand; a uint64 width (the float descriptor); a StringDType NA that is neither a string nor NaN-like.
IncorrectShapeException: The operands do not broadcast.
ValueError: An empty broadcast.

Table of Contents

Class np.strings

Remarks

Methods

add(NDArray, NDArray, NDArray, NDArray, DType)

Parameters

Returns

Exceptions

add(NDArray, string, NDArray, NDArray, DType)

Parameters

Returns

Exceptions

add(string, NDArray, NDArray, NDArray, DType)

Parameters

Returns

Exceptions

add(string, string)

Parameters

Returns

Exceptions

capitalize(NDArray)

Parameters

Returns

Remarks

Exceptions

center(NDArray, NDArray, NDArray)

Parameters

Returns

Exceptions

count(NDArray, NDArray, NDArray, NDArray)

Parameters

Returns

Exceptions

decode(NDArray, object, object)

Parameters

Returns

Remarks

Exceptions

encode(NDArray, object, object)

Parameters

Returns

Remarks

Exceptions

endswith(NDArray, NDArray, NDArray, NDArray)

Parameters

Returns

Exceptions

equal(NDArray, NDArray, NDArray, NDArray, DType)

Parameters

Returns

Exceptions

expandtabs(NDArray, NDArray)

Parameters

Returns

Exceptions

find(NDArray, NDArray, NDArray, NDArray)

Parameters

Returns

Exceptions

greater(NDArray, NDArray, NDArray, NDArray, DType)

Parameters

Returns

Exceptions

greater_equal(NDArray, NDArray, NDArray, NDArray, DType)

Parameters

Returns

Exceptions

index(NDArray, NDArray, NDArray, NDArray)

Parameters

Returns

Exceptions

isalnum(NDArray, NDArray, NDArray, DType)

Parameters

Returns

Remarks

Exceptions

isalpha(NDArray, NDArray, NDArray, DType)

Parameters

Returns

Remarks