From 980ea6b15425628f06a0787e80fb516ef62a0eb9 Mon Sep 17 00:00:00 2001 From: michael-grunder Date: Tue, 1 Nov 2022 14:13:17 -0700 Subject: Documentation: More docblocks with examples [skip ci] --- redis.stub.php | 251 ++++++++++++++++++++++++++++++++++++++++++++++++- redis_arginfo.h | 10 +- redis_legacy_arginfo.h | 9 +- 3 files changed, 257 insertions(+), 13 deletions(-) diff --git a/redis.stub.php b/redis.stub.php index 904e888e..eab463c4 100644 --- a/redis.stub.php +++ b/redis.stub.php @@ -2351,19 +2351,224 @@ class Redis { public function zAdd(string $key, array|float $score_or_options, mixed ...$more_scores_and_mems): Redis|int|false; + /** + * Return the number of elements in a sorted set. + * + * @see https://redis.io/commands/zcard + * + * @param string $key The sorted set to retreive cardinality from. + * + * @return Redis|int|false The number of elements in the set or false on failure + * + * + * 'localhost']); + * + * $redis->del('zs'); + * $redis->zAdd('zs', 0, 'a', 1, 'b', 2, 'c'); + * + * // count(['a', 'b', 'c']) == 3 + * $redis->zCard('zs'); + * ?> + * + */ public function zCard(string $key): Redis|int|false; - public function zCount(string $key, string $start , string $end): Redis|int|false; + /** + * Count the number of members in a sorted set with scores inside a provided range. + * + * @see https://redis.io/commands/zcount + * + * @param string $key The sorted set to check. + * @param string $min The minimum score to include in the count + * @param string $max The maximum score to include in the count + * + * NOTE: In addition to a floating point score you may pass the special values of '-inf' and + * '+inf' meaning negative and positive infinity, respectively. + * + * + * 'localhost']); + * + * $redis->del('fruit-rankings'); + * $redis->zadd('fruit-rankings', -99, 'tomato', 50, 'apple', 60, 'pear', 85, 'mango'); + * + * // count(['apple', 'oear', 'mango']) == 3 + * $redis->zCount('fruit-rankings', '0', '+inf'); + * + * // count(['apple', 'pear']) == 2 + * $redis->zCount('fruit-rankings', 50, 60); + * + * // count(['tomato']) == 1 + * $redis->zCount('fruit-rankings', '-inf', 0); + * ?> + * + */ + public function zCount(string $key, string $start, string $end): Redis|int|false; + + /** + * Create or increment the score of a member in a Redis sorted set + * + * @see https://redis.io/commands/zincrby + * + * @param string $key The sorted set in question. + * @param float $value How much to increment the score. + * + * @return Redis|float|false The new score of the member or false on failure. + * + * 'localhost']); + * + * $redis->del('zs'); + * $redis->zAdd('zs', 0, 'apples', 2, 'bananas'); + * + * // 2 + 5.0 == 7 + * print_r($redis->zIncrBy('zs', 5.0, 'bananas')); + * + * // new element so 0 + 2.0 == 2 + * print_r($redis->zIncrBy('zs', 2.0, 'eggplants')); + * ?> + * + */ public function zIncrBy(string $key, float $value, mixed $member): Redis|float|false; + /** + * Count the number of elements in a sorted set whos members fall within the provided + * lexographical range. + * + * @see https://redis.io/commands/zlexcount + * + * @param string $key The sorted set to check. + * @param string $min The minimum matching lexographical string + * @param string $max The maximum matching lexographical string + * + * @return Redis|int|false The number of members that fall within the range or false on failure. + * + * + * 'localhost']); + * + * $redis->del('captains'); + * $redis->zAdd('captains', 0, 'Janeway', 0, 'Kirk', 0, 'Picard', 0, 'Sisko', 0, 'Archer'); + * + * count(['Archer', 'Janeway', 'Kirk', 'Picard']) == 4 + * $redis->zLexCount('captains', '[A', '[S'); + * + * count(['Kirk', 'Picard']) == 2 + * $redis->zRangeByLex('captains', '[A', '[S', 2, 2); + * ?> + * + * + */ public function zLexCount(string $key, string $min, string $max): Redis|int|false; - public function zMscore(string $key, string $member, string ...$other_members): Redis|array|false; + /** + * Retreive the score of one or more members in a sorted set. + * + * @see https://redis.io/commands/zmscore + * + * @param string $key The sorted set + * @param mixed $member The first member to return the score from + * @param mixed $other_members One or more additional members to return the scores of. + * + * @return Redis|array|false An array of the scores of the requested elements. + * + * + * 'localhost']); + * + * $redis->del('zs'); + * + * $redis->zAdd('zs', 0, 'zero', 1, 'one', 2, 'two', 3, 'three'); + * + * // array(2) { + * // [0]=> + * // float(0) + * // [1]=> + * // float(2) + * // } + * $redis->zMScore('zs', 'zero', 'two'); + * + * // array(2) { + * // [0]=> + * // float(1) + * // [1]=> + * // bool(false) + * // } + * $redis->zMScore('zs', 'one', 'not-a-member'); + * ?> + * + */ + public function zMscore(string $key, mixed $member, mixed ...$other_members): Redis|array|false; - public function zPopMax(string $key, int $value = null): Redis|array|false; + /** + * Pop one or more of the highest scoring elements from a sorted set. + * + * @see https://redis.io/commands/zpopmax + * + * @param string $key The sorted set to pop elements from. + * @param int $count An optional count of elements to pop. + * + * @return Redis|array|false All of the popped elements with scores or false on fialure. + * + * + * 'localhost']); + * + * $redis->del('zs'); + * $redis->zAdd('zs', 0, 'zero', 1, 'one', 2, 'two', 3, 'three'); + * + * // Array + * // ( + * // [three] => 3 + * // ) + * print_r($redis->zPopMax('zs')); + * + * // Array + * // ( + * // [two] => 2 + * // [one] => 1 + * // ) + * print_r($redis->zPopMax('zs', 2)); + * ?> + * + */ + public function zPopMax(string $key, int $count = null): Redis|array|false; - public function zPopMin(string $key, int $value = null): Redis|array|false; + /** + * Pop one or more of the lowest scoring elements from a sorted set. + * + * @see https://redis.io/commands/zpopmin + * + * @param string $key The sorted set to pop elements from. + * @param int $count An optional count of elements to pop. + * + * @return Redis|array|false The popped elements with their scores or false on failure. + * + * + * 'localhost']); + * + * $redis->del('zs'); + * $redis->zAdd('zs', 0, 'zero', 1, 'one', 2, 'two', 3, 'three'); + * + * // Array + * // ( + * // [zero] => 0 + * // ) + * $redis->zPopMin('zs'); + * + * // Array + * // ( + * // [one] => 1 + * // [two] => 2 + * // ) + * $redis->zPopMin('zs', 2); + * ?> + * + */ + public function zPopMin(string $key, int $count = null): Redis|array|false; /** * Retrieve a range of elements of a sorted set between a start and end point. @@ -2402,6 +2607,44 @@ class Redis { */ public function zRange(string $key, mixed $start, mixed $end, array|bool|null $options = null): Redis|array|false; + /** + * Retrieve a range of elements from a sorted set by legographical range. + * + * @see https://redis.io/commands/zrangebylex + * + * @param string $key The sorted set to retreive elements from + * @param string $min The minimum legographical value to return + * @param string $max The maximum legographical value to return + * @param int $offset An optional offset within the matching values to return + * @param int $count An optional count to limit the replies to (used in conjunction with offset) + * + * @return Redis|array|false An array of matching elements or false on failure. + * + * + * 'localhost']); + * + * $redis->del('captains'); + * $redis->zAdd('captains', 0, 'Janeway', 0, 'Kirk', 0, 'Picard', 0, 'Sisko', 0, 'Archer'); + * + * // Array + * // ( + * // [0] => Archer + * // [1] => Janeway + * // [2] => Kirk + * // [3] => Picard + * // ) + * $redis->zRangeByLex('captains', '[A', '[S'); + * + * // Array + * // ( + * // [0] => Kirk + * // [1] => Picard + * // ) + * $redis->zRangeByLex('captains', '[A', '[S', 2, 2); + * ?> + * + */ public function zRangeByLex(string $key, string $min, string $max, int $offset = -1, int $count = -1): Redis|array|false; /** diff --git a/redis_arginfo.h b/redis_arginfo.h index 3b2fe5a2..511c5dfe 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: 08c0be22623f22153c7df080cfb93388b73fa259 */ + * Stub hash: 55e15f9e5c33b941552643c0302becdc3241212e */ 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") @@ -996,11 +996,15 @@ ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX(arginfo_class_Redis_zLexCount, 0, 3, ZEND_ARG_TYPE_INFO(0, max, IS_STRING, 0) ZEND_END_ARG_INFO() -#define arginfo_class_Redis_zMscore arginfo_class_Redis_geohash +ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX(arginfo_class_Redis_zMscore, 0, 2, Redis, MAY_BE_ARRAY|MAY_BE_FALSE) + ZEND_ARG_TYPE_INFO(0, key, IS_STRING, 0) + ZEND_ARG_TYPE_INFO(0, member, IS_MIXED, 0) + ZEND_ARG_VARIADIC_TYPE_INFO(0, other_members, IS_MIXED, 0) +ZEND_END_ARG_INFO() ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX(arginfo_class_Redis_zPopMax, 0, 1, Redis, MAY_BE_ARRAY|MAY_BE_FALSE) ZEND_ARG_TYPE_INFO(0, key, IS_STRING, 0) - ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, value, IS_LONG, 0, "null") + ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, count, IS_LONG, 0, "null") ZEND_END_ARG_INFO() #define arginfo_class_Redis_zPopMin arginfo_class_Redis_zPopMax diff --git a/redis_legacy_arginfo.h b/redis_legacy_arginfo.h index a5700322..8ea1a2b2 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: 08c0be22623f22153c7df080cfb93388b73fa259 */ + * Stub hash: 55e15f9e5c33b941552643c0302becdc3241212e */ ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis___construct, 0, 0, 0) ZEND_ARG_INFO(0, options) @@ -862,12 +862,9 @@ ZEND_END_ARG_INFO() #define arginfo_class_Redis_zMscore arginfo_class_Redis_geohash -ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis_zPopMax, 0, 0, 1) - ZEND_ARG_INFO(0, key) - ZEND_ARG_INFO(0, value) -ZEND_END_ARG_INFO() +#define arginfo_class_Redis_zPopMax arginfo_class_Redis_lPop -#define arginfo_class_Redis_zPopMin arginfo_class_Redis_zPopMax +#define arginfo_class_Redis_zPopMin arginfo_class_Redis_lPop ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis_zRange, 0, 0, 3) ZEND_ARG_INFO(0, key) -- cgit v1.2.3