123456789_123456789_123456789_123456789_123456789_

Class: ActiveModel::Type::DateTime

Overview

Active Model DateTime Type

::ActiveModel::Attribute type to represent dates and times. It is registered under the :datetime key.

class Event
  include ActiveModel::Attributes

  attribute :start, :datetime
end

event = Event.new
event.start = "Wed, 04 Sep 2013 03:00:00 EAT"

event.start.class # => Time
event.start.year  # => 2013
event.start.month # => 9
event.start.day   # => 4
event.start.hour  # => 3
event.start.min   # => 0
event.start.sec   # => 0
event.start.zone  # => "EAT"

String values are parsed using the ISO 8601 datetime format. Partial time-only formats are also accepted.

event.start = "06:07:08+09:00"
event.start.utc # => 1999-12-31 21:07:08 UTC

The degree of sub-second precision can be customized when declaring an attribute:

class Event
  include ActiveModel::Attributes

  attribute :start, :datetime, precision: 4
end

Constant Summary

Helpers::TimeValue - Included

ISO_DATETIME

Class Method Summary

Value - Inherited

.new

Initializes a type with three basic configuration settings: precision, limit, and scale.

Instance Attribute Summary

Helpers::Timezone - Included

Value - Inherited

#limit, #precision, #scale,
#binary?

These predicates are not documented, as I need to look further into their use, and see if they can be removed entirely.

#mutable?, #serialized?

Instance Method Summary

Helpers::TimeValue - Included

#apply_seconds_precision, #serialize_cast_value, #type_cast_for_schema, #user_input_in_time_zone,
#fast_string_to_time

BUG: Wrapping the Time object with Time.at because Time.new with in: in Ruby 3.2.0 used to return an invalid Time object see: bugs.ruby-lang.org/issues/19292.

#new_time

Helpers::Timezone - Included

Value - Inherited

#==, #as_json, #assert_valid_value,
#cast

::ActiveModel::Type casts a value from user input (e.g. from a setter).

#changed?

Determines whether a value has changed for dirty checking.

#changed_in_place?

Determines whether the mutable value has been modified since it was read.

#deserialize

Converts a value from database input to the appropriate ruby type.

#eql?

Alias for Value#==.

#hash,
#serializable?

Returns true if this type can convert value to a type that is usable by the database.

#serialize

Casts a value from the ruby type to a type that the database knows how to understand.

#type

Returns the unique type name as a ::Symbol.

#cast_value

Convenience method for types which do not need separate type casting behavior for user and database inputs.

#force_equality?, #map,
#type_cast_for_schema

::ActiveModel::Type casts a value for schema dumping.

#value_constructed_by_mass_assignment?

SerializeCastValue - Included

Constructor Details

This class inherits a constructor from ActiveModel::Type::Value

Instance Method Details

#cast_value(value) (private)

[ GitHub ]

  
# File 'activemodel/lib/active_model/type/date_time.rb', line 54

def cast_value(value)
  return apply_seconds_precision(value) unless value.is_a?(::String)
  return if value.empty?

  fast_string_to_time(value) || fallback_string_to_time(value)
end

#fallback_string_to_time(string) (private)

[ GitHub ]

  
# File 'activemodel/lib/active_model/type/date_time.rb', line 67

def fallback_string_to_time(string)
  time_hash = begin
    ::Date._parse(string)
  rescue ArgumentError
  end
  return unless time_hash

  time_hash[:sec_fraction] = microseconds(time_hash)

  new_time(*time_hash.values_at(:year, :mon, :mday, :hour, :min, :sec, :sec_fraction, :offset))
end

#microseconds(time) (private)

‘0.123456’ -> 123456 ‘1.123456’ -> 123456

[ GitHub ]

  
# File 'activemodel/lib/active_model/type/date_time.rb', line 63

def microseconds(time)
  time[:sec_fraction] ? (time[:sec_fraction] * 1_000_000).to_i : 0
end

#type

[ GitHub ]

  
# File 'activemodel/lib/active_model/type/date_time.rb', line 49

def type
  :datetime
end

#value_from_multiparameter_assignment(values_hash) (private)

[ GitHub ]

  
# File 'activemodel/lib/active_model/type/date_time.rb', line 79

def value_from_multiparameter_assignment(values_hash)
  missing_parameters = [1, 2, 3].delete_if { |key| values_hash.key?(key) }
  unless missing_parameters.empty?
    raise ArgumentError, "Provided hash #{values_hash} doesn't contain necessary keys: #{missing_parameters}"
  end
  super
end