BITPOS

查找字符串中第一个设置 (1) 或清除 (0) 位。

语法

BITPOS key bit [start [end [BYTE | BIT]]]

引入版本：2.8.7

复杂度摘要：O(N)

返回字符串中第一个设置为 1 或 0 的位的位置。

返回位置，将字符串视为从左到右的位数组，其中第一个字节的最高有效位位于位置 0，第二个字节的最高有效位位于位置 8，依此类推。

GETBIT 和 SETBIT 遵循相同的位位置约定。

默认情况下，检查字符串中包含的所有字节。可以仅在传递附加参数开始和结束的指定间隔中查找位（可以仅传递开始，该操作将假定末尾是字符串的最后一个字节。但是，存在语义差异，稍后将对此进行解释）。默认情况下，该范围被解释为字节范围而不是位范围，因此 start=0 和 end=2 意味着查看前三个字节。

您可以使用可选的 BIT 修饰符来指定应将范围解释为位范围。所以start=0和end=2的意思就是看前三位。

请注意，即使使用开始和结束指定范围，位位置也始终以从位 0 开始的绝对值形式返回。

与 GETRANGE 命令一样，start 和 end 可以包含负值，以便从字符串末尾开始索引字节，其中 -1 是最后一个字节，-2 是倒数第二个字节，依此类推。当指定 BIT 时，-1 是最后一位，-2 是倒数第二位，依此类推。

如果键不存在，则将其视为零位的无限数组：搜索清除位 (0) 返回 0，而搜索设置位 (1) 返回 -1。相反，现有的空字符串（包含“”的键）根本不包含任何位，因此搜索 0 或 1 始终返回 -1。

必需参数

key

保存字符串的键的名称。

bit

要搜索的位值：0 或 1。

可选参数

start

开始搜索的偏移量。默认情况下是字节偏移量；负值从字符串末尾开始计数。

end

停止搜索的偏移量（含）。

BYTE | BIT

将 start 和 end 解释为字节偏移（BYTE，默认值）或位偏移（BIT）。

示例

redis> SET mykey "\xff\xf0\x00"
OK
redis> BITPOS mykey 0
(integer) 12
redis> SET mykey "\x00\xff\xf0"
OK
redis> BITPOS mykey 1 0
(integer) 8
redis> BITPOS mykey 1 2
(integer) 16
redis> BITPOS mykey 1 2 -1 BYTE
(integer) 16
redis> BITPOS mykey 1 7 15 BIT
(integer) 8
redis> set mykey "\x00\x00\x00"
OK
redis> BITPOS mykey 1
(integer) -1
redis> BITPOS mykey 1 7 -3 BIT
(integer) -1

Redis Software 与 Redis Cloud 兼容性

Redis 软件	Redis Cloud	说明
✅ 标准 ✅ 主动-主动	✅ 标准 ✅ 主动-主动

返回值

RESP2

以下之一： * 整数回复：根据请求将第一位设置为 1 或 0 的位置 * 整数回复：-1。如果 bit 参数为 1 并且字符串为空或仅由零字节组成如果我们查找设置位（位参数为 1）并且字符串为空或仅由零字节组成，则返回 -1。如果我们查找清除位（位参数为 0）并且字符串仅包含设置为 1 的位，则函数返回第一个位，而不是右侧字符串的一部分。因此，如果字符串是设置为值 0xff 的三个字节，则命令 BITPOS key 0 将返回 24，因为直到位 23 所有位均为 1。如果您查找清除位并且未指定范围或未指定范围或开始参数只，则该函数会将字符串的右侧视为用零填充。但是，如果您正在寻找清除位并指定开始和结束的范围，则此行为会发生变化。如果在指定范围内未找到清除位，则该函数将返回 -1，因为用户指定了清除范围并且该范围内没有 0 位。

RESP3

以下之一： * 整数回复：根据请求将第一位设置为 1 或 0 的位置 * 整数回复：-1。如果 bit 参数为 1 并且字符串为空或仅由零字节组成如果我们查找设置位（位参数为 1）并且字符串为空或仅由零字节组成，则返回 -1。如果我们查找清除位（位参数为 0）并且字符串仅包含设置为 1 的位，则函数返回第一个位，而不是右侧字符串的一部分。因此，如果字符串是设置为值 0xff 的三个字节，则命令 BITPOS key 0 将返回 24，因为直到位 23 所有位均为 1。如果您查找清除位并且未指定范围或未指定范围或开始参数只，则该函数会将字符串的右侧视为用零填充。但是，如果您正在寻找清除位并指定开始和结束的范围，则此行为会发生变化。如果在指定范围内未找到清除位，则该函数将返回 -1，因为用户指定了清除范围并且该范围内没有 0 位。

资料来源：Redis 官方 BITPOS 文档；中文内容参考 Redis 文档许可。