string_commands.go

Documentation: github.com/redis/go-redis/v9

     1  package redis
     2  
     3  import (
     4  	"context"
     5  	"time"
     6  )
     7  
     8  type StringCmdable interface {
     9  	Append(ctx context.Context, key, value string) *IntCmd
    10  	Decr(ctx context.Context, key string) *IntCmd
    11  	DecrBy(ctx context.Context, key string, decrement int64) *IntCmd
    12  	Get(ctx context.Context, key string) *StringCmd
    13  	GetRange(ctx context.Context, key string, start, end int64) *StringCmd
    14  	GetSet(ctx context.Context, key string, value interface{}) *StringCmd
    15  	GetEx(ctx context.Context, key string, expiration time.Duration) *StringCmd
    16  	GetDel(ctx context.Context, key string) *StringCmd
    17  	Incr(ctx context.Context, key string) *IntCmd
    18  	IncrBy(ctx context.Context, key string, value int64) *IntCmd
    19  	IncrByFloat(ctx context.Context, key string, value float64) *FloatCmd
    20  	LCS(ctx context.Context, q *LCSQuery) *LCSCmd
    21  	MGet(ctx context.Context, keys ...string) *SliceCmd
    22  	MSet(ctx context.Context, values ...interface{}) *StatusCmd
    23  	MSetNX(ctx context.Context, values ...interface{}) *BoolCmd
    24  	Set(ctx context.Context, key string, value interface{}, expiration time.Duration) *StatusCmd
    25  	SetArgs(ctx context.Context, key string, value interface{}, a SetArgs) *StatusCmd
    26  	SetEx(ctx context.Context, key string, value interface{}, expiration time.Duration) *StatusCmd
    27  	SetNX(ctx context.Context, key string, value interface{}, expiration time.Duration) *BoolCmd
    28  	SetXX(ctx context.Context, key string, value interface{}, expiration time.Duration) *BoolCmd
    29  	SetRange(ctx context.Context, key string, offset int64, value string) *IntCmd
    30  	StrLen(ctx context.Context, key string) *IntCmd
    31  }
    32  
    33  func (c cmdable) Append(ctx context.Context, key, value string) *IntCmd {
    34  	cmd := NewIntCmd(ctx, "append", key, value)
    35  	_ = c(ctx, cmd)
    36  	return cmd
    37  }
    38  
    39  func (c cmdable) Decr(ctx context.Context, key string) *IntCmd {
    40  	cmd := NewIntCmd(ctx, "decr", key)
    41  	_ = c(ctx, cmd)
    42  	return cmd
    43  }
    44  
    45  func (c cmdable) DecrBy(ctx context.Context, key string, decrement int64) *IntCmd {
    46  	cmd := NewIntCmd(ctx, "decrby", key, decrement)
    47  	_ = c(ctx, cmd)
    48  	return cmd
    49  }
    50  
    51  // Get Redis `GET key` command. It returns redis.Nil error when key does not exist.
    52  func (c cmdable) Get(ctx context.Context, key string) *StringCmd {
    53  	cmd := NewStringCmd(ctx, "get", key)
    54  	_ = c(ctx, cmd)
    55  	return cmd
    56  }
    57  
    58  func (c cmdable) GetRange(ctx context.Context, key string, start, end int64) *StringCmd {
    59  	cmd := NewStringCmd(ctx, "getrange", key, start, end)
    60  	_ = c(ctx, cmd)
    61  	return cmd
    62  }
    63  
    64  func (c cmdable) GetSet(ctx context.Context, key string, value interface{}) *StringCmd {
    65  	cmd := NewStringCmd(ctx, "getset", key, value)
    66  	_ = c(ctx, cmd)
    67  	return cmd
    68  }
    69  
    70  // GetEx An expiration of zero removes the TTL associated with the key (i.e. GETEX key persist).
    71  // Requires Redis >= 6.2.0.
    72  func (c cmdable) GetEx(ctx context.Context, key string, expiration time.Duration) *StringCmd {
    73  	args := make([]interface{}, 0, 4)
    74  	args = append(args, "getex", key)
    75  	if expiration > 0 {
    76  		if usePrecise(expiration) {
    77  			args = append(args, "px", formatMs(ctx, expiration))
    78  		} else {
    79  			args = append(args, "ex", formatSec(ctx, expiration))
    80  		}
    81  	} else if expiration == 0 {
    82  		args = append(args, "persist")
    83  	}
    84  
    85  	cmd := NewStringCmd(ctx, args...)
    86  	_ = c(ctx, cmd)
    87  	return cmd
    88  }
    89  
    90  // GetDel redis-server version >= 6.2.0.
    91  func (c cmdable) GetDel(ctx context.Context, key string) *StringCmd {
    92  	cmd := NewStringCmd(ctx, "getdel", key)
    93  	_ = c(ctx, cmd)
    94  	return cmd
    95  }
    96  
    97  func (c cmdable) Incr(ctx context.Context, key string) *IntCmd {
    98  	cmd := NewIntCmd(ctx, "incr", key)
    99  	_ = c(ctx, cmd)
   100  	return cmd
   101  }
   102  
   103  func (c cmdable) IncrBy(ctx context.Context, key string, value int64) *IntCmd {
   104  	cmd := NewIntCmd(ctx, "incrby", key, value)
   105  	_ = c(ctx, cmd)
   106  	return cmd
   107  }
   108  
   109  func (c cmdable) IncrByFloat(ctx context.Context, key string, value float64) *FloatCmd {
   110  	cmd := NewFloatCmd(ctx, "incrbyfloat", key, value)
   111  	_ = c(ctx, cmd)
   112  	return cmd
   113  }
   114  
   115  func (c cmdable) LCS(ctx context.Context, q *LCSQuery) *LCSCmd {
   116  	cmd := NewLCSCmd(ctx, q)
   117  	_ = c(ctx, cmd)
   118  	return cmd
   119  }
   120  
   121  func (c cmdable) MGet(ctx context.Context, keys ...string) *SliceCmd {
   122  	args := make([]interface{}, 1+len(keys))
   123  	args[0] = "mget"
   124  	for i, key := range keys {
   125  		args[1+i] = key
   126  	}
   127  	cmd := NewSliceCmd(ctx, args...)
   128  	_ = c(ctx, cmd)
   129  	return cmd
   130  }
   131  
   132  // MSet is like Set but accepts multiple values:
   133  //   - MSet("key1", "value1", "key2", "value2")
   134  //   - MSet([]string{"key1", "value1", "key2", "value2"})
   135  //   - MSet(map[string]interface{}{"key1": "value1", "key2": "value2"})
   136  //   - MSet(struct), For struct types, see HSet description.
   137  func (c cmdable) MSet(ctx context.Context, values ...interface{}) *StatusCmd {
   138  	args := make([]interface{}, 1, 1+len(values))
   139  	args[0] = "mset"
   140  	args = appendArgs(args, values)
   141  	cmd := NewStatusCmd(ctx, args...)
   142  	_ = c(ctx, cmd)
   143  	return cmd
   144  }
   145  
   146  // MSetNX is like SetNX but accepts multiple values:
   147  //   - MSetNX("key1", "value1", "key2", "value2")
   148  //   - MSetNX([]string{"key1", "value1", "key2", "value2"})
   149  //   - MSetNX(map[string]interface{}{"key1": "value1", "key2": "value2"})
   150  //   - MSetNX(struct), For struct types, see HSet description.
   151  func (c cmdable) MSetNX(ctx context.Context, values ...interface{}) *BoolCmd {
   152  	args := make([]interface{}, 1, 1+len(values))
   153  	args[0] = "msetnx"
   154  	args = appendArgs(args, values)
   155  	cmd := NewBoolCmd(ctx, args...)
   156  	_ = c(ctx, cmd)
   157  	return cmd
   158  }
   159  
   160  // Set Redis `SET key value [expiration]` command.
   161  // Use expiration for `SETEx`-like behavior.
   162  //
   163  // Zero expiration means the key has no expiration time.
   164  // KeepTTL is a Redis KEEPTTL option to keep existing TTL, it requires your redis-server version >= 6.0,
   165  // otherwise you will receive an error: (error) ERR syntax error.
   166  func (c cmdable) Set(ctx context.Context, key string, value interface{}, expiration time.Duration) *StatusCmd {
   167  	args := make([]interface{}, 3, 5)
   168  	args[0] = "set"
   169  	args[1] = key
   170  	args[2] = value
   171  	if expiration > 0 {
   172  		if usePrecise(expiration) {
   173  			args = append(args, "px", formatMs(ctx, expiration))
   174  		} else {
   175  			args = append(args, "ex", formatSec(ctx, expiration))
   176  		}
   177  	} else if expiration == KeepTTL {
   178  		args = append(args, "keepttl")
   179  	}
   180  
   181  	cmd := NewStatusCmd(ctx, args...)
   182  	_ = c(ctx, cmd)
   183  	return cmd
   184  }
   185  
   186  // SetArgs provides arguments for the SetArgs function.
   187  type SetArgs struct {
   188  	// Mode can be `NX` or `XX` or empty.
   189  	Mode string
   190  
   191  	// Zero `TTL` or `Expiration` means that the key has no expiration time.
   192  	TTL      time.Duration
   193  	ExpireAt time.Time
   194  
   195  	// When Get is true, the command returns the old value stored at key, or nil when key did not exist.
   196  	Get bool
   197  
   198  	// KeepTTL is a Redis KEEPTTL option to keep existing TTL, it requires your redis-server version >= 6.0,
   199  	// otherwise you will receive an error: (error) ERR syntax error.
   200  	KeepTTL bool
   201  }
   202  
   203  // SetArgs supports all the options that the SET command supports.
   204  // It is the alternative to the Set function when you want
   205  // to have more control over the options.
   206  func (c cmdable) SetArgs(ctx context.Context, key string, value interface{}, a SetArgs) *StatusCmd {
   207  	args := []interface{}{"set", key, value}
   208  
   209  	if a.KeepTTL {
   210  		args = append(args, "keepttl")
   211  	}
   212  
   213  	if !a.ExpireAt.IsZero() {
   214  		args = append(args, "exat", a.ExpireAt.Unix())
   215  	}
   216  	if a.TTL > 0 {
   217  		if usePrecise(a.TTL) {
   218  			args = append(args, "px", formatMs(ctx, a.TTL))
   219  		} else {
   220  			args = append(args, "ex", formatSec(ctx, a.TTL))
   221  		}
   222  	}
   223  
   224  	if a.Mode != "" {
   225  		args = append(args, a.Mode)
   226  	}
   227  
   228  	if a.Get {
   229  		args = append(args, "get")
   230  	}
   231  
   232  	cmd := NewStatusCmd(ctx, args...)
   233  	_ = c(ctx, cmd)
   234  	return cmd
   235  }
   236  
   237  // SetEx Redis `SETEx key expiration value` command.
   238  func (c cmdable) SetEx(ctx context.Context, key string, value interface{}, expiration time.Duration) *StatusCmd {
   239  	cmd := NewStatusCmd(ctx, "setex", key, formatSec(ctx, expiration), value)
   240  	_ = c(ctx, cmd)
   241  	return cmd
   242  }
   243  
   244  // SetNX Redis `SET key value [expiration] NX` command.
   245  //
   246  // Zero expiration means the key has no expiration time.
   247  // KeepTTL is a Redis KEEPTTL option to keep existing TTL, it requires your redis-server version >= 6.0,
   248  // otherwise you will receive an error: (error) ERR syntax error.
   249  func (c cmdable) SetNX(ctx context.Context, key string, value interface{}, expiration time.Duration) *BoolCmd {
   250  	var cmd *BoolCmd
   251  	switch expiration {
   252  	case 0:
   253  		// Use old `SETNX` to support old Redis versions.
   254  		cmd = NewBoolCmd(ctx, "setnx", key, value)
   255  	case KeepTTL:
   256  		cmd = NewBoolCmd(ctx, "set", key, value, "keepttl", "nx")
   257  	default:
   258  		if usePrecise(expiration) {
   259  			cmd = NewBoolCmd(ctx, "set", key, value, "px", formatMs(ctx, expiration), "nx")
   260  		} else {
   261  			cmd = NewBoolCmd(ctx, "set", key, value, "ex", formatSec(ctx, expiration), "nx")
   262  		}
   263  	}
   264  
   265  	_ = c(ctx, cmd)
   266  	return cmd
   267  }
   268  
   269  // SetXX Redis `SET key value [expiration] XX` command.
   270  //
   271  // Zero expiration means the key has no expiration time.
   272  // KeepTTL is a Redis KEEPTTL option to keep existing TTL, it requires your redis-server version >= 6.0,
   273  // otherwise you will receive an error: (error) ERR syntax error.
   274  func (c cmdable) SetXX(ctx context.Context, key string, value interface{}, expiration time.Duration) *BoolCmd {
   275  	var cmd *BoolCmd
   276  	switch expiration {
   277  	case 0:
   278  		cmd = NewBoolCmd(ctx, "set", key, value, "xx")
   279  	case KeepTTL:
   280  		cmd = NewBoolCmd(ctx, "set", key, value, "keepttl", "xx")
   281  	default:
   282  		if usePrecise(expiration) {
   283  			cmd = NewBoolCmd(ctx, "set", key, value, "px", formatMs(ctx, expiration), "xx")
   284  		} else {
   285  			cmd = NewBoolCmd(ctx, "set", key, value, "ex", formatSec(ctx, expiration), "xx")
   286  		}
   287  	}
   288  
   289  	_ = c(ctx, cmd)
   290  	return cmd
   291  }
   292  
   293  func (c cmdable) SetRange(ctx context.Context, key string, offset int64, value string) *IntCmd {
   294  	cmd := NewIntCmd(ctx, "setrange", key, offset, value)
   295  	_ = c(ctx, cmd)
   296  	return cmd
   297  }
   298  
   299  func (c cmdable) StrLen(ctx context.Context, key string) *IntCmd {
   300  	cmd := NewIntCmd(ctx, "strlen", key)
   301  	_ = c(ctx, cmd)
   302  	return cmd
   303  }
   304
View as plain text