DOC-5718: add new string commands

content/commands/delex.md

@@ -0,0 +1,106 @@
+---
+acl_categories:
+- '@write'
+- '@string'
+- '@fast'
+arguments:
+- display_text: key
+  key_spec_index: 0
+  name: key
+  type: key
+- arguments:
+  - display_text: ifeq-value
+    name: ifeq-value
+    token: IFEQ
+    type: string
+  - display_text: ifne-value
+    name: ifne-value
+    token: IFNE
+    type: string
+  - display_text: ifdeq-digest
+    name: ifdeq-digest
+    token: IFDEQ
+    type: integer
+  - display_text: ifdne-digest
+    name: ifdne-digest
+    token: IFDNE
+    type: integer
+  name: condition
+  optional: true
+  type: oneof
+arity: -2
+categories:
+- docs
+- develop
+- stack
+- oss
+- rs
+- rc
+- oss
+- kubernetes
+- clients
+command_flags:
+- write
+- fast
+complexity: O(1) for IFEQ/IFNE, O(N) for IFDEQ/IFDNE where N is the length of the string value.
+description: Conditionally removes the specified key based on value or hash digest comparison.
+group: string
+hidden: false
+key_specs:
+- RW: true
+  begin_search:
+    spec:
+      index: 1
+    type: index
+  delete: true
+  find_keys:
+    spec:
+      keystep: 1
+      lastkey: 0
+      limit: 0
+    type: range
+linkTitle: DELEX
+since: 8.4.0
+summary: Conditionally removes the specified key based on value or hash digest comparison.
+syntax_fmt: "DELEX key [IFEQ\_ifeq-value | IFNE\_ifne-value | IFDEQ\_ifdeq-digest\
+  \ |\n  IFDNE\_ifdne-digest]"
+syntax_str: "[IFEQ\_ifeq-value | IFNE\_ifne-value | IFDEQ\_ifdeq-digest | IFDNE\_\
+  ifdne-digest]"
+title: DELEX
+---
+
+Conditionally removes the specified key based on value or hash digest comparison.
+
+## Hash Digest
+
+A hash digest is a fixed-size numerical representation of a string value, computed using the XXH3 hash algorithm. Redis uses this hash digest for efficient comparison operations without needing to compare the full string content. You can retrieve a key's hash digest using the [`DIGEST`]({{< relref "/commands/digest" >}}) command, which returns it as a hexadecimal string that you can use with the `IFDEQ` and `IFDNE` options, and also the [`SET`]({{< relref "/commands/set" >}}) command's `IFDEQ` and `IFDNE` options.
+
+## Options
+
+The DELEX command supports a set of options that modify its behavior.
+Only one of the options can be specified.
+
+* `IFEQ ifeq-value` -- Remove the key if the value is equal to the specified value.
+* `IFNE ifne-value` -- Remove the key if the value is not equal to the specified value.
+* `IFDEQ ifeq-digest` -- Remove the key if its hash digest is equal to the specified hash digest.
+* `IFDNE ifne-digest` -- Remove the key if its hash digest is not equal to the specified hash digest.
+
+In 8.4, keys must be of type string when using one of the options above. If no options are specified, the key is removed regardless of its type.
+
+## Return information
+
+{{< multitabs id="return-info"
+    tab1="RESP2"
+    tab2="RESP3" >}}
+
+One of the following:
+- [Integer reply]({{< relref "/develop/reference/protocol-spec#integers" >}}): 0 if not deleted (the key does not exist or a specified `IFEQ/IFNE/IFDEQ/IFDNE` condition is false), or 1 if deleted.
+- [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}) if the key exists but holds a value that is not a string and one of `IFEQ, IFNE, IFDEQ,` or `IFDNE` is specified.
+
+-tab-sep-
+
+One of the following:
+- [Integer reply]({{< relref "/develop/reference/protocol-spec#integers" >}}): 0 if not deleted (the key does not exist or a specified `IFEQ/IFNE/IFDEQ/IFDNE` condition is false), or 1 if deleted.
+- [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}) if the key exists but holds a value that is not a string and one of `IFEQ, IFNE, IFDEQ,` or `IFDNE` is specified.
+
+{{< /multitabs >}}

content/commands/digest.md

@@ -0,0 +1,76 @@
+---
+acl_categories:
+- '@read'
+- '@string'
+- '@fast'
+arguments:
+- display_text: key
+  key_spec_index: 0
+  name: key
+  type: key
+arity: 2
+categories:
+- docs
+- develop
+- stack
+- oss
+- rs
+- rc
+- oss
+- kubernetes
+- clients
+command_flags:
+- readonly
+- fast
+complexity: O(N) where N is the length of the string value.
+description: Returns the hash digest of a string value.
+group: string
+hidden: false
+key_specs:
+- RO: true
+  access: true
+  begin_search:
+    spec:
+      index: 1
+    type: index
+  find_keys:
+    spec:
+      keystep: 1
+      lastkey: 0
+      limit: 0
+    type: range
+linkTitle: DIGEST
+since: 8.4.0
+summary: Returns the hash digest of a string value as a hexadecimal string.
+syntax_fmt: DIGEST key
+syntax_str: ''
+title: DIGEST
+---
+
+Get the hash digest for the value stored in the specified key as a hexadecimal string. Keys must be of type string.
+
+## Hash Digest
+
+A hash digest is a fixed-size numerical representation of a string value, computed using the XXH3 hash algorithm. Redis uses this hash digest for efficient comparison operations without needing to compare the full string content. You can use these hash digests with the [SET]({{< relref "/commands/set" >}}) command's `IFDEQ` and `IFDNE` options, and also the [DELEX]({{< relref "/commands/delex" >}}) command's `IFDEQ` and `IFDNE` options.
+
+## Return information
+
+{{< multitabs id="return-info"
+    tab1="RESP2"
+    tab2="RESP3" >}}
+
+One of the following:
+
+- [Null bulk string reply]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) if the key does not exist.
+- [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}) if the key exists but holds a value which is not a string.
+- [Bulk string reply]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) the hash digest of the value stored in the key as a hexadecimal string.
+
+-tab-sep-
+
+One of the following:
+
+- [Null bulk string reply]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) if the key does not exist.
+- [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}) if the key exists but holds a value which is not a string.
+- [Bulk string reply]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) the hash digest of the value stored in the key as a hexadecimal string.
+
+{{< /multitabs >}}

content/commands/set.md

@@ -20,6 +20,26 @@ arguments:
     name: xx
     token: XX
     type: pure-token
+  - display_text: ifeq-value
+    name: ifeq-value
+    since: 8.4.0
+    token: IFEQ
+    type: string
+  - display_text: ifne-value
+    name: ifne-value
+    since: 8.4.0
+    token: IFNE
+    type: string
+  - display_text: ifdeq-digest
+    name: ifdeq-digest
+    since: 8.4.0
+    token: IFDEQ
+    type: integer
+  - display_text: ifdne-digest
+    name: ifdne-digest
+    since: 8.4.0
+    token: IFDNE
+    type: integer
   name: condition
   optional: true
   since: 2.6.12
@@ -87,6 +107,8 @@ history:
   - Added the `GET`, `EXAT` and `PXAT` option.
 - - 7.0.0
   - Allowed the `NX` and `GET` options to be used together.
+- - 8.4.0
+  - Added 'IFEQ', 'IFNE', 'IFDEQ', 'IFDNE' options.
 key_specs:
 - RW: true
   access: true
@@ -107,12 +129,15 @@ linkTitle: SET
 since: 1.0.0
 summary: Sets the string value of a key, ignoring its type. The key is created if
   it doesn't exist.
-syntax_fmt: "SET key value [NX | XX] [GET] [EX\_seconds | PX\_milliseconds |\n  EXAT\_\
-  unix-time-seconds | PXAT\_unix-time-milliseconds | KEEPTTL]"
-syntax_str: "value [NX | XX] [GET] [EX\_seconds | PX\_milliseconds | EXAT\_unix-time-seconds\
+syntax_fmt: "SET key value [NX | XX | IFEQ\_ifeq-value | IFNE\_ifne-value |\n\
+  \  IFDEQ\_ifdeq-digest | IFDNE\_ifdne-digest] [GET] [EX\_seconds |\n  PX\_milliseconds\
+  \ | EXAT\_unix-time-seconds |\n  PXAT\_unix-time-milliseconds | KEEPTTL]"
+syntax_str: "value [NX | XX | IFEQ\_ifeq-value | IFNE\_ifne-value | IFDEQ\_ifdeq-digest\
+  \ | IFDNE\_ifdne-digest] [GET] [EX\_seconds | PX\_milliseconds | EXAT\_unix-time-seconds\
   \ | PXAT\_unix-time-milliseconds | KEEPTTL]"
 title: SET
 ---
+
 Set `key` to hold the string `value`.
 If `key` already holds a value, it is overwritten, regardless of its type.
 Any previous time to live associated with the key is discarded on successful `SET` operation.
@@ -121,17 +146,25 @@ Any previous time to live associated with the key is discarded on successful `SE
 
 The `SET` command supports a set of options that modify its behavior:
 
+* `NX` -- Only set the key if it does not already exist.
+* `XX` -- Only set the key if it already exists.
+* `IFEQ ifeq-value` -- Set the key’s value and expiration only if its current value is equal to `ifeq-value`. If the key doesn’t exist, it won’t be created.
+* `IFNE ifne-value` -- Set the key’s value and expiration only if its current value is not equal to `ifne-value`. If the key doesn’t exist, it will be created.
+* `IFDEQ ifeq-digest` -- Set the key’s value and expiration only if the hash digest of its current value is equal to `ifeq-digest`. If the key doesn’t exist, it won’t be created. See the [Hash Digest](#hash-digest) section below for more information.
+* `IFDNE ifne-digest` -- Set the key’s value and expiration only if the hash digest of its current value is not equal to `ifne-digest`. If the key doesn’t exist, it will be created. See the [Hash Digest](#hash-digest) section below for more information.
+* `GET` -- Return the old string stored at key, or nil if key did not exist. An error is returned and `SET` aborted if the value stored at key is not a string.
 * `EX` *seconds* -- Set the specified expire time, in seconds (a positive integer).
 * `PX` *milliseconds* -- Set the specified expire time, in milliseconds (a positive integer).
 * `EXAT` *timestamp-seconds* -- Set the specified Unix time at which the key will expire, in seconds (a positive integer).
 * `PXAT` *timestamp-milliseconds* -- Set the specified Unix time at which the key will expire, in milliseconds (a positive integer).
-* `NX` -- Only set the key if it does not already exist.
-* `XX` -- Only set the key if it already exists.
 * `KEEPTTL` -- Retain the time to live associated with the key.
-* `GET` -- Return the old string stored at key, or nil if key did not exist. An error is returned and `SET` aborted if the value stored at key is not a string.
 
 Note: Since the `SET` command options can replace [`SETNX`]({{< relref "/commands/setnx" >}}), [`SETEX`]({{< relref "/commands/setex" >}}), [`PSETEX`]({{< relref "/commands/psetex" >}}), [`GETSET`]({{< relref "/commands/getset" >}}), it is possible that in future versions of Redis these commands will be deprecated and finally removed.
 
+## Hash Digest
+
+A hash digest is a fixed-size numerical representation of a string value, computed using the XXH3 hash algorithm. Redis uses this hash digest for efficient comparison operations without needing to compare the full string content. You can retrieve a key's hash digest using the [`DIGEST`]({{< relref "/commands/digest" >}}) command, which returns it as a hexadecimal string that you can use with the `IFDEQ` and `IFDNE` options, and also the [`DELEX`]({{< relref "/commands/delex" >}}) command's `IFDEQ` and `IFDNE` options.
+
 ## Examples
 
 {{% redis-cli %}}
@@ -180,20 +213,24 @@ The script should be called with `EVAL ...script... 1 resource-name token-value`
     tab1="RESP2" 
     tab2="RESP3" >}}
 
-* If `GET` was not specified, any of the following:
-  * [Nil reply](../../develop/reference/protocol-spec#bulk-strings): Operation was aborted (conflict with one of the `XX`/`NX` options). The key was not set.
+* If `GET` was not specified, one of the following:
+  * [Null bulk string reply](../../develop/reference/protocol-spec#bulk-strings) in the following two cases.
+    * The key doesn’t exist and `XX/IFEQ/IFDEQ` was specified. The key was not created.
+    * The key exists, and `NX` was specified or a specified `IFEQ/IFNE/IFDEQ/IFDNE` condition is false. The key was not set.
   * [Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK`: The key was set.
-* If `GET` was specified, any of the following:
-  * [Nil reply](../../develop/reference/protocol-spec#bulk-strings): The key didn't exist before the `SET`. If `XX` was specified, the key was not set. Otherwise, the key was set.
-  * [Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): The previous value of the key. If `NX` was specified, the key was not set. Otherwise, the key was set.
+* If `GET` was specified, one of the following:
+  * [Null bulk string reply](../../develop/reference/protocol-spec#bulk-strings): The key didn't exist before the `SET` operation, whether the key was created of not.
+  * [Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): The previous value of the key, whether the key was set or not.
 
 -tab-sep-
 
-* If `GET` was not specified, any of the following:
-  * [Null reply](../../develop/reference/protocol-spec#nulls): Operation was aborted (conflict with one of the `XX`/`NX` options). The key was not set.
+* If `GET` was not specified, one of the following:
+  * [Null reply](../../develop/reference/protocol-spec#nulls) in the following two cases.
+    * The key doesn’t exist and `XX/IFEQ/IFDEQ` was specified. The key was not created.
+    * The key exists, and `NX` was specified or a specified `IFEQ/IFNE/IFDEQ/IFDNE` condition is false. The key was not set.
   * [Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK`: The key was set.
-* If `GET` was specified, any of the following:
-  * [Null reply](../../develop/reference/protocol-spec#nulls): The key didn't exist before the `SET`. If `XX` was specified, the key was not set. Otherwise, the key was set.
-  * [Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): The previous value of the key. If `NX` was specified, the key was not set. Otherwise, the key was set.
+* If `GET` was specified, one of the following:
+  * [Null reply](../../develop/reference/protocol-spec#nulls): The key didn't exist before the `SET` operation, whether the key was created of not.
+  * [Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): The previous value of the key, whether the key was set or not.
 
 {{< /multitabs >}}