bitfield
BITFIELD
Numeric operations on a BIT array
A data structure that stores and operates on numbers as a bit array to save memory.
For example, if you need to store many numbers in the 0-15 range, using a 4-bit integer instead of the usual
4 bytes (32 bits) integer can save a lot of memory.
- Set: bitfield key SET type offset value -> bitfield key SET u4 0 1
- Get: bitfield key GET type offset -> GET u4 0
- Increment / decrement: bitfield key INCRBY type offset increment -> INCRBY u4 0 1
- type: Numeric data type. Signed number i, unsigned number u,
and the number of bits used to represent the value
Unsigned 4-bit number: u4, unsigned 8-bit number: u8
Signed 4-bit number: i4, signed 8-bit number: i8
- offset: Bit position. For u4: 0, 4, 8, ...
- value: Value. Only integers are allowed.
SET
Example
| Command> | bitfield key set u4 0 2 Store 2 in the first 4 bits
|
| Result> | 1) (integer) 0 The previous value is returned.
|
| Command> | bitfield key set u4 4 4 Store 4 in the second 4 bits
|
| Result> | 1) (integer) 0
|
| Command> | bitfield key set u4 8 6 Store 6 in the third 4 bits
|
| Result> | 1) (integer) 0
|
GET
Example
| Command> | bitfield key get u4 0 Get the first 4-bit value
|
| Result> | 1) (integer) 2
|
| Command> | bitfield key get u4 4
|
| Result> | 1) (integer) 4
|
| Command> | bitfield key get u4 8
|
| Result> | 1) (integer) 6
|
INCRBY increment / decrement
Example
| Command> | bitfield key incrby u4 0 1 Increment the first 4-bit value by 1
|
| Result> | 1) (integer) 3 Shows the result value.
|
| Command> | bitfield key incrby u4 0 2
|
| Result> | 1) (integer) 5
|
| Command> | bitfield key incrby u4 0 -3 Negative values are allowed
|
| Result> | 1) (integer) 2
|
offset #: specify by item
You can use '#' to specify offset by item instead of bit position.
For u4 or i4: first 4 bits: #0, second 4 bits: #1, third 4 bits: #2, and so on
For u8 or i8: first 8 bits: #0, second 8 bits: #1, third 8 bits: #2, and so on
You do not need to calculate the bit count.
Example
| Command> | bitfield key set u4 #0 2
|
| Result> | 1) (integer) 0
|
| Command> | bitfield key get u4 #0
|
| Result> | 1) (integer) 2
|
| Command> | bitfield key set u4 #0 2
|
| Result> | 1) (integer) 4
|
Options (SET, GET, INCRBY) can be used more than once
Example
| Command> | bitfield key set u4 #0 1 set u4 #1 2
|
| Result> | 1) (integer) 0
2) (integer) 0
|
| Command> | bitfield key set u4 #3 1 get u4 #1
|
| Result> | 1) (integer) 0
2) (integer) 2
|
| Command> | bitfield key incrby u4 #3 2 set u4 #4 5
|
| Result> | 1) (integer) 3
2) (integer) 0
|
Specify overflow / underflow handling
Specifies how to handle the value when it exceeds the maximum
or goes below the minimum.
- WRAP: Adding 1 to u4 15 becomes 0. Adding 1 to i4 7 becomes -8. This is the default.
- SAT: Adding 10 to u4 10 becomes 15. Adding 5 to i4 5 becomes 7.
It stops at the maximum or minimum.
- FAIL: Adding 10 to u4 10 returns (nil). Adding 5 to i4 5 returns (nil).
- Command position (order): Affects only the incrby after OVERFLOW.
WRAP
Example
| Command> | bitfield key set u4 #0 15
|
| Command> | bitfield key overflow wrap incrby u4 #0 1
|
| Result> | 1) (integer) 0 |
| Command> | bitfield key set i4 #0 7
|
| Command> | bitfield key overflow wrap incrby i4 #0 1
|
| Result> | 1) (integer) -8 |
SAT
Example
| Command> | bitfield key set u4 #0 10
|
| Command> | bitfield key overflow sat incrby u4 #0 10
|
| Result> | 1) (integer) 15 |
| Command> | bitfield key set i4 #0 5
|
| Command> | bitfield key overflow sat incrby i4 #0 5
|
| Result> | 1) (integer) 7 |
FAIL
Example
| Command> | bitfield key set u4 #0 10
|
| Command> | bitfield key overflow fail incrby u4 #0 10
|
| Result> | 1) (nil) |
| Command> | bitfield key set i4 #0 5
|
| Command> | bitfield key overflow fail incrby i4 #0 5
|
| Result> | 1) (nil) |
Syntax
BITFIELD key [GET type offset] [SET type offset value]
[OVERFLOW WRAP|SAT|FAIL] [INCRBY type offset increment]
- Available since version 3.2.0.
- Time complexity is O(1).
Commands
Apply for Redis Developer Course
Redis Regular Inspection / Technical Support
Redis Enterprise Server
