Class: Familia::ListKey

Inherits:
DataType show all
Defined in:
lib/familia/data_type/types/listkey.rb

Instance Attribute Summary collapse

Attributes included from Settings

#current_key_version, #default_expiration, #delim, #encryption_keys, #encryption_personalization, #logical_database, #prefix, #schema_path, #schema_validator, #schemas, #strict_write_order, #suffix, #transaction_mode

Instance Method Summary collapse

Methods included from Features::Autoloader

autoload_files, included, normalize_to_config_name

Methods included from DataType::Serialization

#deserialize_value, #deserialize_values, #deserialize_values_with_nil, #serialize_value

Methods included from DataType::DatabaseCommands

#current_expiration, #delete!, #echo, #exists?, #expire, #expireat, #persist, #rename, #renamenx, #type

Methods included from DataType::Connection

#dbclient, #dbkey, #uri

Methods included from Connection::Behavior

#connect, #create_dbclient, #multi, #normalize_uri, #pipeline, #pipelined, #transaction, #uri=, #url, #url=

Methods included from Settings

#configure, #default_suffix, #pipelined_mode, #pipelined_mode=

Methods included from Base

add_feature, #as_json, #expired?, #expires?, find_feature, #generate_id, #to_json, #to_s, #ttl, #update_expiration, #uuid

Constructor Details

This class inherits a constructor from Familia::DataType

Instance Attribute Details

#features_enabled ⇒ Object (readonly) Originally defined in module Features

Returns the value of attribute features_enabled.

#logical_database(val = nil) ⇒ Object Originally defined in module DataType::ClassMethods

#parent ⇒ Object Originally defined in module DataType::ClassMethods

Returns the value of attribute parent.

#prefix ⇒ Object Originally defined in module DataType::ClassMethods

Returns the value of attribute prefix.

#suffix ⇒ Object Originally defined in module DataType::ClassMethods

Returns the value of attribute suffix.

#uri(val = nil) ⇒ Object Originally defined in module DataType::ClassMethods

Returns the value of attribute uri.

Instance Method Details

#<<(val) ⇒ Object Also known as: add_element, add 



33
34
35
 
# File 'lib/familia/data_type/types/listkey.rb', line 33

def <<(val)
  push(val)
end

#[](idx, count = nil) ⇒ Object Also known as: slice 



82
83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/familia/data_type/types/listkey.rb', line 82

def [](idx, count = nil)
  if idx.is_a? Range
    range idx.first, idx.last
  elsif count
    case count <=> 0
    when 1  then range(idx, idx + count - 1)
    when 0  then []
    when -1 then nil
    end
  else
    at idx
  end
end

#at(idx) ⇒ Object 



167
168
169
 
# File 'lib/familia/data_type/types/listkey.rb', line 167

def at(idx)
  deserialize_value dbclient.lindex(dbkey, idx)
end

#collect ⇒ Object 



151
152
153
 
# File 'lib/familia/data_type/types/listkey.rb', line 151

def collect(&)
  range.collect(&)
end

#collectraw ⇒ Object 



159
160
161
 
# File 'lib/familia/data_type/types/listkey.rb', line 159

def collectraw(&)
  rangeraw.collect(&)
end

#each ⇒ Object 



135
136
137
 
# File 'lib/familia/data_type/types/listkey.rb', line 135

def each(&)
  range.each(&)
end

#each_with_index ⇒ Object 



139
140
141
 
# File 'lib/familia/data_type/types/listkey.rb', line 139

def each_with_index(&)
  range.each_with_index(&)
end

#eachraw ⇒ Object 



143
144
145
 
# File 'lib/familia/data_type/types/listkey.rb', line 143

def eachraw(&)
  rangeraw.each(&)
end

#eachraw_with_index ⇒ Object 



147
148
149
 
# File 'lib/familia/data_type/types/listkey.rb', line 147

def eachraw_with_index(&)
  rangeraw.each_with_index(&)
end

#element_count ⇒ Integer Also known as: size, length, count

Returns the number of elements in the list

Returns:

  • (Integer) —

    number of elements



9
10
11
 
# File 'lib/familia/data_type/types/listkey.rb', line 9

def element_count
  dbclient.llen dbkey
end

#empty? ⇒ Boolean

Returns:

  • (Boolean) 


16
17
18
 
# File 'lib/familia/data_type/types/listkey.rb', line 16

def empty?
  element_count.zero?
end

#first ⇒ Object 



268
269
270
 
# File 'lib/familia/data_type/types/listkey.rb', line 268

def first
  at 0
end

#insert(position, pivot, value) ⇒ Integer Also known as: linsert

Inserts an element before or after a pivot element

Parameters:

  • position (:before, :after) —

    Where to insert relative to pivot

  • pivot —

    The pivot element to search for

  • value —

    The value to insert

Returns:

  • (Integer) —

    Length of list after insert, or -1 if pivot not found



201
202
203
204
205
206
207
208
209
210
211
212
 
# File 'lib/familia/data_type/types/listkey.rb', line 201

def insert(position, pivot, value)
  warn_if_dirty!
  pos = case position
        when :before, 'BEFORE' then 'BEFORE'
        when :after, 'AFTER' then 'AFTER'
        else
          raise ArgumentError, "position must be :before or :after, got #{position.inspect}"
        end
  result = dbclient.linsert dbkey, pos, serialize_value(pivot), serialize_value(value)
  update_expiration if result.positive?
  result
end

#last ⇒ Object 



272
273
274
 
# File 'lib/familia/data_type/types/listkey.rb', line 272

def last
  at(-1)
end

#member?(value) ⇒ Boolean

Returns:

  • (Boolean) 


97
98
99
 
# File 'lib/familia/data_type/types/listkey.rb', line 97

def member?(value)
  !dbclient.lpos(dbkey, serialize_value(value)).nil?
end

#members(count = -1)) ⇒ Object Also known as: all, to_a 



122
123
124
125
126
 
# File 'lib/familia/data_type/types/listkey.rb', line 122

def members(count = -1)
  echo :members, Familia.pretty_stack(limit: 1) if Familia.debug
  count -= 1 if count.positive?
  range 0, count
end

#membersraw(count = -1)) ⇒ Object 



130
131
132
133
 
# File 'lib/familia/data_type/types/listkey.rb', line 130

def membersraw(count = -1)
  count -= 1 if count.positive?
  rangeraw 0, count
end

#move(destination, wherefrom, whereto) ⇒ Object? Also known as: lmove

Moves an element from this list to another list atomically

Parameters:

  • destination (ListKey, String) —

    Destination list (ListKey or key string)

  • wherefrom (:left, :right) —

    Which end to pop from source

  • whereto (:left, :right) —

    Which end to push to destination

Returns:

  • (Object, nil) —

    The moved element, or nil if source is empty



220
221
222
223
224
225
226
227
228
229
230
231
232
233
 
# File 'lib/familia/data_type/types/listkey.rb', line 220

def move(destination, wherefrom, whereto)
  warn_if_dirty!
  dest_key = destination.respond_to?(:dbkey) ? destination.dbkey : destination
  from = wherefrom.to_s.upcase
  to = whereto.to_s.upcase

  unless %w[LEFT RIGHT].include?(from) && %w[LEFT RIGHT].include?(to)
    raise ArgumentError, 'wherefrom and whereto must be :left or :right'
  end

  result = dbclient.lmove dbkey, dest_key, from, to
  update_expiration
  deserialize_value result
end

#pop(count = nil) ⇒ Object, ...

Removes and returns the last element(s) from the list

Parameters:

  • count (Integer, nil) (defaults to: nil) —

    Number of elements to pop (Redis 6.2+)

Returns:

  • (Object, Array<Object>, nil) —

    Single element or array if count specified



55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/familia/data_type/types/listkey.rb', line 55

def pop(count = nil)
  warn_if_dirty!
  ret = if count
          result = dbclient.rpop(dbkey, count)
          result.nil? ? nil : deserialize_values(*result)
        else
          deserialize_value dbclient.rpop(dbkey)
        end
  update_expiration
  ret
end

#push(*values) ⇒ Object Also known as: append

Note:

This method executes a Redis RPUSH immediately, unlike scalar field setters which are deferred until save. If the parent object has unsaved scalar field changes, consider calling save first to avoid split-brain state.



23
24
25
26
27
28
29
30
 
# File 'lib/familia/data_type/types/listkey.rb', line 23

def push *values
  warn_if_dirty!
  echo :push, Familia.pretty_stack(limit: 1) if Familia.debug
  values.flatten.compact.each { |v| dbclient.rpush dbkey, serialize_value(v) }
  dbclient.ltrim dbkey, -@opts[:maxlength], -1 if @opts[:maxlength]
  update_expiration
  self
end

#pushx(*values) ⇒ Integer Also known as: rpushx

Pushes values only if the list already exists

Parameters:

  • values —

    Values to push to the tail of the list

Returns:

  • (Integer) —

    Length of list after push, or 0 if list doesn't exist



239
240
241
242
243
244
245
246
247
248
249
 
# File 'lib/familia/data_type/types/listkey.rb', line 239

def pushx(*values)
  return 0 if values.empty?

  serialized_values = values.flatten.compact.map { |v| serialize_value(v) }
  return 0 if serialized_values.empty?

  warn_if_dirty!
  result = dbclient.rpushx(dbkey, serialized_values)
  update_expiration if result.positive?
  result
end

#range(sidx = 0, eidx = -1)) ⇒ Object 



113
114
115
116
 
# File 'lib/familia/data_type/types/listkey.rb', line 113

def range(sidx = 0, eidx = -1)
  elements = rangeraw sidx, eidx
  deserialize_values(*elements)
end

#rangeraw(sidx = 0, eidx = -1)) ⇒ Object 



118
119
120
 
# File 'lib/familia/data_type/types/listkey.rb', line 118

def rangeraw(sidx = 0, eidx = -1)
  dbclient.lrange(dbkey, sidx, eidx)
end

#remove_element(value, count = 0) ⇒ Integer Also known as: remove

Removes elements equal to value from the list

Parameters:

  • value —

    The value to remove

  • count (Integer) (defaults to: 0) —

    Number of elements to remove (0 means all)

Returns:

  • (Integer) —

    The number of removed elements



105
106
107
108
109
110
 
# File 'lib/familia/data_type/types/listkey.rb', line 105

def remove_element(value, count = 0)
  warn_if_dirty!
  ret = dbclient.lrem dbkey, count, serialize_value(value)
  update_expiration
  ret
end

#select ⇒ Object 



155
156
157
 
# File 'lib/familia/data_type/types/listkey.rb', line 155

def select(&)
  range.select(&)
end

#selectraw ⇒ Object 



163
164
165
 
# File 'lib/familia/data_type/types/listkey.rb', line 163

def selectraw(&)
  rangeraw.select(&)
end

#set(index, value) ⇒ String Also known as: lset

Sets the element at the specified index

Parameters:

  • index (Integer) —

    Index to set (0-based, negative counts from end)

  • value —

    The value to set

Returns:

  • (String) —

    "OK" on success

Raises:

  • (Redis::CommandError) —

    if index is out of range



188
189
190
191
192
193
 
# File 'lib/familia/data_type/types/listkey.rb', line 188

def set(index, value)
  warn_if_dirty!
  result = dbclient.lset dbkey, index, serialize_value(value)
  update_expiration
  result
end

#shift(count = nil) ⇒ Object, ...

Removes and returns the first element(s) from the list

Parameters:

  • count (Integer, nil) (defaults to: nil) —

    Number of elements to shift (Redis 6.2+)

Returns:

  • (Object, Array<Object>, nil) —

    Single element or array if count specified



70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/familia/data_type/types/listkey.rb', line 70

def shift(count = nil)
  warn_if_dirty!
  ret = if count
          result = dbclient.lpop(dbkey, count)
          result.nil? ? nil : deserialize_values(*result)
        else
          deserialize_value dbclient.lpop(dbkey)
        end
  update_expiration
  ret
end

#trim(start, stop) ⇒ String Also known as: ltrim

Trims the list to the specified range

Parameters:

  • start (Integer) —

    Start index (0-based, negative counts from end)

  • stop (Integer) —

    End index (inclusive, negative counts from end)

Returns:

  • (String) —

    "OK" on success



175
176
177
178
179
180
 
# File 'lib/familia/data_type/types/listkey.rb', line 175

def trim(start, stop)
  warn_if_dirty!
  result = dbclient.ltrim dbkey, start, stop
  update_expiration
  result
end

#unshift(*values) ⇒ Object Also known as: prepend

Note:

This method executes a Redis LPUSH immediately, unlike scalar field setters which are deferred until save. If the parent object has unsaved scalar field changes, consider calling save first to avoid split-brain state.



42
43
44
45
46
47
48
49
 
# File 'lib/familia/data_type/types/listkey.rb', line 42

def unshift *values
  warn_if_dirty!
  values.flatten.compact.each { |v| dbclient.lpush dbkey, serialize_value(v) }
  # TODO: test maxlength
  dbclient.ltrim dbkey, 0, @opts[:maxlength] - 1 if @opts[:maxlength]
  update_expiration
  self
end

#unshiftx(*values) ⇒ Integer Also known as: lpushx

Pushes values to the head only if the list already exists

Parameters:

  • values —

    Values to push to the head of the list

Returns:

  • (Integer) —

    Length of list after push, or 0 if list doesn't exist



255
256
257
258
259
260
261
262
263
264
265
 
# File 'lib/familia/data_type/types/listkey.rb', line 255

def unshiftx(*values)
  return 0 if values.empty?

  serialized_values = values.flatten.compact.map { |v| serialize_value(v) }
  return 0 if serialized_values.empty?

  warn_if_dirty!
  result = dbclient.lpushx(dbkey, serialized_values)
  update_expiration if result.positive?
  result
end