BITPOS

BITPOS

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

Доступно с версии:

2.8.7

Временная сложность:

O(N)

Категории ACL:

@read, @bitmap, @slow,

Возвращает позицию первого бита, установленного в 1 или 0 в строке.

Позиция возвращается, рассматривая строку как массив битов слева направо, где самый старший бит первого байта находится в позиции 0, самый старший бит второго байта — в позиции 8 и так далее.

Такая же конвенция по позициям битов используется в командах GETBIT и SETBIT.

По умолчанию проверяются все байты, содержащиеся в строке. Можно искать биты только в заданном интервале, передавая дополнительные аргументы start и end (можно передать только start, в этом случае операция будет предполагать, что end — это последний байт строки. Однако существуют семантические различия, как объяснено ниже). По умолчанию диапазон интерпретируется как диапазон байтов, а не диапазон битов, поэтому start=0 и end=2 означает, что необходимо посмотреть на первые три байта.

Можно использовать необязательный модификатор BIT для указания, что диапазон следует интерпретировать как диапазон битов. Таким образом, start=0 и end=2 означают просмотр первых трёх битов.

Обратите внимание, что позиции битов всегда возвращаются как абсолютные значения, начиная с бита ноль, даже когда start и end используются для задания диапазона.

Как и для команды GETRANGE, start и end могут содержать отрицательные значения для индексации байтов, начиная с конца строки, где -1 — последний байт, -2 — предпоследний и так далее. При указании BIT, -1 — это последний бит, -2 — предпоследний и так далее.

Отсутствующие ключи обрабатываются как пустые строки.

Возврат

Целое число

Команда возвращает позицию первого бита, установленного в 1 или 0 в соответствии с запросом.

Если мы ищем установленные биты (аргумент bit равен 1), а строка пуста или состоит только из нулевых байтов, возвращается -1.

Если мы ищем сброшенные биты (аргумент bit равен 0), а строка содержит только установленные в 1 биты, функция возвращает позицию первого бита, отсутствующего в строке справа. Таким образом, если строка состоит из трёх байтов, установленных в значение 0xff, команда BITPOS key 0 вернёт 24, так как до бита 23 все биты равны 1.

В принципе, функция рассматривает правую часть строки как заполненную нулями, если ищете сброшенные биты и не задаёте диапазон или указываете только аргумент start.

Однако это поведение меняется, если вы ищете сброшенные биты и задаёте диапазон с помощью обоих аргументов start и end. Если ни один сброшенный бит не найден в заданном диапазоне, функция возвращает -1, так как пользователь указал диапазон для сброшенных битов, а битов 0 в этом диапазоне нет.

Примеры

SET mykey "\xff\xf0\x00"
BITPOS mykey 0
SET mykey "\x00\xff\xf0"
BITPOS mykey 1 0
BITPOS mykey 1 2
BITPOS mykey 1 2 -1 BYTE
BITPOS mykey 1 7 15 BIT
set mykey "\x00\x00\x00"
BITPOS mykey 1
BITPOS mykey 1 7 -3 BIT

История

• Начиная с версии Redis 7.0.0: Добавлена опция BYTE|BIT.