module DataMapper::OrderedSet::Cache::API

The default implementation of the {API} that {OrderedSet} expects from the cache object that it uses to

1. keep track of insertion order
2. enforce set semantics.

Classes including {API} must customize the behavior of the cache in 2 ways:

They must determine the value to use as cache key and thus set discriminator, by implementing the {#key_for} method. The {#key_for} method accepts an arbitrary object as param and the method is free to return whatever value from that method. Obviously this will most likely be some attribute or value otherwise derived from the object that got passed in.

They must determine which objects are valid set entries by overwriting the {#valid?} method. The {#valid?} method accepts an arbitrary object as param and the overwriting method must return either true or false.

The motivation behind this is that set semantics cannot always be enforced by calling {#eql?} and {#hash} on the set's entries. For example, two entries might be considered unique wrt the set if their names are the same, but other internal state differs. This is exactly the case for {DataMapper::Property} and {DataMapper::Associations::Relationship} objects.

@see DataMapper::SubjectSet::NameCache

@api private

Public Class Methods

new() click to toggle source

Initialize a new Cache

@api private

# File lib/dm-core/support/ordered_set.rb, line 60
def initialize
  @cache = {}
end

Public Instance Methods

[](entry) click to toggle source

Return the index for the entry in the cache

@param [Object] entry

the entry to get the index for

@return [Integer, nil]

the index for the entry, or nil if it does not exist

@api private

# File lib/dm-core/support/ordered_set.rb, line 112
def [](entry)
  @cache[key_for(entry)]
end
[]=(entry, index) click to toggle source

Set the index for the entry in the cache

@param [Object] entry

the entry to set the index for

@param [Integer] index

the index to assign to the given entry

@return [Integer]

the given index for the entry

@api private

# File lib/dm-core/support/ordered_set.rb, line 127
def []=(entry, index)
  if valid?(entry)
    @cache[key_for(entry)] = index
  end
end
clear() click to toggle source

Removes all entries and returns self

@return [API] self

@api private

# File lib/dm-core/support/ordered_set.rb, line 156
def clear
  @cache.clear
  self
end
delete(entry) click to toggle source

Delete an entry from the cache

@param [Object] entry

the entry to delete from the cache

@return [API] self

@api private

# File lib/dm-core/support/ordered_set.rb, line 141
def delete(entry)
  deleted_index = @cache.delete(key_for(entry))
  if deleted_index
    @cache.each do |key, index|
      @cache[key] -= 1 if index > deleted_index
    end
  end
  deleted_index
end
include?(entry) click to toggle source

Check if the entry exists in the cache

@param [Object] entry

the entry to test for

@return [Boolean]

true if entry is included in the cache

@api private

# File lib/dm-core/support/ordered_set.rb, line 99
def include?(entry)
  @cache.has_key?(key_for(entry))
end
key_for(entry) click to toggle source

Given an entry, return the key to be used in the cache

@param [Object] entry

the entry to get the key for

@return [Object, nil]

a value derived from the entry that is used as key in the cache

@api private

# File lib/dm-core/support/ordered_set.rb, line 86
def key_for(entry)
  raise NotImplementedError, "#{self}#key_for must be implemented"
end
valid?(entry) click to toggle source

Tests if the given entry qualifies to be added to the cache

@param [Object] entry

the entry to be checked

@return [Boolean]

true if the entry qualifies to be added to the cache

@api private

# File lib/dm-core/support/ordered_set.rb, line 73
def valid?(entry)
  raise NotImplementedError, "#{self}#valid? must be implemented"
end