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
Initialize a new Cache
@api private
# File lib/dm-core/support/ordered_set.rb, line 60 def initialize @cache = {} end
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
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
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 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
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
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
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
Generated with the Darkfish Rdoc Generator 2.