Documentation: SSCAN docblock and example

[skip ci]

3 files changed, 63 insertions, 2 deletions

diff --git a/redis.stub.php b/redis.stub.php
index 69fda01c..64faa3bc 100644
--- a/redis.stub.php
+++ b/redis.stub.php
@@ -1893,6 +1893,67 @@ class Redis {
      */
     public function srem(string $key, mixed $value, mixed ...$other_values): Redis|int|false;
 
+    /**
+     * Scan the members of a redis SET key.
+     *
+     * @see https://redis.io/commands/sscan
+     * @see https://redis.io/commands/scan
+     * @see Redis::setOption()
+     *
+     * @param string $key       The Redis SET key in question.
+     * @param int    $iterator  A reference to an iterator which should be initialized to NULL that
+     *                          PhpRedis will update with the value returned from Redis after each
+     *                          subsequent call to SSCAN.  Once this cursor is zero you know all
+     *                          members have been traversed.
+     * @param string $pattern   An optional glob style pattern to match against, so Redis only
+     *                          returns the subset of members matching this pattern.
+     * @param int    $count     A hint to Redis as to how many members it should scan in one command
+     *                          before returning members for that iteration.
+     *
+     * <code>
+     * $redis = new Redis(['host' => 'localhost']);
+     *
+     * $redis->del('myset');
+     * for ($i = 0; $i < 10000; $i++) {
+     *     $redis->sAdd('myset', "member:$i");
+     * }
+     * $redis->sadd('myset', 'foofoo');
+     *
+     * $redis->setOption(Redis::OPT_SCAN, Redis::SCAN_NORETRY);
+     *
+     * $scanned = 0;
+     * $it = NULL;
+     *
+     * // Without Redis::SCAN_RETRY we may receive empty results and
+     * // a nonzero iterator.
+     * do {
+     *     // Scan members containing '5'
+     *     $members = $redis->sscan('myset', $it, '*5*');
+     *     foreach ($members as $member) {
+     *          echo "NORETRY: $member\n";
+     *          $scanned++;
+     *     }
+     * } while ($it != 0);
+     * echo "TOTAL: $scanned\n";
+     *
+     * $redis->setOption(Redis::OPT_SCAN, Redis::SCAN_RETRY);
+     *
+     * $scanned = 0;
+     * $it = NULL;
+     *
+     * // With Redis::SCAN_RETRY PhpRedis will never return an empty array
+     * // when the cursor is non-zero
+     * while (($members = $redis->sscan('myset', $it, '*5*'))) {
+     *     foreach ($members as $member) {
+     *         echo "RETRY: $member\n";
+     *         $scanned++;
+     *     }
+     * }
+     * echo "TOTAL: $scanned\n";
+     * ?>
+     * </code>
+     *
+     */
     public function sscan(string $key, ?int &$iterator, ?string $pattern = null, int $count = 0): array|false;
 
     /** @return Redis|int|false*/
diff --git a/redis_arginfo.h b/redis_arginfo.h
index 9d28c7d3..5833affe 100644
--- a/redis_arginfo.h
+++ b/redis_arginfo.h
@@ -1,5 +1,5 @@
 /* This is a generated file, edit the .stub.php file instead.
- * Stub hash: 8a3b18f9b816cfb6aac50ef147008d7349496e08 */
+ * Stub hash: 5554480fcf6749dcfd69f371ad8dbd07fd8ed4c4 */
 
 ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis___construct, 0, 0, 0)
 	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, options, IS_ARRAY, 0, "null")
diff --git a/redis_legacy_arginfo.h b/redis_legacy_arginfo.h
index 5baf9d03..5d4355cb 100644
--- a/redis_legacy_arginfo.h
+++ b/redis_legacy_arginfo.h
@@ -1,5 +1,5 @@
 /* This is a generated file, edit the .stub.php file instead.
- * Stub hash: 8a3b18f9b816cfb6aac50ef147008d7349496e08 */
+ * Stub hash: 5554480fcf6749dcfd69f371ad8dbd07fd8ed4c4 */
 
 ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis___construct, 0, 0, 0)
 	ZEND_ARG_INFO(0, options)