Class: Mongoid::Association::Referenced::HasMany::Targets::Enumerable

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Enumerable
Defined in:
lib/mongoid/association/referenced/has_many/enumerable.rb

Overview

This class is the wrapper for all referenced associations that have a target that can be a criteria or array of _loaded documents. This handles both cases or a combination of the two.

Since:

  • 7.0

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(target, base = nil, association = nil) ⇒ Enumerable

Initialize the new enumerable either with a criteria or an array.

Examples:

Initialize the enumerable with a criteria.

Enumberable.new(Post.where(:person_id => id))

Initialize the enumerable with an array.

Enumerable.new([ post ])

Parameters:

Since:

  • 2.1.0



256
257
258
259
260
261
262
263
264
265
266
267
268
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 256

def initialize(target, base = nil, association = nil)
  @_base = base
  @_association = association
  if target.is_a?(Criteria)
    @_added, @executed, @_loaded, @_unloaded = {}, false, {}, target
  else
    @_added, @executed = {}, true
    @_loaded = target.inject({}) do |_target, doc|
      _target[doc._id] = doc if doc
      _target
    end
  end
end

Instance Attribute Details

#_added ⇒ Object

The three main instance variables are collections of documents.

Since:

  • 7.0



22
23
24
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 22

def _added
  @_added
end

#_added Documents that have been appended.(Documentsthathavebeenappended.) ⇒ Object

The three main instance variables are collections of documents.



22
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 22

attr_accessor :_added, :_loaded, :_unloaded

#_loaded ⇒ Object

The three main instance variables are collections of documents.

Since:

  • 7.0



22
23
24
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 22

def _loaded
  @_loaded
end

#_loaded Persisted documents that have been _loaded.(Persisteddocumentsthathavebeen_loaded.) ⇒ Object

The three main instance variables are collections of documents.



22
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 22

attr_accessor :_added, :_loaded, :_unloaded

#_unloaded ⇒ Object

The three main instance variables are collections of documents.

Since:

  • 7.0



22
23
24
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 22

def _unloaded
  @_unloaded
end

#_unloaded A criteria representing persisted docs.(Acriteriarepresentingpersisteddocs.) ⇒ Object

The three main instance variables are collections of documents.



22
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 22

attr_accessor :_added, :_loaded, :_unloaded

Instance Method Details

#<<(document) ⇒ Document Also known as: push

Append a document to the enumerable.

Examples:

Append the document.

enumerable << document

Parameters:

  • document (Document) —

    The document to append.

Returns:

Since:

  • 2.1.0



66
67
68
69
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 66

def <<(document)
  _added[document._id] = document
  self
end

#==(other) ⇒ true, false

Check if the enumerable is equal to the other object.

Examples:

Check equality.

enumerable == []

Parameters:

Returns:

  • (true, false) —

    If the objects are equal.

Since:

  • 2.1.0



36
37
38
39
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 36

def ==(other)
  return false unless other.respond_to?(:entries)
  entries == other.entries
end

#===(other) ⇒ true, false

Check equality of the enumerable against the provided object for case statements.

Examples:

Check case equality.

enumerable === Array

Parameters:

  • other (Object) —

    The object to check.

Returns:

  • (true, false) —

    If the objects are equal in a case.

Since:

  • 3.1.4



52
53
54
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 52

def ===(other)
  other.class == Class ? (Array == other || Enumerable == other) : self == other
end

#_loaded? ⇒ true, false

Has the enumerable been _loaded? This will be true if the criteria has been executed or we manually load the entire thing.

Examples:

Is the enumerable _loaded?

enumerable._loaded?

Returns:

  • (true, false) —

    If the enumerable has been _loaded.

Since:

  • 2.1.0



361
362
363
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 361

def _loaded?
  !!@executed
end

#as_json(options = {}) ⇒ Hash

Send #as_json to the entries, without encoding.

Examples:

Get the enumerable as json.

enumerable.as_json

Parameters:

  • options (Hash) (defaults to: {}) —

    Optional parameters.

Returns:

  • (Hash) —

    The entries all _loaded as a hash.

Since:

  • 2.2.0



475
476
477
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 475

def as_json(options = {})
  entries.as_json(options)
end

#clear ⇒ Array<Document>

Clears out all the documents in this enumerable. If passed a block it will yield to each document that is in memory.

Examples:

Clear out the enumerable.

enumerable.clear

Clear out the enumerable with a block.

enumerable.clear do |doc|
  doc.unbind
end

Returns:

  • (Array<Document>) —

    The cleared out _added docs.

Since:

  • 2.1.0



87
88
89
90
91
92
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 87

def clear
  if block_given?
    in_memory { |doc| yield(doc) }
  end
  _loaded.clear and _added.clear
end

#clone ⇒ Array<Document>

Note:

This loads all documents into memory.

Clones each document in the enumerable.

Examples:

Clone the enumerable.

enumerable.clone

Returns:

  • (Array<Document>) —

    An array clone of the enumerable.

Since:

  • 2.1.6



104
105
106
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 104

def clone
  collect { |doc| doc.clone }
end

#delete(document) {|doc| ... } ⇒ Document

Delete the supplied document from the enumerable.

Examples:

Delete the document.

enumerable.delete(document)

Parameters:

  • document (Document) —

    The document to delete.

Yields:

  • (doc)

Returns:

Since:

  • 2.1.0



118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 118

def delete(document)
  doc = (_loaded.delete(document._id) || _added.delete(document._id))
  unless doc
    if _unloaded && _unloaded.where(_id: document._id).exists?
      yield(document) if block_given?
      return document
    end
  end
  yield(doc) if block_given?
  doc
end

#delete_if(&block) ⇒ Array<Document>

Note:

This operation loads all documents from the database.

Deletes every document in the enumerable for where the block returns true.

Examples:

Delete all matching documents.

enumerable.delete_if do |doc|
  dod._id == _id
end

Returns:

  • (Array<Document>) —

    The remaining docs.

Since:

  • 2.1.0



143
144
145
146
147
148
149
150
151
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 143

def delete_if(&block)
  load_all!
  deleted = in_memory.select(&block)
  deleted.each do |doc|
    _loaded.delete(doc._id)
    _added.delete(doc._id)
  end
  self
end

#each ⇒ true

Iterating over this enumerable has to handle a few different scenarios.

If the enumerable has its criteria _loaded into memory then it yields to all the _loaded docs and all the _added docs.

If the enumerable has not _loaded the criteria then it iterates over the cursor while loading the documents and then iterates over the _added docs.

If no block is passed then it returns an enumerator containing all docs.

Examples:

Iterate over the enumerable.

enumerable.each do |doc|
  puts doc
end

return an enumerator containing all the docs


a = enumerable.each

Returns:

  • (true) —

    That the enumerable is now _loaded.

Since:

  • 2.1.0



178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 178

def each
  unless block_given?
    return to_enum
  end
  if _loaded?
    _loaded.each_pair do |id, doc|
      document = _added.delete(doc._id) || doc
      set_base(document)
      yield(document)
    end
  else
    unloaded_documents.each do |doc|
      document = _added.delete(doc._id) || _loaded.delete(doc._id) || doc
      _loaded[document._id] = document
      set_base(document)
      yield(document)
    end
  end
  _added.each_pair do |id, doc|
    yield(doc)
  end
  @executed = true
end

#empty? ⇒ true, false

Is the enumerable empty? Will determine if the count is zero based on whether or not it is _loaded.

Examples:

Is the enumerable empty?

enumerable.empty?

Returns:

  • (true, false) —

    If the enumerable is empty.

Since:

  • 2.1.0



211
212
213
214
215
216
217
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 211

def empty?
  if _loaded?
    in_memory.count == 0
  else
    _unloaded.count + _added.count == 0
  end
end

#first(opts = {}) ⇒ Document

Note:

Automatically adding a sort on _id when no other sort is defined on the criteria has the potential to cause bad performance issues. If you experience unexpected poor performance when using #first or #last, use the option { id_sort: :none }. Be aware that #first/#last won’t guarantee order in this case.

Get the first document in the enumerable. Will check the persisted documents first. Does not load the entire enumerable.

Examples:

Get the first document.

enumerable.first

Parameters:

  • opts (Hash) (defaults to: {}) —

    The options for the query returning the first document.

Options Hash (opts):

  • :id_sort (:none) —

    Don’t apply a sort on _id.

Returns:

  • (Document) —

    The first document found.

Since:

  • 2.1.0



238
239
240
241
242
243
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 238

def first(opts = {})
  _loaded.try(:values).try(:first) ||
      _added[(ul = _unloaded.try(:first, opts)).try(:id)] ||
      ul ||
      _added.values.try(:first)
end

#in_memory ⇒ Array<Document>

Note:

When passed a block it yields to each document.

Return all the documents in the enumerable that have been _loaded or _added.

Examples:

Get the in memory docs.

enumerable.in_memory

Returns:

  • (Array<Document>) —

    The in memory docs.

Since:

  • 2.1.0



309
310
311
312
313
314
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 309

def in_memory
  docs = (_loaded.values + _added.values)
  docs.each do |doc|
    yield(doc) if block_given?
  end
end

#include?(doc) ⇒ true, false

Does the target include the provided document?

Examples:

Does the target include the document?

enumerable.include?(document)

Parameters:

  • doc (Document) —

    The document to check.

Returns:

  • (true, false) —

    If the document is in the target.

Since:

  • 3.0.0



280
281
282
283
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 280

def include?(doc)
  return super unless _unloaded
  _unloaded.where(_id: doc._id).exists? || _added.has_key?(doc._id)
end

#inspect ⇒ String

Inspection will just inspect the entries for nice array-style printing.

Examples:

Inspect the enumerable.

enumerable.inspect

Returns:

  • (String) —

    The inspected enum.

Since:

  • 2.1.0



294
295
296
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 294

def inspect
  entries.inspect
end

#last(opts = {}) ⇒ Document

Note:

Automatically adding a sort on _id when no other sort is defined on the criteria has the potential to cause bad performance issues. If you experience unexpected poor performance when using #first or #last, use the option { id_sort: :none }. Be aware that #first/#last won’t guarantee order in this case.

Get the last document in the enumerable. Will check the new documents first. Does not load the entire enumerable.

Examples:

Get the last document.

enumerable.last

Parameters:

  • opts (Hash) (defaults to: {}) —

    The options for the query returning the first document.

Options Hash (opts):

  • :id_sort (:none) —

    Don’t apply a sort on _id.

Returns:

  • (Document) —

    The last document found.

Since:

  • 2.1.0



335
336
337
338
339
340
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 335

def last(opts = {})
  _added.values.try(:last) ||
      _loaded.try(:values).try(:last) ||
      _added[(ul = _unloaded.try(:last, opts)).try(:id)] ||
      ul
end

#marshal_dump ⇒ Array<Object>

Provides the data needed to Marshal.dump an enumerable proxy.

Examples:

Dump the proxy.

Marshal.dump(proxy)

Returns:

  • (Array<Object>) —

    The dumped data.

Since:

  • 3.0.15



373
374
375
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 373

def marshal_dump
  [_added, _loaded, _unloaded, @executed]
end

#marshal_load(data) ⇒ Array<Object>

Loads the data needed to Marshal.load an enumerable proxy.

Examples:

Load the proxy.

Marshal.load(proxy)

Returns:

  • (Array<Object>) —

    The dumped data.

Since:

  • 3.0.15



385
386
387
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 385

def marshal_load(data)
  @_added, @_loaded, @_unloaded, @executed = data
end

#reset ⇒ false

Reset the enumerable back to its persisted state.

Examples:

Reset the enumerable.

enumerable.reset

Returns:

  • (false) —

    Always false.

Since:

  • 2.1.0



397
398
399
400
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 397

def reset
  _loaded.clear and _added.clear
  @executed = false
end

#reset_unloaded(criteria) ⇒ Object

Resets the underlying unloaded criteria object with a new one. Used my HABTM associations to keep the underlying array in sync.

Examples:

Reset the unloaded documents.

enumerable.reset_unloaded(criteria)

Parameters:

  • criteria (Criteria) —

    The criteria to replace with.

Since:

  • 3.0.14



411
412
413
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 411

def reset_unloaded(criteria)
  @_unloaded = criteria if _unloaded.is_a?(Criteria)
end

#respond_to?(name, include_private = false) ⇒ true, false

Does this enumerable respond to the provided method?

Examples:

Does the enumerable respond to the method?

enumerable.respond_to?(:sum)

Parameters:

  • name (String, Symbol) —

    The name of the method.

  • include_private (true, false) (defaults to: false) —

    Whether to include private methods.

Returns:

  • (true, false) —

    Whether the enumerable responds.

Since:

  • 2.1.0



427
428
429
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 427

def respond_to?(name, include_private = false)
  [].respond_to?(name, include_private) || super
end

#size ⇒ Integer Also known as: length

Gets the total size of this enumerable. This is a combination of all the persisted and unpersisted documents.

Examples:

Get the size.

enumerable.size

Returns:

  • (Integer) —

    The size of the enumerable.

Since:

  • 2.1.0



440
441
442
443
444
445
446
447
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 440

def size
  count = (_unloaded ? _unloaded.count : _loaded.count)
  if count.zero?
    count + _added.count
  else
    count + _added.values.count { |d| d.new_record? }
  end
end

#to_json(options = {}) ⇒ String

Send #to_json to the entries.

Examples:

Get the enumerable as json.

enumerable.to_json

Parameters:

  • options (Hash) (defaults to: {}) —

    Optional parameters.

Returns:

  • (String) —

    The entries all _loaded as a string.

Since:

  • 2.2.0



461
462
463
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 461

def to_json(options = {})
  entries.to_json(options)
end

#uniq ⇒ Array<Document>

Note:

This operation loads all documents from the database.

Return all the unique documents in the enumerable.

Examples:

Get all the unique documents.

enumerable.uniq

Returns:

  • (Array<Document>) —

    The unique documents.

Since:

  • 2.1.0



489
490
491
 
# File 'lib/mongoid/association/referenced/has_many/enumerable.rb', line 489

def uniq
  entries.uniq
end