Module: DataMapper::OrderedSet::Cache::API Private

Included in:
DataMapper::OrderedSet::Cache, SubjectSet::NameCache
Defined in:
lib/dm-core/support/ordered_set.rb

Overview

This module is part of a private API. You should avoid using this module if possible, as it may be removed or be changed in the future.

The default implementation of the API that DataMapper::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 Property and Associations::Relationship objects.

See Also:

Instance Method Summary collapse

Instance Method Details

#[](entry) ⇒ Integer?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Return the index for the entry in the cache

Parameters:

  • entry (Object) —

    the entry to get the index for

Returns:

  • (Integer, nil) —

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



114
115
116
 
# File 'lib/dm-core/support/ordered_set.rb', line 114

def [](entry)
  @cache[key_for(entry)]
end

#[]=(entry, index) ⇒ Integer

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Set the index for the entry in the cache

Parameters:

  • entry (Object) —

    the entry to set the index for

  • index (Integer) —

    the index to assign to the given entry

Returns:

  • (Integer) —

    the given index for the entry



129
130
131
132
133
 
# File 'lib/dm-core/support/ordered_set.rb', line 129

def []=(entry, index)
  if valid?(entry)
    @cache[key_for(entry)] = index
  end
end

#clear ⇒ API

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Removes all entries and returns self

Returns:

  • (API) —

    self



158
159
160
161
 
# File 'lib/dm-core/support/ordered_set.rb', line 158

def clear
  @cache.clear
  self
end

#delete(entry) ⇒ API

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Delete an entry from the cache

Parameters:

  • entry (Object) —

    the entry to delete from the cache

Returns:

  • (API) —

    self



143
144
145
146
147
148
149
150
151
 
# File 'lib/dm-core/support/ordered_set.rb', line 143

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) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Check if the entry exists in the cache

Parameters:

  • entry (Object) —

    the entry to test for

Returns:

  • (Boolean) —

    true if entry is included in the cache



101
102
103
 
# File 'lib/dm-core/support/ordered_set.rb', line 101

def include?(entry)
  @cache.has_key?(key_for(entry))
end

#initialize ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Initialize a new Cache



62
63
64
 
# File 'lib/dm-core/support/ordered_set.rb', line 62

def initialize
  @cache = {}
end

#key_for(entry) ⇒ Object?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Parameters:

  • entry (Object) —

    the entry to get the key for

Returns:

  • (Object, nil) —

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

Raises:

  • (NotImplementedError) 


88
89
90
 
# File 'lib/dm-core/support/ordered_set.rb', line 88

def key_for(entry)
  raise NotImplementedError, "#{self}#key_for must be implemented"
end

#valid?(entry) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Parameters:

  • entry (Object) —

    the entry to be checked

Returns:

  • (Boolean) —

    true if the entry qualifies to be added to the cache

Raises:

  • (NotImplementedError) 


75
76
77
 
# File 'lib/dm-core/support/ordered_set.rb', line 75

def valid?(entry)
  raise NotImplementedError, "#{self}#valid? must be implemented"
end