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 {#} method. The {#} 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 {#} method. The {#} 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 {#} and {#} 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 60: def initialize 61: @cache = {} 62: 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 112: def [](entry) 113: @cache[key_for(entry)] 114: 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 127: def []=(entry, index) 128: if valid?(entry) 129: @cache[key_for(entry)] = index 130: end 131: end
Removes all entries and returns self
@return [API] self
@api private
# File lib/dm-core/support/ordered_set.rb, line 156 156: def clear 157: @cache.clear 158: self 159: 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 141: def delete(entry) 142: deleted_index = @cache.delete(key_for(entry)) 143: if deleted_index 144: @cache.each do |key, index| 145: @cache[key] -= 1 if index > deleted_index 146: end 147: end 148: deleted_index 149: 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 99: def include?(entry) 100: @cache.has_key?(key_for(entry)) 101: 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 86: def key_for(entry) 87: raise NotImplementedError, "#{self}#key_for must be implemented" 88: 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 73: def valid?(entry) 74: raise NotImplementedError, "#{self}#valid? must be implemented" 75: end
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.