Module: Mongoid::Persistence::Atomic

Defined in:
lib/mongoid/persistence/atomic.rb,
lib/mongoid/persistence/atomic/bit.rb,
lib/mongoid/persistence/atomic/inc.rb,
lib/mongoid/persistence/atomic/pop.rb,
lib/mongoid/persistence/atomic/pull.rb,
lib/mongoid/persistence/atomic/push.rb,
lib/mongoid/persistence/atomic/sets.rb,
lib/mongoid/persistence/atomic/unset.rb,
lib/mongoid/persistence/atomic/rename.rb,
lib/mongoid/persistence/atomic/pull_all.rb,
lib/mongoid/persistence/atomic/push_all.rb,
lib/mongoid/persistence/atomic/operation.rb,
lib/mongoid/persistence/atomic/add_to_set.rb

Overview

This module provides the explicit atomic operations helpers on the document itself.

Defined Under Namespace

Modules: Operation Classes: AddToSet, Bit, Inc, Pop, Pull, PullAll, Push, PushAll, Rename, Sets, Unset

Instance Method Summary collapse

Instance Method Details

#add_to_set(field, value, options = {}) ⇒ Array<Object>

Performs an atomic $addToSet of the provided value on the supplied field. If the field does not exist it will be initialized as an empty array.

If the value already exists on the array it will not be added.

Examples:

Add only a unique value on the field.

person.add_to_set(:aliases, "Bond")

Add only the unique values to the field.

person.add_to_set(:aliases, [ "Bond", "James" ])

Parameters:

  • field (Symbol) —

    The name of the field.

  • value (Object, Array<Object>) —

    The value or values to add.

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

    The mongo persistence options.

Returns:

  • (Array<Object>) —

    The new value of the field.

Since:

  • 2.0.0



40
41
42
 
# File 'lib/mongoid/persistence/atomic.rb', line 40

def add_to_set(field, value, options = {})
  AddToSet.new(self, field, value, options).persist
end

#bit(field, value, options = {}) ⇒ Integer

Performs an atomic $bit operation on the field with the provided hash of bitwise ops to execute in order.

Examples:

Execute a bitwise and on the field.

person.bit(:age, { :and => 12 })

Execute a bitwise or on the field.

person.bit(:age, { :or => 12 })

Execute a chain of bitwise operations.

person.bit(:age, { :and => 10, :or => 12 })

Parameters:

  • field (Symbol) —

    The name of the field.

  • value (Hash) —

    The bitwise operations to perform.

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

    The mongo persistence options.

Returns:

  • (Integer) —

    The new value of the field.

Since:

  • 2.1.0



63
64
65
 
# File 'lib/mongoid/persistence/atomic.rb', line 63

def bit(field, value, options = {})
  Bit.new(self, field, value, options).persist
end

#inc(field, value, options = {}) ⇒ Array<Object>

Performs an atomic $inc of the provided value on the supplied field. If the field does not exist it will be initialized as the provided value.

Examples:

Increment a field.

person.inc(:score, 2)

Parameters:

  • field (Symbol) —

    The name of the field.

  • value (Numeric) —

    The value to increment.

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

    The mongo persistence options.

Returns:

  • (Array<Object>) —

    The new value of the field.

Since:

  • 2.0.0



81
82
83
 
# File 'lib/mongoid/persistence/atomic.rb', line 81

def inc(field, value, options = {})
  Inc.new(self, field, value, options).persist
end

#pop(field, value, options = {}) ⇒ Array<Object>

Performs an atomic $pop of the provided value on the supplied field.

Examples:

Pop the last value from the array.

person.pop(:aliases, 1)

Pop the first value from the array.

person.pop(:aliases, -1)

Parameters:

  • field (Symbol) —

    The name of the field.

  • value (Integer) —

    Whether to pop the first or last.

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

    The mongo persistence options.

Returns:

  • (Array<Object>) —

    The new value of the field.

Since:

  • 2.1.0



101
102
103
 
# File 'lib/mongoid/persistence/atomic.rb', line 101

def pop(field, value, options = {})
  Pop.new(self, field, value, options).persist
end

#pull(field, value, options = {}) ⇒ Array<Object>

Note:

Support for a $pull with an expression is not yet supported.

Performs an atomic $pull of the provided value on the supplied field.

Examples:

Pull the value from the field.

person.pull(:aliases, "Bond")

Parameters:

  • field (Symbol) —

    The name of the field.

  • value (Object) —

    The value to pull.

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

    The mongo persistence options.

Returns:

  • (Array<Object>) —

    The new value of the field.

Since:

  • 2.1.0



120
121
122
 
# File 'lib/mongoid/persistence/atomic.rb', line 120

def pull(field, value, options = {})
  Pull.new(self, field, value, options).persist
end

#pull_all(field, value, options = {}) ⇒ Array<Object>

Performs an atomic $pullAll of the provided value on the supplied field. If the field does not exist it will be initialized as an empty array.

Examples:

Pull the values from the field.

person.pull_all(:aliases, [ "Bond", "James" ])

Parameters:

  • field (Symbol) —

    The name of the field.

  • value (Array<Object>) —

    The values to pull.

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

    The mongo persistence options.

Returns:

  • (Array<Object>) —

    The new value of the field.

Since:

  • 2.0.0



138
139
140
 
# File 'lib/mongoid/persistence/atomic.rb', line 138

def pull_all(field, value, options = {})
  PullAll.new(self, field, value, options).persist
end

#push(field, value, options = {}) ⇒ Array<Object>

Performs an atomic $push of the provided value on the supplied field. If the field does not exist it will be initialized as an empty array.

Examples:

Push a value on the field.

person.push(:aliases, "Bond")

Parameters:

  • field (Symbol) —

    The name of the field.

  • value (Object) —

    The value to push.

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

    The mongo persistence options.

Returns:

  • (Array<Object>) —

    The new value of the field.

Since:

  • 2.0.0



155
156
157
 
# File 'lib/mongoid/persistence/atomic.rb', line 155

def push(field, value, options = {})
  Push.new(self, field, value, options).persist
end

#push_all(field, value, options = {}) ⇒ Array<Object>

Performs an atomic $pushAll of the provided value on the supplied field. If the field does not exist it will be initialized as an empty array.

Examples:

Push the values onto the field.

person.push_all(:aliases, [ "Bond", "James" ])

Parameters:

  • field (Symbol) —

    The name of the field.

  • value (Array<Object>) —

    The values to push.

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

    The mongo persistence options.

Returns:

  • (Array<Object>) —

    The new value of the field.

Since:

  • 2.1.0



172
173
174
 
# File 'lib/mongoid/persistence/atomic.rb', line 172

def push_all(field, value, options = {})
  PushAll.new(self, field, value, options).persist
end

#rename(field, value, options = {}) ⇒ Object

Performs the atomic $rename from the old field to the new field name.

Examples:

Rename the field.

person.rename(:age, :years)

Parameters:

  • field (Symbol) —

    The old field name.

  • value (Symbol) —

    The new field name.

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

    The mongo persistence options.

Returns:

  • (Object) —

    The value of the new field.

Since:

  • 2.1.0



188
189
190
 
# File 'lib/mongoid/persistence/atomic.rb', line 188

def rename(field, value, options = {})
  Rename.new(self, field, value, options).persist
end

#set(field, value = nil, options = {}) ⇒ Array<Object>

Performs an atomic $set of the provided value on the supplied field. If the field does not exist it will be initialized as the provided value.

Examples:

Set a field.

person.set(:score, 2)

Parameters:

  • field (Symbol) —

    The name of the field.

  • value (Integer) (defaults to: nil) —

    The value to set.

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

    The mongo persistence options.

Returns:

  • (Array<Object>) —

    The new value of the field.

Since:

  • 2.1.0



206
207
208
 
# File 'lib/mongoid/persistence/atomic.rb', line 206

def set(field, value = nil, options = {})
  Sets.new(self, field, value, options).persist
end

#unset(*args) ⇒ nil

Performs the atomic $unset on the supplied field.

Examples:

Remove the field.
  person.unset(:age)
Remove fields age and score.
  person.unset([:age, :score])

Parameters:

  • fields (Symbol, Array<Object>) —

    The fields name.

  • options (Hash) —

    The mongo persistence options.

Returns:

  • (nil) —

    Always nil.

Since:

  • 2.1.0



224
225
226
227
228
 
# File 'lib/mongoid/persistence/atomic.rb', line 224

def unset(*args)
  fields = args.__find_args__
  options = fields[-1].is_a?(Hash) ? fields.delete_at(-1) : {}
  Unset.new(self, fields, true, options).persist
end