diff options
Diffstat (limited to 'iredis/data/commands/srandmember.md')
| -rw-r--r-- | iredis/data/commands/srandmember.md | 51 |
1 files changed, 28 insertions, 23 deletions
diff --git a/iredis/data/commands/srandmember.md b/iredis/data/commands/srandmember.md index 99f9b7e..640ccdc 100644 --- a/iredis/data/commands/srandmember.md +++ b/iredis/data/commands/srandmember.md @@ -1,22 +1,21 @@ When called with just the `key` argument, return a random element from the set value stored at `key`. -Starting from Redis version 2.6, when called with the additional `count` -argument, return an array of `count` **distinct elements** if `count` is -positive. If called with a negative `count` the behavior changes and the command -is allowed to return the **same element multiple times**. In this case the -number of returned elements is the absolute value of the specified `count`. +If the provided `count` argument is positive, return an array of **distinct +elements**. The array's length is either `count` or the set's cardinality +(`SCARD`), whichever is lower. -When called with just the key argument, the operation is similar to `SPOP`, -however while `SPOP` also removes the randomly selected element from the set, -`SRANDMEMBER` will just return a random element without altering the original -set in any way. +If called with a negative `count`, the behavior changes and the command is +allowed to return the **same element multiple times**. In this case, the number +of returned elements is the absolute value of the specified `count`. @return -@bulk-string-reply: without the additional `count` argument the command returns +@bulk-string-reply: without the additional `count` argument, the command returns a Bulk Reply with the randomly selected element, or `nil` when `key` does not -exist. @array-reply: when the additional `count` argument is passed the command +exist. + +@array-reply: when the additional `count` argument is passed, the command returns an array of elements, or an empty array when `key` does not exist. @examples @@ -28,26 +27,32 @@ SRANDMEMBER myset 2 SRANDMEMBER myset -5 ``` +@history + +- `>= 2.6.0`: Added the optional `count` argument. + ## Specification of the behavior when count is passed -When a count argument is passed and is positive, the elements are returned as if -every selected element is removed from the set (like the extraction of numbers -in the game of Bingo). However elements are **not removed** from the Set. So -basically: +When the `count` argument is a positive value this command behaves as follows: - No repeated elements are returned. -- If count is bigger than the number of elements inside the Set, the command - will only return the whole set without additional elements. +- If `count` is bigger than the set's cardinality, the command will only return + the whole set without additional elements. +- The order of elements in the reply is not truly random, so it is up to the + client to shuffle them if needed. -When instead the count is negative, the behavior changes and the extraction -happens as if you put the extracted element inside the bag again after every -extraction, so repeated elements are possible, and the number of elements -requested is always returned as we can repeat the same elements again and again, -with the exception of an empty Set (non existing key) that will always produce -an empty array as a result. +When the `count` is a negative value, the behavior changes as follows: + +- Repeating elements are possible. +- Exactly `count` elements, or an empty array if the set is empty (non-existing + key), are always returned. +- The order of elements in the reply is truly random. ## Distribution of returned elements +Note: this section is relevant only for Redis 5 or below, as Redis 6 implements +a fairer algorithm. + The distribution of the returned elements is far from perfect when the number of elements in the set is small, this is due to the fact that we used an approximated random element function that does not really guarantees good |