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

formatter[RW]

Used to get and set the CarbonDate::Date.formatter

day[R]

The date's day counting from 1

hour[R]

The date's hour in range (0..23)

minute[R]

The date's minute in range (0..59)

month[R]

The date's month in range (1..12)

precision[R]

The date's precision

second[R]

The date's second in range (0..59)

year[R]

The date's year. Cannot be 0 as there is no 0 year in the Gregorian Calendar.

Public Class Methods

iso8601(string, precision_level) click to toggle source

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
new(year = 1970, month = 1, day = 1, hour = 0, minute = 0, second = 0, precision: :second) click to toggle source

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

<=(another_date) click to toggle source

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
==(another_date) click to toggle source

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
>=(another_date) click to toggle source

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
day=(value) click to toggle source

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
hour=(value) click to toggle source

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
invalid_date() click to toggle source
# File lib/carbon_date/date.rb, line 208
def invalid_date
  ArgumentError.new("Invalid date #{year}-#{month}-#{day}")
end
minute=(value) click to toggle source

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
month=(value) click to toggle source

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
precision=(value) click to toggle source

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
second=(value) click to toggle source

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
set_date(year, month, day) click to toggle source

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
to_date() click to toggle source

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
to_datetime() click to toggle source

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
to_s() click to toggle source

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
year=(value) click to toggle source

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