class CarbonDate::Date
Models a date with a precision. The conventions of the Gregorian Calendar are used to model dates.
Constants
- PRECISION
The precisions available
Attributes
Used to get and set the CarbonDate::Date.formatter
The date's day counting from 1
The date's hour in range (0..23)
The date's minute in range (0..59)
The date's month in range (1..12)
The date's precision
The date's second in range (0..59)
The date's year. Cannot be 0 as there is no 0 year in the Gregorian Calendar.
Public Class Methods
Converts from an iso8601 datetime format, with precision Dates like these are found on Wikidata (www.wikidata.org) Params: string
-> the iso8601 datetime in the form +1989-03-23T23:11:08Z precision_level
-> an integer between 0 and 14 (see CarbonDate::Date::PRECISION
) Returns: CarbonDate::Date
object
# File lib/carbon_date/date.rb, line 147 def self.iso8601(string, precision_level) p = PRECISION[precision_level] raise ArgumentError.new("Invalid precision level #{precision_level}") unless p # If there is an initial '-' symbol on the year, it needs to be treateded differenty than the other '-'. # Example: -0500-01-01 is the 1st January 500 BCE if string[0] == '-' string = string[1..(string.length - 1)] # Drop the initial '-' bce = true else bce = false end d = string.split('T').map { |x| x.split(/[-:]/) }.flatten.map(&:to_i) year = bce ? -d[0] : d[0] CarbonDate::Date.new(year, d[1], d[2], d[3], d[4], d[5], precision: p) end
Creates a new CarbonDate::Date
Params: year
- The date's year, as an integer month
- The date's month, as an integer day
- The date's day, as an integer hour
- The date's hour, as an integer minute
- The date's minute, as an integer second
- The date's second, as an integer :precision
- The date's precision, as a symbol. For avaiable options, see CarbonDate::Date::PRECISION
Raises: ArgumentError
if validations fail Returns: CarbonDate::Date
object
# File lib/carbon_date/date.rb, line 69 def initialize(year = 1970, month = 1, day = 1, hour = 0, minute = 0, second = 0, precision: :second) month = 1 if month == 0 day = 1 if day == 0 self.precision = precision self.set_date(year, month, day) self.hour = hour self.minute = minute self.second = second end
Public Instance Methods
Tests if this CarbonDate::Date
is in the past relative to the other CarbonDate::Date
Defers to DateTime#<=
# File lib/carbon_date/date.rb, line 198 def <=(another_date) self.to_datetime <= another_date.to_datetime end
Test equality of two CarbonDate::Dates For equality, the two dates have to have the same:
-
precision
-
year
-
month
-
day
-
hour
-
minute
-
second
# File lib/carbon_date/date.rb, line 191 def ==(another_date) return false if self.precision != another_date.precision self.to_datetime == another_date.to_datetime end
Tests if this CarbonDate::Date
is in the future relative to the other CarbonDate::Date
Defers to DateTime#>=
# File lib/carbon_date/date.rb, line 204 def >=(another_date) self.to_datetime >= another_date.to_datetime end
Sets the day. Calls set_date
() to ensure atomicity. Raises ArgumentError
if:
-
value is not in (1..12)
# File lib/carbon_date/date.rb, line 115 def day=(value) set_date(@year, @month, value) end
Sets the hour with validation Raises ArgumentError
unless in the range (0..23)
# File lib/carbon_date/date.rb, line 121 def hour=(value) raise ArgumentError.new "Invalid hour #{value}" unless (0..23).include? value @hour = value end
# File lib/carbon_date/date.rb, line 208 def invalid_date ArgumentError.new("Invalid date #{year}-#{month}-#{day}") end
Sets the minute with validation Raises ArgumentError
unless in the range (0..59)
# File lib/carbon_date/date.rb, line 128 def minute=(value) raise ArgumentError.new "Invalid minute #{value}" unless (0..59).include? value @minute = value end
Sets the month. Calls set_date
() to ensure atomicity. Raises ArgumentError
if:
-
value is not in (1..12)
# File lib/carbon_date/date.rb, line 108 def month=(value) set_date(@year, value, @day) end
Sets the precision Raises ArgumentError
if invalid symbol
# File lib/carbon_date/date.rb, line 81 def precision=(value) raise ArgumentError.new "Invalid precision #{value}" unless PRECISION.include? value @precision = value end
Sets the second with validation Raises ArgumentError
unless in the range (0..59)
# File lib/carbon_date/date.rb, line 135 def second=(value) raise ArgumentError.new "Invalid second #{value}" unless (0..59).include? value @second = value end
An atomic function to set the date component (year, month and day) Raises ArgumentError
if invalid date
# File lib/carbon_date/date.rb, line 88 def set_date(year, month, day) raise invalid_date if (year.nil? || year == 0 || !((1..12).include? month)) begin ::Date.new(year, month, day) rescue ArgumentError raise invalid_date end @year = year.to_i @month = month @day = day end
Convert to a standard Ruby Date
object Returns: ::Date
object
# File lib/carbon_date/date.rb, line 171 def to_date ::Date.new(@year, @month, @day) end
Convert into a standard Ruby DateTime object Returns: ::DateTime
object
# File lib/carbon_date/date.rb, line 178 def to_datetime ::DateTime.new(@year, @month, @day, @hour, @minute, @second) end
Prints a human-readable version of the date, using CarbonDate::Date.formatter
# File lib/carbon_date/date.rb, line 164 def to_s CarbonDate::Date.formatter.date_to_string(self) end
Sets the year. Calls set_date
() to ensure atomicity.
# File lib/carbon_date/date.rb, line 101 def year=(value) set_date(value, @month, @day) end