Class: CiteProc::Date::DateParts

Inherits:
Struct
  • Object
show all
Includes:
Comparable
Defined in:
lib/citeproc/date.rb

Overview

Represents the individual parts of a date (i.e., year, month, day). There is a sublte difference between CiteProc dates (and date parts) and regular Ruby dates, because a Ruby date will always contain valid year, month and date values, whereas CiteProc dates may leave the month and day parts empty. That is to say, CiteProc distinguishes between the first of May 1955 and the month of May 1955 - a distinction that is not supported by regular Ruby dates.

may_1955 = CiteProc::Date::DateParts.new(1955, 5)
first_of_may_1955 = CiteProc::Date::DateParts.new(1955, 5, 1)

may_1955 < first_of_may_1955
#-> true

Date.new(1955, 5) < Date.new(1955, 5, 1)
#-> false

The above example shows that a month’s sort order is less than a day in that month, whereas, with Ruby date’s there is no such distinction.

The DateParts class encapsulates the year, month and day parts of a date; it is used internally by CiteProc::Date variables and not supposed to be used in an external context.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(*arguments) ⇒ DateParts

Returns a new instance of DateParts.



78
79
80
81
82
83
84
85
 
# File 'lib/citeproc/date.rb', line 78

def initialize(*arguments)
  if arguments.length == 1 && arguments[0].is_a?(::Date)
    d = arguments[0]
    super(d.year, d.month, d.day)
  else
    super(*arguments.map(&:to_i))
  end
end

Instance Attribute Details

#day ⇒ Object

Returns the value of attribute day

Returns:

  • (Object) —

    the current value of day



75
76
77
 
# File 'lib/citeproc/date.rb', line 75

def day
  @day
end

#month ⇒ Object

Returns the value of attribute month

Returns:

  • (Object) —

    the current value of month



75
76
77
 
# File 'lib/citeproc/date.rb', line 75

def month
  @month
end

#year ⇒ Object

Returns the value of attribute year

Returns:

  • (Object) —

    the current value of year



75
76
77
 
# File 'lib/citeproc/date.rb', line 75

def year
  @year
end

Instance Method Details

#<=>(other) ⇒ Fixnum?

Compares the date parts with the passed-in date.

Parameters:

Returns:

  • (Fixnum, nil) —

    the result of the comparison (-1, 0, 1 or nil)



149
150
151
152
153
154
155
156
157
158
 
# File 'lib/citeproc/date.rb', line 149

def <=>(other)
  case
  when other.is_a?(DateParts)
    to_citeproc <=> other.to_citeproc
  when other.respond_to?(:to_date)
    to_date <=> other.to_date
  else
    nil
  end
end

#ad? ⇒ Boolean

A date is said to be AD when it is in the first millennium, i.e., between 1 and 1000 AD

Returns:

  • (Boolean) —

    whether or not the date is AD



128
129
130
 
# File 'lib/citeproc/date.rb', line 128

def ad?
  !bc? && year < 1000
end

#bc? ⇒ Boolean

A date is said to be BC when the year is defined and less than zero.

Returns:

  • (Boolean) —

    whether or not the date is BC



121
122
123
 
# File 'lib/citeproc/date.rb', line 121

def bc?
  !!(year && year < 0)
end

#empty? ⇒ Boolean

Returns whether or not the date parts are unset.

Returns:

  • (Boolean) —

    whether or not the date parts are unset



108
109
110
 
# File 'lib/citeproc/date.rb', line 108

def empty?
  to_citeproc.empty?
end

#initialize_copy(other) ⇒ Object 



87
88
89
 
# File 'lib/citeproc/date.rb', line 87

def initialize_copy(other)
  update(other)
end

#inspect ⇒ String

Returns a human-readable representation of the object.

Returns:

  • (String) —

    a human-readable representation of the object



192
193
194
 
# File 'lib/citeproc/date.rb', line 192

def inspect
  "#<DateParts #{to_s}>"
end

#open? ⇒ Boolean

In the current CiteProc specification, date parts consisting of zeroes are used to designate open ranges.

Returns:

  • (Boolean) —

    whether or not the this is an open-end date



115
116
117
 
# File 'lib/citeproc/date.rb', line 115

def open?
  to_citeproc.include?(0)
end

#strftime(format = '%F') ⇒ String?

Formats the date parts according to the passed-in format string.

Parameters:

  • format (String) (defaults to: '%F') —

    a format string

Returns:

  • (String, nil) —

    the formatted date string; nil if the date parts are not a valid date.



136
137
138
139
140
141
142
143
144
 
# File 'lib/citeproc/date.rb', line 136

def strftime(format = '%F')
  d = to_date

  if d.nil?
    nil
  else
    d.strftime(format)
  end
end

#to_citeproc ⇒ Array<Fixnum>

Returns the list of date parts.

Returns:

  • (Array<Fixnum>) —

    the list of date parts



182
183
184
 
# File 'lib/citeproc/date.rb', line 182

def to_citeproc
  take_while { |p| !p.nil? }
end

#to_date ⇒ ::Date? Also known as: to_ruby

Convert the date parts into a proper Ruby date object; if the date parts are empty, contain zero or are otherwise invalid, nil will be returned instead.

Returns:

  • (::Date, nil) —

    the date parts as a Ruby date object



164
165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/citeproc/date.rb', line 164

def to_date
  parts = to_citeproc

  if parts.empty? || parts.include?(0)
    nil
  else
    begin
      ::Date.new(*parts)
    rescue
      # Catch invalid dates (e.g., if the month is 13).
      nil
    end
  end
end

#to_s ⇒ String

Returns the date parts as a string.

Returns:

  • (String) —

    the date parts as a string



187
188
189
 
# File 'lib/citeproc/date.rb', line 187

def to_s
  to_citeproc.inspect
end

#update(parts) ⇒ self

Update the date parts with the passed-in values.

Parameters:

  • parts (Array, #each_pair) —

    an ordered list of date parts (year, month, day) or a Hash containing the mapping

Returns:

  • (self) 


95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/citeproc/date.rb', line 95

def update(parts)
  unless parts.respond_to?(:each_pair)
    parts = Hash[DateParts.members.zip(parts)]
  end

  parts.each_pair do |part, value|
    self[part] = value.nil? ? nil : value.to_i
  end

  self
end