使用字符串和字节数组#

虽然 NumPy 主要是一个数值库，但使用 NumPy 字符串或字节数组通常很方便。两种最常见的用例是

  • 处理从数据文件加载或内存映射的数据，其中数据中的一个或多个字段是字符串或字节串，并且提前知道字段的最大长度。这通常用于名称或标签字段。

  • 使用 NumPy 索引和广播处理未知长度的 Python 字符串数组，这些字符串可能也可能没有为每个值定义数据。

对于第一个用例，NumPy 提供了固定宽度的 numpy.void、numpy.str_ 和 numpy.bytes_ 数据类型。对于第二个用例，numpy 提供了 numpy.dtypes.StringDType。下面我们将描述如何使用固定宽度和可变宽度字符串数组，如何在两种表示之间进行转换，并提供一些关于如何在 NumPy 中最有效地使用字符串数据的建议。

固定宽度数据类型#

在 NumPy 2.0 之前，固定宽度的 numpy.str_、numpy.bytes_ 和 numpy.void 数据类型是 NumPy 中唯一可用于处理字符串和字节串的类型。因此，它们分别用作字符串和字节串的默认 dtype。

>>> np.array(["hello", "world"])
array(['hello', 'world'], dtype='<U5')

此处检测到的数据类型为 '<U5'，或小端序 Unicode 字符串数据，最大长度为 5 个 Unicode 代码点。

字节串也类似

>>> np.array([b"hello", b"world"])
array([b'hello', b'world'], dtype='|S5')

由于这是单字节编码，字节序为 ‘|’（不适用），检测到的数据类型为最大 5 个字符的字节串。

您还可以使用 numpy.void 来表示字节串

>>> np.array([b"hello", b"world"]).astype(np.void)
array([b'\x68\x65\x6C\x6C\x6F', b'\x77\x6F\x72\x6C\x64'], dtype='|V5')

当处理不能很好地表示为字节串的字节流时，这最有用，而将其视为 8 位整数的集合更好。

可变宽度字符串#

版本 2.0 中的新功能。

注意

numpy.dtypes.StringDType 是 NumPy 的新增功能，它使用 NumPy 中对灵活的用户定义数据类型的新支持来实现，并且在生产工作流程中的测试不如旧的 NumPy 数据类型广泛。

通常，现实世界的字符串数据没有可预测的长度。在这些情况下，使用固定宽度字符串很尴尬，因为在创建数组之前，存储所有数据而不截断需要知道想要存储在数组中的最长字符串的长度。

为了支持这种情况，NumPy 提供了 numpy.dtypes.StringDType，它以 UTF-8 编码在 NumPy 数组中存储可变宽度字符串数据。

>>> from numpy.dtypes import StringDType
>>> data = ["this is a longer string", "short string"]
>>> arr = np.array(data, dtype=StringDType())
>>> arr
array(['this is a longer string', 'short string'], dtype=StringDType())

请注意，与固定宽度字符串和大多数其他 NumPy 数据类型不同，StringDType 不会将字符串数据存储在“主” ndarray 数据缓冲区中。相反，数组缓冲区用于存储有关字符串数据在内存中存储位置的元数据。这种差异意味着期望数组缓冲区包含字符串数据的代码将无法正常工作，并且需要更新以支持 StringDType。

还请注意，与固定宽度字符串和大多数其他 NumPy 数据类型不同，StringDType 不在“主要”ndarray数据缓冲区中存储字符串数据。相反，数组缓冲区用于存储有关字符串数据在内存中存储位置的元数据。这种差异意味着期望数组缓冲区包含字符串数据的代码将无法正常工作，需要更新以支持StringDType。

缺失数据支持#

字符串数据集通常不完整，需要一个特殊的标签来指示值缺失。默认情况下，StringDType 除了使用空字符串填充空数组之外，没有其他对缺失值的特殊支持。

>>> np.empty(3, dtype=StringDType())
array(['', '', ''], dtype=StringDType())

或者，您可以通过将 na_object 作为初始化程序的关键字参数传递来创建具有缺失值支持的 StringDType 实例。

>>> dt = StringDType(na_object=None)
>>> arr = np.array(["this array has", None, "as an entry"], dtype=dt)
>>> arr
array(['this array has', None, 'as an entry'],
      dtype=StringDType(na_object=None))
>>> arr[1] is None
True

na_object 可以是任何任意的 Python 对象。常见的选择是 numpy.nan、float('nan')、None、专门用于表示缺失数据的对象（如 pandas.NA），或一个（希望是）唯一的字符串，如 "__placeholder__"。

NumPy 对 NaN 样哨兵和字符串哨兵有特殊处理。

NaN 样缺失数据哨兵#

NaN 样哨兵将自身作为算术运算的结果返回。这包括 python nan 浮点数和 Pandas 缺失数据哨兵 pd.NA。NaN 样哨兵在字符串操作中继承这些行为。这意味着，例如，与任何其他字符串相加的结果都是哨兵。

>>> dt = StringDType(na_object=np.nan)
>>> arr = np.array(["hello", np.nan, "world"], dtype=dt)
>>> arr + arr
array(['hellohello', nan, 'worldworld'], dtype=StringDType(na_object=nan))

遵循浮点数组中 nan 的行为，NaN 样哨兵排序到数组的末尾。

>>> np.sort(arr)
array(['hello', 'world', nan], dtype=StringDType(na_object=nan))

字符串缺失数据哨兵#

字符串缺失数据值是 str 或 str 的子类型的实例。如果将此类数组传递给字符串操作或强制转换，“缺失”条目将被视为其值由字符串哨兵给出。比较操作同样直接使用哨兵值表示缺失条目。

其他哨兵#

其他对象，例如 None 也支持作为缺失数据哨兵。如果使用此类哨兵的数组中存在任何缺失数据，则字符串操作将引发错误。

>>> dt = StringDType(na_object=None)
>>> arr = np.array(["this array has", None, "as an entry"])
>>> np.sort(arr)
Traceback (most recent call last):
...
TypeError: '<' not supported between instances of 'NoneType' and 'str'

强制转换非字符串#

默认情况下，非字符串数据将强制转换为字符串。

>>> np.array([1, object(), 3.4], dtype=StringDType())
array(['1', '<object object at 0x7faa2497dde0>', '3.4'], dtype=StringDType())

如果不需要此行为，则可以通过在初始化程序中设置 coerce=False 来创建禁用字符串强制转换的 DType 实例。

>>> np.array([1, object(), 3.4], dtype=StringDType(coerce=False))
Traceback (most recent call last):
...
ValueError: StringDType only allows string data when string coercion is disabled.

这允许在 NumPy 用于创建数组的同一数据传递中进行严格的数据验证。设置 coerce=True 将恢复默认行为，允许强制转换为字符串。

在固定宽度字符串之间进行强制转换#

StringDType 支持在 numpy.str_、numpy.bytes_ 和 numpy.void 之间进行往返强制转换。当需要在 ndarray 中内存映射字符串或需要固定宽度字符串来读取和写入具有已知最大字符串长度的列数据格式时，强制转换为固定宽度字符串最有用。

在所有情况下，强制转换为固定宽度字符串都需要指定允许的最大字符串长度。

>>> arr = np.array(["hello", "world"], dtype=StringDType())
>>> arr.astype(np.str_)  
Traceback (most recent call last):
...
TypeError: Casting from StringDType to a fixed-width dtype with an
unspecified size is not currently supported, specify an explicit
size for the output dtype instead.

The above exception was the direct cause of the following
exception:

TypeError: cannot cast dtype StringDType() to <class 'numpy.dtypes.StrDType'>.
>>> arr.astype("U5")
array(['hello', 'world'], dtype='<U5')

numpy.bytes_ 转换最适用于已知仅包含 ASCII 字符的字符串数据，因为此范围之外的字符无法在 UTF-8 编码中用单个字节表示，因此会被拒绝。

任何有效的 Unicode 字符串都可以转换为 numpy.str_，尽管 numpy.str_ 对所有字符使用 32 位 UCS4 编码，但这对于可以用更高效的编码很好地表示的真实世界文本数据来说，通常会浪费内存。

此外，任何有效的 Unicode 字符串都可以转换为 numpy.void，将 UTF-8 字节直接存储在输出数组中。

>>> arr = np.array(["hello", "world"], dtype=StringDType())
>>> arr.astype("V5")
array([b'\x68\x65\x6C\x6C\x6F', b'\x77\x6F\x72\x6C\x64'], dtype='|V5')

必须注意确保输出数组有足够的空闲空间来容纳字符串中的 UTF-8 字节，因为 UTF-8 字节流的字节大小不一定与字符串中的字符数相同。