From cbe90ae046ec634b96202dcd868018d340689118 Mon Sep 17 00:00:00 2001 From: Scott Osteen Date: Sun, 17 Nov 2024 20:41:59 -0600 Subject: [PATCH] docs added --- docs/docs/commands/hash/hexpire.mdx | 48 +++++++++++++++++++++++++++++ docs/docs/commands/hash/httl.mdx | 48 +++++++++++++++++++++++++++++ sugardb/api_hash.go | 37 ++++++++++++++++++++++ 3 files changed, 133 insertions(+) create mode 100644 docs/docs/commands/hash/hexpire.mdx create mode 100644 docs/docs/commands/hash/httl.mdx diff --git a/docs/docs/commands/hash/hexpire.mdx b/docs/docs/commands/hash/hexpire.mdx new file mode 100644 index 0000000..cdb090e --- /dev/null +++ b/docs/docs/commands/hash/hexpire.mdx @@ -0,0 +1,48 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# HEXPIRE + +### Syntax +``` +HEXPIRE key seconds [NX | XX | GT | LT] FIELDS numfields field [field...] +``` + +### Module +hash + +### Categories +fast +hash +write + +### Description +Set an expiration (TTL or time to live) in seconds on one or more fields of a given hash key. +You must specify at least one field. Field(s) will automatically be deleted from the hash key when their TTLs expire. + +### Examples + + + + Set the expiration in seconds for fields in the hash: + ```go + db, err := sugardb.NewSugarDB() + if err != nil { + log.Fatal(err) + } + respArray, err := db.HExpire("key", 500, nil, field1, field2) + ``` + + + Set the expiration in seconds for fields in the hash: + ``` + > HEXPIRE key 500 FIELDS 2 field1 field2 + ``` + + diff --git a/docs/docs/commands/hash/httl.mdx b/docs/docs/commands/hash/httl.mdx new file mode 100644 index 0000000..88b0c7f --- /dev/null +++ b/docs/docs/commands/hash/httl.mdx @@ -0,0 +1,48 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# HTTL + +### Syntax +``` +HTTL key FIELDS numfields field [field...] +``` + +### Module +hash + +### Categories +fast +hash +read + +### Description +Returns the remaining TTL (time to live) of a hash key's field(s) that have a set expiration. +This introspection capability allows you to check how many seconds a given hash field will continue to be part of the hash key. + +### Examples + + + + Get the expiration time in seconds for fields in the hash: + ```go + db, err := sugardb.NewSugarDB() + if err != nil { + log.Fatal(err) + } + TTLArray, err := db.HTTL("key", field1, field2) + ``` + + + Get the expiration time in seconds for fields in the hash: + ``` + > HTTL key FIELDS 2 field1 field2 + ``` + + diff --git a/sugardb/api_hash.go b/sugardb/api_hash.go index 777ff4e..05977c1 100644 --- a/sugardb/api_hash.go +++ b/sugardb/api_hash.go @@ -357,6 +357,27 @@ func (server *SugarDB) HDel(key string, fields ...string) (int, error) { return internal.ParseIntegerResponse(b) } +// HExpire sets the expiration for the provided field(s) in a hash map. +// +// Parameters: +// +// `key` - string - the key to the hash map. +// +// `seconds` - int - number of seconds until expiration. +// +// `ExOpt` - ExpireOptions - One of NX, XX, GT, LT. +// +// `fields` - ...string - a list of fields to set expiration of. +// +// Returns: an integer array representing the outcome of the commmand for each field. +// - Integer reply: -2 if no such field exists in the provided hash key, or the provided key does not exist. +// - Integer reply: 0 if the specified NX | XX | GT | LT condition has not been met. +// - Integer reply: 1 if the expiration time was set/updated. +// - Integer reply: 2 when HEXPIRE/HPEXPIRE is called with 0 seconds +// +// Errors: +// +// "value of key is not a hash" - when the provided key is not a hash. func (server *SugarDB) HExpire(key string, seconds int, ExOpt ExpireOptions, fields ...string) ([]int, error) { secs := fmt.Sprintf("%v", seconds) cmd := []string{"HEXPIRE", key, secs} @@ -376,6 +397,22 @@ func (server *SugarDB) HExpire(key string, seconds int, ExOpt ExpireOptions, fie return internal.ParseIntegerArrayResponse(b) } +// HTTL gets the expiration for the provided field(s) in a hash map. +// +// Parameters: +// +// `key` - string - the key to the hash map. +// +// `fields` - ...string - a list of fields to get TTL for. +// +// Returns: an integer array representing the outcome of the commmand for each field. +// - Integer reply: the TTL in seconds. +// - Integer reply: -2 if no such field exists in the provided hash key, or the provided key does not exist. +// - Integer reply: -1 if the field exists but has no associated expiration set. +// +// Errors: +// +// "value of key is not a hash" - when the provided key is not a hash. func (server *SugarDB) HTTL(key string, fields ...string) ([]int, error) { numFields := fmt.Sprintf("%v", len(fields))