BITPOS

Syntax text Syntax diagram API methods

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

Client:

bitpos(
    key: KeyT,
    bit: int,
    start: Optional[int] = None,
    end: Optional[int] = None,
    mode: Optional[str] = None
) → ResponseT

BITPOS(
    key: RedisArgument,
    bit: BitValue,
    start?: number,
    end?: number,
    mode?: 'BYTE' | 'BIT'
) → Any

bitpos(
    key: byte[],
    value: boolean
) → long

bitpos(
    key: Any,
    value: Any,
    BitPosParams(: new
) → return

bitpos(
    key: byte[],
    value: boolean,
    params: BitPosParams
) → long

bitpos(
    key: String,
    value: boolean
) → long

bitpos(
    key: String,
    value: boolean,
    params: BitPosParams
) → long

bitpos(
    key: K,  // the key.
    state: boolean  // the bit type: long.
) → Long  // Long integer-reply The command returns the position of the first bit set to 1 or 0 according to the request. If we look for set bits (the bit argument is 1) and the string is empty or composed of just zero bytes, -1 is returned. If we look for clear bits (the bit argument is 0) and the string only contains bit set to 1, the function returns the first bit not part of the string on the right. So if the string is three bytes set to the value 0xff the command BITPOS key 0 will return 24, since up to bit 23 all the bits are 1. Basically the function consider the right of the string as padded with zeros if you look for clear bits and specify no range or the <em>start</em> argument <strong>only</strong>. However this behavior changes if you are looking for clear bits and specify a range with both <strong>start</strong> and <strong>end</strong>. If no clear bit is found in the specified range, the function returns -1 as the user specified a clear range and there are no 0 bits in that range.

bitpos(
    key: K,  // the key.
    state: boolean,  // the bit type: long.
    start: long  // the start type: long.
) → Long  // Long integer-reply The command returns the position of the first bit set to 1 or 0 according to the request. If we look for set bits (the bit argument is 1) and the string is empty or composed of just zero bytes, -1 is returned. If we look for clear bits (the bit argument is 0) and the string only contains bit set to 1, the function returns the first bit not part of the string on the right. So if the string is three bytes set to the value 0xff the command BITPOS key 0 will return 24, since up to bit 23 all the bits are 1. Basically the function consider the right of the string as padded with zeros if you look for clear bits and specify no range or the <em>start</em> argument <strong>only</strong>. However this behavior changes if you are looking for clear bits and specify a range with both <strong>start</strong> and <strong>end</strong>. If no clear bit is found in the specified range, the function returns -1 as the user specified a clear range and there are no 0 bits in that range.

bitpos(
    key: K,  // the key.
    state: boolean,  // the bit type: long.
    start: long,  // the start type: long.
    end: long  // the end type: long.
) → Long  // Long integer-reply The command returns the position of the first bit set to 1 or 0 according to the request. If we look for set bits (the bit argument is 1) and the string is empty or composed of just zero bytes, -1 is returned. If we look for clear bits (the bit argument is 0) and the string only contains bit set to 1, the function returns the first bit not part of the string on the right. So if the string is three bytes set to the value 0xff the command BITPOS key 0 will return 24, since up to bit 23 all the bits are 1. Basically the function consider the right of the string as padded with zeros if you look for clear bits and specify no range or the <em>start</em> argument <strong>only</strong>. However this behavior changes if you are looking for clear bits and specify a range with both <strong>start</strong> and <strong>end</strong>. If no clear bit is found in the specified range, the function returns -1 as the user specified a clear range and there are no 0 bits in that range.

bitpos(
    key: K,  // the key.
    state: boolean  // the bit type: long.
) → RedisFuture<Long>  // Long integer-reply The command returns the position of the first bit set to 1 or 0 according to the request. If we look for set bits (the bit argument is 1) and the string is empty or composed of just zero bytes, -1 is returned. If we look for clear bits (the bit argument is 0) and the string only contains bit set to 1, the function returns the first bit not part of the string on the right. So if the string is three bytes set to the value 0xff the command BITPOS key 0 will return 24, since up to bit 23 all the bits are 1. Basically the function consider the right of the string as padded with zeros if you look for clear bits and specify no range or the <em>start</em> argument <strong>only</strong>. However this behavior changes if you are looking for clear bits and specify a range with both <strong>start</strong> and <strong>end</strong>. If no clear bit is found in the specified range, the function returns -1 as the user specified a clear range and there are no 0 bits in that range.

bitpos(
    key: K,  // the key.
    state: boolean,  // the bit type: long.
    start: long  // the start type: long.
) → RedisFuture<Long>  // Long integer-reply The command returns the position of the first bit set to 1 or 0 according to the request. If we look for set bits (the bit argument is 1) and the string is empty or composed of just zero bytes, -1 is returned. If we look for clear bits (the bit argument is 0) and the string only contains bit set to 1, the function returns the first bit not part of the string on the right. So if the string is three bytes set to the value 0xff the command BITPOS key 0 will return 24, since up to bit 23 all the bits are 1. Basically the function consider the right of the string as padded with zeros if you look for clear bits and specify no range or the <em>start</em> argument <strong>only</strong>. However this behavior changes if you are looking for clear bits and specify a range with both <strong>start</strong> and <strong>end</strong>. If no clear bit is found in the specified range, the function returns -1 as the user specified a clear range and there are no 0 bits in that range.

bitpos(
    key: K,  // the key.
    state: boolean,  // the bit type: long.
    start: long,  // the start type: long.
    end: long  // the end type: long.
) → RedisFuture<Long>  // Long integer-reply The command returns the position of the first bit set to 1 or 0 according to the request. If we look for set bits (the bit argument is 1) and the string is empty or composed of just zero bytes, -1 is returned. If we look for clear bits (the bit argument is 0) and the string only contains bit set to 1, the function returns the first bit not part of the string on the right. So if the string is three bytes set to the value 0xff the command BITPOS key 0 will return 24, since up to bit 23 all the bits are 1. Basically the function consider the right of the string as padded with zeros if you look for clear bits and specify no range or the <em>start</em> argument <strong>only</strong>. However this behavior changes if you are looking for clear bits and specify a range with both <strong>start</strong> and <strong>end</strong>. If no clear bit is found in the specified range, the function returns -1 as the user specified a clear range and there are no 0 bits in that range.

bitpos(
    key: K,  // the key.
    state: boolean  // the bit type: long.
) → Mono<Long>  // Long integer-reply The command returns the position of the first bit set to 1 or 0 according to the request. If we look for set bits (the bit argument is 1) and the string is empty or composed of just zero bytes, -1 is returned. If we look for clear bits (the bit argument is 0) and the string only contains bit set to 1, the function returns the first bit not part of the string on the right. So if the string is three bytes set to the value 0xff the command BITPOS key 0 will return 24, since up to bit 23 all the bits are 1. Basically the function consider the right of the string as padded with zeros if you look for clear bits and specify no range or the <em>start</em> argument <strong>only</strong>. However this behavior changes if you are looking for clear bits and specify a range with both <strong>start</strong> and <strong>end</strong>. If no clear bit is found in the specified range, the function returns -1 as the user specified a clear range and there are no 0 bits in that range.

bitpos(
    key: K,  // the key.
    state: boolean,  // the bit type: long.
    start: long  // the start type: long.
) → Mono<Long>  // Long integer-reply The command returns the position of the first bit set to 1 or 0 according to the request. If we look for set bits (the bit argument is 1) and the string is empty or composed of just zero bytes, -1 is returned. If we look for clear bits (the bit argument is 0) and the string only contains bit set to 1, the function returns the first bit not part of the string on the right. So if the string is three bytes set to the value 0xff the command BITPOS key 0 will return 24, since up to bit 23 all the bits are 1. Basically the function consider the right of the string as padded with zeros if you look for clear bits and specify no range or the <em>start</em> argument <strong>only</strong>. However this behavior changes if you are looking for clear bits and specify a range with both <strong>start</strong> and <strong>end</strong>. If no clear bit is found in the specified range, the function returns -1 as the user specified a clear range and there are no 0 bits in that range.

bitpos(
    key: K,  // the key.
    state: boolean,  // the bit type: long.
    start: long,  // the start type: long.
    end: long  // the end type: long.
) → Mono<Long>  // Long integer-reply The command returns the position of the first bit set to 1 or 0 according to the request. If we look for set bits (the bit argument is 1) and the string is empty or composed of just zero bytes, -1 is returned. If we look for clear bits (the bit argument is 0) and the string only contains bit set to 1, the function returns the first bit not part of the string on the right. So if the string is three bytes set to the value 0xff the command BITPOS key 0 will return 24, since up to bit 23 all the bits are 1. Basically the function consider the right of the string as padded with zeros if you look for clear bits and specify no range or the <em>start</em> argument <strong>only</strong>. However this behavior changes if you are looking for clear bits and specify a range with both <strong>start</strong> and <strong>end</strong>. If no clear bit is found in the specified range, the function returns -1 as the user specified a clear range and there are no 0 bits in that range.

BitPos(
    ctx: context.Context,
    key: string,
    bit: int64,
    pos: ...int64
) → *IntCmd

BitPosSpan(
    ctx: context.Context,
    key: string,
    bit: int8,
    start: Any,
    end: int64,
    span: string
) → *IntCmd

StringBitPosition(
    key: RedisKey,  // The key of the string.
    bit: bool,  // True to check for the first 1 bit, false to check for the first 0 bit.
    start: long,  // The position to start looking (defaults to 0).
    end: long,  // The position to stop looking (defaults to -1, unlimited).
    flags: CommandFlags  // The flags to use for this operation.
) → long  // The command returns the position of the first bit set to 1 or 0 according to the request. If we look for set bits(the bit argument is 1) and the string is empty or composed of just zero bytes, -1 is returned.

StringBitPosition(
    key: RedisKey,  // The key of the string.
    bit: bool,  // True to check for the first 1 bit, false to check for the first 0 bit.
    start: long,  // The position to start looking (defaults to 0).
    end: long,  // The position to stop looking (defaults to -1, unlimited).
    indexType: StringIndexType,  // In Redis 7+, we can choose if start and end specify a bit index or byte index (defaults to Byte).
    flags: CommandFlags  // The flags to use for this operation.
) → long  // The command returns the position of the first bit set to 1 or 0 according to the request. If we look for set bits(the bit argument is 1) and the string is empty or composed of just zero bytes, -1 is returned.

StringBitPositionAsync(
    key: RedisKey,
    bit: bool,
    start: long,
    end: long,
    flags: CommandFlags
) → Task<long>

StringBitPositionAsync(
    key: RedisKey,
    bit: bool,
    start: long,
    end: long,
    indexType: StringIndexType,
    flags: CommandFlags
) → Task<long>

StringBitPosition(
    key: RedisKey,  // The key of the string.
    bit: bool,  // True to check for the first 1 bit, false to check for the first 0 bit.
    start: long,  // The position to start looking (defaults to 0).
    end: long,  // The position to stop looking (defaults to -1, unlimited).
    flags: CommandFlags  // The flags to use for this operation.
) → long  // The command returns the position of the first bit set to 1 or 0 according to the request. If we look for set bits(the bit argument is 1) and the string is empty or composed of just zero bytes, -1 is returned.

StringBitPositionAsync(
    key: RedisKey,
    bit: bool,
    start: long,
    end: long,
    flags: CommandFlags
) → Task<long>

StringBitPositionAsync(
    key: RedisKey,
    bit: bool,
    start: long,
    end: long,
    indexType: StringIndexType,
    flags: CommandFlags
) → Task<long>

StringBitPosition(
    key: RedisKey,  // The key of the string.
    bit: bool,  // True to check for the first 1 bit, false to check for the first 0 bit.
    start: long,  // The position to start looking (defaults to 0).
    end: long,  // The position to stop looking (defaults to -1, unlimited).
    flags: CommandFlags  // The flags to use for this operation.
) → long  // The command returns the position of the first bit set to 1 or 0 according to the request. If we look for set bits(the bit argument is 1) and the string is empty or composed of just zero bytes, -1 is returned.

StringBitPosition(
    key: RedisKey,  // The key of the string.
    bit: bool,  // True to check for the first 1 bit, false to check for the first 0 bit.
    start: long,  // The position to start looking (defaults to 0).
    end: long,  // The position to stop looking (defaults to -1, unlimited).
    indexType: StringIndexType,  // In Redis 7+, we can choose if start and end specify a bit index or byte index (defaults to Byte).
    flags: CommandFlags  // The flags to use for this operation.
) → long  // The command returns the position of the first bit set to 1 or 0 according to the request. If we look for set bits(the bit argument is 1) and the string is empty or composed of just zero bytes, -1 is returned.

StringBitPosition(
    key: RedisKey,  // The key of the string.
    bit: bool,  // True to check for the first 1 bit, false to check for the first 0 bit.
    start: long,  // The position to start looking (defaults to 0).
    end: long,  // The position to stop looking (defaults to -1, unlimited).
    flags: CommandFlags  // The flags to use for this operation.
) → long  // The command returns the position of the first bit set to 1 or 0 according to the request. If we look for set bits(the bit argument is 1) and the string is empty or composed of just zero bytes, -1 is returned.

bitpos(
    $key: string,
    $bit: Any,
    $start = null: Any,
    $end = null: Any,
    string $index = 'byte': Any
) → int

Available since:: Redis Open Source 2.8.7
Time complexity:: O(N)
ACL categories:: @read, @bitmap, @slow,
Compatibility:: Redis Software and Redis Cloud compatibility

Return the position of the first bit set to 1 or 0 in a string.

The position is returned, thinking of the string as an array of bits from left to right, where the first byte's most significant bit is at position 0, the second byte's most significant bit is at position 8, and so forth.

The same bit position convention is followed by GETBIT and SETBIT.

By default, all the bytes contained in the string are examined. It is possible to look for bits only in a specified interval passing the additional arguments start and end (it is possible to just pass start, the operation will assume that the end is the last byte of the string. However there are semantic differences as explained later). By default, the range is interpreted as a range of bytes and not a range of bits, so start=0 and end=2 means to look at the first three bytes.

You can use the optional BIT modifier to specify that the range should be interpreted as a range of bits. So start=0 and end=2 means to look at the first three bits.

Note that bit positions are returned always as absolute values starting from bit zero even when start and end are used to specify a range.

Like for the GETRANGE command start and end can contain negative values in order to index bytes starting from the end of the string, where -1 is the last byte, -2 is the penultimate, and so forth. When BIT is specified, -1 is the last bit, -2 is the penultimate, and so forth.

Non-existent keys are treated as empty strings.

Examples

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 and Redis Cloud compatibility

Redis Software	Redis Cloud	Notes
✅ Standard ✅ Active-Active	✅ Standard ✅ Active-Active

Return information

RESP2 RESP3

One of the following:

Integer reply: the position of the first bit set to 1 or 0 according to the request
Integer reply: -1. In case the bit argument is 1 and the string is empty or composed of just zero bytes If we look for set bits (the bit argument is 1) and the string is empty or composed of just zero bytes, -1 is returned. If we look for clear bits (the bit argument is 0) and the string only contains bits set to 1, the function returns the first bit not part of the string on the right. So if the string is three bytes set to the value 0xff the command BITPOS key 0 will return 24, since up to bit 23 all the bits are 1. The function considers the right of the string as padded with zeros if you look for clear bits and specify no range or the start argument only. However, this behavior changes if you are looking for clear bits and specify a range with both start and end. If a clear bit isn't found in the specified range, the function returns -1 as the user specified a clear range and there are no 0 bits in that range.

One of the following:

Integer reply: the position of the first bit set to 1 or 0 according to the request
Integer reply: -1. In case the bit argument is 1 and the string is empty or composed of just zero bytes If we look for set bits (the bit argument is 1) and the string is empty or composed of just zero bytes, -1 is returned. If we look for clear bits (the bit argument is 0) and the string only contains bits set to 1, the function returns the first bit not part of the string on the right. So if the string is three bytes set to the value 0xff the command BITPOS key 0 will return 24, since up to bit 23 all the bits are 1. The function considers the right of the string as padded with zeros if you look for clear bits and specify no range or the start argument only. However, this behavior changes if you are looking for clear bits and specify a range with both start and end. If a clear bit isn't found in the specified range, the function returns -1 as the user specified a clear range and there are no 0 bits in that range.

History

Starting with Redis version 7.0.0: Added the BYTE|BIT option.

Products

Tools

Get Redis

Connect

Learn

Latest

See how it works

BITPOS

Examples

Redis Software and Redis Cloud compatibility

Return information

History