This class handles the behaviour for a document that embeds many other documents within in it as an array.
Appends a document or array of documents to the relation. Will set the parent and update the index in the process.
@example Append a document.
person.addresses << address
@example Push a document.
person.addresses.push(address)
@example Concat with other documents.
person.addresses.concat([ address_one, address_two ])
@param [ Document, Array<Document> ] *args Any number of documents.
# File lib/mongoid/relations/embedded/many.rb, line 23 def <<(*args) atomically(:$pushAll) do args.flatten.each do |doc| next unless doc append(doc) doc.save if persistable? && !_assigning? end end end
Get this relation as as its representation in the database.
@example Convert the relation to an attributes hash.
person.addresses.as_document
@return [ Array<Hash> ] The relation as stored in the db.
@since 2.0.0.rc.1
# File lib/mongoid/relations/embedded/many.rb, line 287 def as_document [].tap do |attributes| target.each do |doc| attributes << doc.as_document end end end
Builds a new document in the relation and appends it to the target. Takes an optional type if you want to specify a subclass.
@example Build a new document on the relation.
person.people.build(:name => "Bozo")
@overload build(attributes = {}, options = {}, type = nil)
@param [ Hash ] attributes The attributes to build the document with. @param [ Hash ] options The scoped assignment options. @param [ Class ] type Optional class to build the document with.
@overload build(attributes = {}, type = nil)
@param [ Hash ] attributes The attributes to build the document with. @param [ Class ] type Optional class to build the document with.
@return [ Document ] The new document.
# File lib/mongoid/relations/embedded/many.rb, line 51 def build(attributes = {}, options = {}, type = nil) if options.is_a? Class options, type = {}, options end Factory.build(type || metadata.klass, attributes, options).tap do |doc| doc.identify append(doc) yield(doc) if block_given? end end
Clear the relation. Will delete the documents from the db if they are already persisted.
@example Clear the relation.
person.addresses.clear
@return [ Many ] The empty relation.
# File lib/mongoid/relations/embedded/many.rb, line 71 def clear tap do |proxy| atomically(:$unset) { proxy.delete_all } end end
Returns a count of the number of documents in the association that have actually been persisted to the database.
Use #size if you want the total number of documents.
@example Get the count of persisted documents.
person.addresses.count
@return [ Integer ] The total number of persisted embedded docs, as
flagged by the #persisted? method.
# File lib/mongoid/relations/embedded/many.rb, line 87 def count target.select { |doc| doc.persisted? }.size end
Create a new document in the relation. This is essentially the same as doing a build then #save on the new document.
@example Create a new document in the relation.
person.movies.create(:name => "Bozo")
@overload create(attributes = {}, options = {}, type = nil)
@param [ Hash ] attributes The attributes to build the document with. @param [ Hash ] options The scoped assignment options. @param [ Class ] type Optional class to create the document with.
@overload create(attributes = {}, type = nil)
@param [ Hash ] attributes The attributes to build the document with. @param [ Class ] type Optional class to create the document with.
@return [ Document ] The newly created document.
# File lib/mongoid/relations/embedded/many.rb, line 107 def create(attributes = {}, options = {}, type = nil, &block) build(attributes, options, type, &block).tap { |doc| doc.save } end
Create a new document in the relation. This is essentially the same as doing a build then #save on the new document. If validation failed on the document an error will get raised.
@example Create the document.
person.addresses.create!(:street => "Unter der Linden")</tt>
@overload create!(attributes = {}, options = {}, type = nil)
@param [ Hash ] attributes The attributes to build the document with. @param [ Hash ] options The scoped assignment options. @param [ Class ] type Optional class to create the document with.
@overload create!(attributes = {}, type = nil)
@param [ Hash ] attributes The attributes to build the document with. @param [ Class ] type Optional class to create the document with.
@raise [ Errors::Validations ] If a validation error occured.
@return [ Document ] The newly created document.
# File lib/mongoid/relations/embedded/many.rb, line 130 def create!(attributes = {}, options = {}, type = nil, &block) build(attributes, options, type, &block).tap { |doc| doc.save! } end
Delete the supplied document from the target. This method is proxied in order to reindex the array after the operation occurs.
@example Delete the document from the relation.
person.addresses.delete(address)
@param [ Document ] document The document to be deleted.
@return [ Document, nil ] The deleted document or nil if nothing deleted.
@since 2.0.0.rc.1
# File lib/mongoid/relations/embedded/many.rb, line 145 def delete(document) target.delete_one(document).tap do |doc| if doc && !_binding? if _assigning? base.add_atomic_pull(doc) else doc.delete(:suppress => true) end unbind_one(doc) end reindex end end
Delete all the documents in the association without running callbacks.
@example Delete all documents from the relation.
person.addresses.delete_all
@example Conditionally delete documents from the relation.
person.addresses.delete_all(:conditions => { :street => "Bond" })
@param [ Hash ] conditions Conditions on which documents to delete.
@return [ Integer ] The number of documents deleted.
# File lib/mongoid/relations/embedded/many.rb, line 170 def delete_all(conditions = {}) atomically(:$pull) { remove_all(conditions, :delete) } end
Destroy all the documents in the association whilst running callbacks.
@example Destroy all documents from the relation.
person.addresses.destroy_all
@example Conditionally destroy documents from the relation.
person.addresses.destroy_all(:conditions => { :street => "Bond" })
@param [ Hash ] conditions Conditions on which documents to destroy.
@return [ Integer ] The number of documents destroyed.
# File lib/mongoid/relations/embedded/many.rb, line 185 def destroy_all(conditions = {}) atomically(:$pull) { remove_all(conditions, :destroy) } end
Finds a document in this association through several different methods.
@example Find a document by its id.
person.addresses.find(BSON::ObjectId.new)
@example Find documents for multiple ids.
person.addresses.find([ BSON::ObjectId.new, BSON::ObjectId.new ])
@example Find documents based on conditions.
person.addresses.find(:all, :conditions => { :number => 10 }) person.addresses.find(:first, :conditions => { :number => 10 }) person.addresses.find(:last, :conditions => { :number => 10 })
@param [ Array<Object> ] args Various arguments.
@return [ Array<Document>, Document ] A single or multiple documents.
# File lib/mongoid/relations/embedded/many.rb, line 206 def find(*args) criteria.find(*args) end
Get all the documents in the relation that are loaded into memory.
@example Get the in memory documents.
relation.in_memory
@return [ Array<Document> ] The documents in memory.
@since 2.1.0
# File lib/mongoid/relations/embedded/many.rb, line 237 def in_memory target end
Substitutes the supplied target documents for the existing documents in the relation.
@example Substitute the relation’s target.
person.addresses.substitute([ address ])
@param [ Array<Document> ] new_target The replacement array. @param [ true, false ] building Are we in build mode?
@return [ Many ] The proxied relation.
@since 2.0.0.rc.1
# File lib/mongoid/relations/embedded/many.rb, line 253 def substitute(replacement) tap do |proxy| if replacement.blank? if _assigning? && !proxy.empty? base.atomic_unsets.push(proxy.first.atomic_path) end proxy.clear else atomically(:$set) do if replacement.first.is_a?(Hash) replacement = Many.builder(base, metadata, replacement).build end proxy.target = replacement.compact if _assigning? base.delayed_atomic_sets[metadata.name.to_s] = proxy.as_document end proxy.target.each_with_index do |doc, index| integrate(doc) doc._index = index doc.save if base.persisted? && !_assigning? end end end end end
Get a criteria for the embedded documents without the default scoping applied.
@example Get the unscoped criteria.
person.addresses.unscoped
@return [ Criteria ] The unscoped criteria.
@since 2.2.1
# File lib/mongoid/relations/embedded/many.rb, line 304 def unscoped criteria(false) end
Instantiate a new embeds_many relation.
@example Create the new relation.
Many.new(person, addresses, metadata)
@param [ Document ] base The document this relation hangs off of. @param [ Array<Document> ] target The child documents of the relation. @param [ Metadata ] metadata The relation’s metadata
@return [ Many ] The proxy.
# File lib/mongoid/relations/embedded/many.rb, line 220 def initialize(base, target, metadata) init(base, target, metadata) do target.each_with_index do |doc, index| integrate(doc) doc._index = index end end end
Generated with the Darkfish Rdoc Generator 2.