Skip to content

Commit

Permalink
#1017 Migrate Commands: ('SETBIT', 'GETBIT', 'BITCOUNT', 'BITPOS', 'B…
Browse files Browse the repository at this point in the history 
…ITFIELD', 'BITFIELD_RO') (#1089)
  • Loading branch information
@vishnuchandrashekar
vishnuchandrashekar authored Nov 9, 2024
1 parent 60c59df commit 44779c2
Show file tree
Hide file tree
Showing 19 changed files with 4,507 additions and 1,439 deletions.
157 changes: 157 additions & 0 deletions docs/src/content/docs/commands/BITFIELD.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,157 @@
---
title: BITFIELD
description: The BITFIELD command in DiceDB performs complex bitwise operations on string values at specified offsets, treating them as an array of integers. It allows manipulation of individual bits or groups of bits, supporting commands like SET, GET, and INCRBY to update or retrieve bitfield values.
---

## Syntax

```bash
BITFIELD key [GET type offset | [OVERFLOW <WRAP | SAT | FAIL>]
<SET type offset value | INCRBY type offset increment>
[GET type offset | [OVERFLOW <WRAP | SAT | FAIL>]
<SET type offset value | INCRBY type offset increment>
...]]
```
## Parameters
| Parameter | Description |Type |Required|
|--------------------|----------------------------------------------------------------------------------------------------------------------------|------|--------|
| `key` | The name of the key containing the bitfield. |String|Yes |
| `GET type offset` | Retrieves bits starting at the specified offset with the specified type. Type defines the signed/unsigned integer format. |String|Optional|
| `SET type offset value`| Sets bits at the specified offset to the given value using the specified integer type. |String|Optional|
| `INCRBY type offset increment`| Increments bits at the specified offset by the increment value and wraps around on overflow based on type. |String|Optional|
| `OVERFLOW WRAP\|SAT\|FAIL` | Defines overflow behavior. |String|Optional|
## Return values
| Condition | Return Value |
|----------------------------------------------------------------|-------------------------------------------------------|
| Command is successful | Array of results corresponding to each subcommand |
| Syntax or specified constraints are invalid | error |
## Behaviour
The BITFIELD command in DiceDB allows for direct bitwise manipulation within a binary string stored in a single key. It works by treating the string as an array of integers and performs operations on specific bits or groups of bits at specified offsets:
- SET: Sets the value of bits at a specific offset.
- GET: Retrieves the value of bits at a specific offset.
- INCRBY: Increments the value at a specific offset by a given amount, useful for counters.
- OVERFLOW: Defines the overflow behavior (WRAP, SAT, FAIL) for INCRBY, determining how to handle values that exceed the bitfield’s limits.
#### Overflow Options:
- WRAP: Cycles values back to zero on overflow (default behavior).
- SAT: Saturates to the maximum or minimum value for the bit width.
- FAIL: Prevents overflow by causing INCRBY to fail if it would exceed the limits.
<br>
<br>
- Supports unsigned (u) with bit widths between 1 and 63 and signed (i) integers with bit widths between 1 and 64.
- The offset specifies where the bitfield starts within the key’s binary string.
- If an offset is out of range (far beyond the current size), DiceDB will automatically expand the binary string to accommodate it, which can impact memory usage.
## Errors
1. `Syntax Error`:
- Error Message: `(error) ERR syntax error`
- Occurs if the commands syntax is incorrect.
2. `Invalid bitfield type`:
- Error Message: `(error) ERR Invalid bitfield type. Use something like i16 u8. Note that u64 is not supported but i64 is`
- Occurs when attempting to use the command on a wrong type.
3. `Non-integer value`:
- Error Message: `(error) ERR value is not an integer or out of range`
- Occurs when attempting to use the command on a value that contains a non-integer value.
4. `Invalid OVERLOW type`:
- Error Message: `(error) ERR Invalid OVERFLOW type specified`
- Occurs when attempting to use a wrong OVERFLOW type.
5. `Wrong type of value or key`:
- Error Message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value`
- Occurs when attempting to use the command on a key that contains a non-string value.
6. `Invalid bIT offset`:
- Error Message: `(error) ERR bit offset is not an integer or out of range`
- Occurs when attempting to use the command with an invalid bit offset.
## Example Usage
### Basic Usage:
```bash
127.0.0.1:7379> BITFIELD mykey INCRBY i5 100 1 GET u4 0
1) "1"
2) "0"
```
### Overflow control:
```bash
127.0.0.1:7379> BITFIELD mykey incrby u2 100 1 OVERFLOW SAT incrby u2 102 1
1) "1"
2) "1"
127.0.0.1:7379> BITFIELD mykey incrby u2 100 1 OVERFLOW SAT incrby u2 102 1
1) "2"
2) "2"
127.0.0.1:7379> BITFIELD mykey incrby u2 100 1 OVERFLOW SAT incrby u2 102 1
1) "3"
2) "3"
127.0.0.1:7379> BITFIELD mykey incrby u2 100 1 OVERFLOW SAT incrby u2 102 1
1) "0"
2) "3"
```
### Example of OVERFLOW FAIL returning nil:
```bash
127.0.0.1:7379> BITFIELD mykey OVERFLOW FAIL incrby u2 102 1
(nil)
```
### Invalid usage:
```bash
127.0.0.1:7379> BITFIELD
(error) ERR wrong number of arguments for 'bitfield' command
```
```bash
127.0.0.1:7379> SADD bits a b c
(integer) 3
127.0.0.1:7379> BITFIELD bits
(error) ERR WRONGTYPE Operation against a key holding the wrong kind of value
```
```bash
127.0.0.1:7379> BITFIELD bits SET u8 0 255 INCRBY u8 0 100 GET u8
(error) ERR syntax error
```
```bash
127.0.0.1:7379> bitfield bits set a8 0 255 incrby u8 0 100 get u8
(error) ERR Invalid bitfield type. Use something like i16 u8. Note that u64 is not supported but i64 is
```
```bash
127.0.0.1:7379> bitfield bits set u8 a 255 incrby u8 0 100 get u8
(error) ERR bit offset is not an integer or out of range
```
```bash
127.0.0.1:7379> bitfield bits set u8 0 255 incrby u8 0 100 overflow wraap
(error) ERR Invalid OVERFLOW type specified
```
```bash
127.0.0.1:7379> bitfield bits set u8 0 incrby u8 0 100 get u8 288
(error) ERR value is not an integer or out of range
```
## Notes
Where an integer encoding is expected, it can be composed by prefixing with i for signed integers and u for unsigned integers with the number of bits of our integer encoding. So for example u8 is an unsigned integer of 8 bits and i16 is a signed integer of 16 bits.
The supported encodings are up to 64 bits for signed integers, and up to 63 bits for unsigned integers. This limitation with unsigned integers is due to the fact that currently RESP is unable to return 64 bit unsigned integers as replies.
## Subcommands
- **subcommand**: Optional. Available subcommands include:
- `GET` `<type>` `<offset>` : Returns the specified bit field.
- `SET` `<type>` `<offset>` `<value>` : Set the specified bit field and - returns its old value.
- `INCRBY` `<type>` `<offset>` `<increment>` : Increments or decrements (if a negative increment is given) the specified bit field and returns the new value.
- `OVERFLOW` [ `WRAP` | `SAT` | `FAIL` ]
41 changes: 41 additions & 0 deletions docs/src/content/docs/commands/BITFIELD_RO.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
---
title: BITFIELD_RO
description: Read-only variant of the BITFIELD command. It is like the original BITFIELD but only accepts GET subcommand.
---

## Syntax

```bash
BITFIELD_RO key [GET type offset [GET type offset ...]]
```
## Parameters
| Parameter | Description |Type |Required|
|-----------|-------------------------------------------------------------------------------------------------------------------------------------|------|--------|
| `key` | The name of the key containing the bitfield. |String|Yes |
| `GET type offset` | Retrieves bits starting at the specified offset with the specified type. Type defines the signed/unsigned integer format. |String|Optional|
## Return values
| Condition | Return Value |
|----------------------------------------------------------------|-------------------------------------------------------|
| Command is successful | Array of results corresponding to each `GET` command |
| Syntax or specified constraints are invalid | error |
## Behaviour
- Read-only variant of the BITFIELD command. It is like the original BITFIELD but only accepts GET subcommand.
- See original BITFIELD for more details.
## Example Usage
### Basic Usage
```bash
127.0.0.1:7379> SET hello "Hello World"
OK
127.0.0.1:7379> BITFIELD_RO hello GET i8 16
1) "108"
```
60 changes: 38 additions & 22 deletions docs/src/content/docs/commands/BITOP.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,15 @@ BITOP operation destkey key [key ...]
```

## Parameters
| Parameter | Description | Type | Required |
|-------------------|--------------------------------------------------------------------------------|--------------|----------|
| `AND` | Perform a bitwise AND operation. | Operation | Yes |
| `OR` | Perform a bitwise OR operation. | Operation | Yes |
| `XOR` | Perform a bitwise XOR operation. | Operation | Yes |
| `NOT` | Perform a bitwise NOT operation (only one key is allowed for this operation). | Operation | Yes |
| `destkey` | The key where the result of the bitwise operation will be stored. | String | Yes |
| `key [key ...]` | One or more keys containing the strings to be used in the bitwise operation. For the `NOT` operation, only one key is allowed.| String | Yes |

- `operation`: The bitwise operation to perform. It can be one of the following:
- `AND`: Perform a bitwise AND operation.
- `OR`: Perform a bitwise OR operation.
- `XOR`: Perform a bitwise XOR operation.
- `NOT`: Perform a bitwise NOT operation (only one key is allowed for this operation).
- `destkey`: The key where the result of the bitwise operation will be stored.
- `key [key ...]`: One or more keys containing the strings to be used in the bitwise operation. For the `NOT` operation, only one key is allowed.

## Return Value

Expand Down Expand Up @@ -61,10 +62,14 @@ The `BITOP` command can raise errors in the following cases:
### Example 1: Bitwise AND Operation

```bash
SET key1 "foo"
SET key2 "bar"
BITOP AND result key1 key2
GET result
127.0.0.1:7379> SET key1 "foo"
OK
127.0.0.1:7379> SET key2 "bar"
OK
127.0.0.1:7379> BITOP AND result key1 key2
(integer) 3
127.0.0.1:7379> GET result
"bab"
```

`Explanation`:
Expand All @@ -77,10 +82,14 @@ GET result
### Example 2: Bitwise OR Operation

```bash
SET key1 "foo"
SET key2 "bar"
BITOP OR result key1 key2
GET result
127.0.0.1:7379> SET key1 "foo"
OK
127.0.0.1:7379> SET key2 "bar"
OK
127.0.0.1:7379> BITOP OR result key1 key2
(integer) 3
127.0.0.1:7379> GET result
"fo\x7f"
```

`Explanation`:
Expand All @@ -93,10 +102,14 @@ GET result
### Example 3: Bitwise XOR Operation

```bash
SET key1 "foo"
SET key2 "bar"
BITOP XOR result key1 key2
GET result
127.0.0.1:7379> SET key1 "foo"
OK
127.0.0.1:7379> SET key2 "bar"
OK
127.0.0.1:7379> BITOP XOR result key1 key2
(integer) 3
127.0.0.1:7379> GET result
"\x04\x0e\x1d"
```

`Explanation`:
Expand All @@ -109,9 +122,12 @@ GET result
### Example 4: Bitwise NOT Operation

```bash
SET key1 "foo"
BITOP NOT result key1
GET result
127.0.0.1:7379> SET key1 "foo"
OK
127.0.0.1:7379> BITOP NOT result key1
(integer) 3
127.0.0.1:7379> GET result
"\x99\x90\x90"
```

`Explanation`:
Expand Down
Loading

0 comments on commit 44779c2

Please sign in to comment.