lib/xmlrpc/datetime.rb

   1 =begin
   2 = xmlrpc/datetime.rb
   3 Copyright (C) 2001, 2002, 2003 by Michael Neumann (mneumann@ntecs.de)
   4
   5 Released under the same term of license as Ruby.
   6
   7 = Classes
   8 * ((<XMLRPC::DateTime>))
   9
  10 = XMLRPC::DateTime
  11 == Description
  12 This class is important to handle XMLRPC (('dateTime.iso8601')) values,
  13 correcly, because normal UNIX-dates (class (({Date}))) only handle dates
  14 from year 1970 on, and class (({Time})) handles dates without the time
  15 component. (({XMLRPC::DateTime})) is able to store a XMLRPC
  16 (('dateTime.iso8601')) value correctly.
  17
  18 == Class Methods
  19 --- XMLRPC::DateTime.new( year, month, day, hour, min, sec )
  20     Creates a new (({XMLRPC::DateTime})) instance with the
  21     parameters ((|year|)), ((|month|)), ((|day|)) as date and
  22     ((|hour|)), ((|min|)), ((|sec|)) as time.
  23     Raises (({ArgumentError})) if a parameter is out of range, or ((|year|)) is not
  24     of type (({Integer})).
  25
  26 == Instance Methods
  27 --- XMLRPC::DateTime#year
  28 --- XMLRPC::DateTime#month
  29 --- XMLRPC::DateTime#day
  30 --- XMLRPC::DateTime#hour
  31 --- XMLRPC::DateTime#min
  32 --- XMLRPC::DateTime#sec
  33     Return the value of the specified date/time component.
  34
  35 --- XMLRPC::DateTime#mon
  36     Alias for ((<XMLRPC::DateTime#month>)).
  37
  38 --- XMLRPC::DateTime#year=( value )
  39 --- XMLRPC::DateTime#month=( value )
  40 --- XMLRPC::DateTime#day=( value )
  41 --- XMLRPC::DateTime#hour=( value )
  42 --- XMLRPC::DateTime#min=( value )
  43 --- XMLRPC::DateTime#sec=( value )
  44     Set ((|value|)) as the new date/time component.
  45     Raises (({ArgumentError})) if ((|value|)) is out of range, or in the case
  46     of (({XMLRPC::DateTime#year=})) if ((|value|)) is not of type (({Integer})).
  47
  48 --- XMLRPC::DateTime#mon=( value )
  49     Alias for ((<XMLRPC::DateTime#month=>)).
  50
  51 --- XMLRPC::DateTime#to_time
  52     Return a (({Time})) object of the date/time which (({self})) represents.
  53     If the (('year')) is below 1970, this method returns (({nil})),
  54     because (({Time})) cannot handle years below 1970.
  55     The used timezone is GMT.
  56
  57 --- XMLRPC::DateTime#to_date
  58     Return a (({Date})) object of the date which (({self})) represents.
  59     The (({Date})) object do ((*not*)) contain the time component (only date).
  60
  61 --- XMLRPC::DateTime#to_a
  62     Returns all date/time components in an array.
  63     Returns (({[year, month, day, hour, min, sec]})).
  64 =end
  65
  66 require "date"
  67
  68 module XMLRPC
  69
  70 class DateTime
  71
  72   attr_reader :year, :month, :day, :hour, :min, :sec
  73
  74   def year= (value)
  75     raise ArgumentError, "date/time out of range" unless value.is_a? Integer
  76     @year = value
  77   end
  78
  79   def month= (value)
  80     raise ArgumentError, "date/time out of range" unless (1..12).include? value
  81     @month = value
  82   end
  83
  84   def day= (value)
  85     raise ArgumentError, "date/time out of range" unless (1..31).include? value
  86     @day = value
  87   end
  88
  89   def hour= (value)
  90     raise ArgumentError, "date/time out of range" unless (0..24).include? value
  91     @hour = value
  92   end
  93
  94   def min= (value)
  95     raise ArgumentError, "date/time out of range" unless (0..59).include? value
  96     @min = value
  97   end
  98
  99   def sec= (value)
 100     raise ArgumentError, "date/time out of range" unless (0..59).include? value
 101     @sec = value
 102   end
 103
 104   alias mon  month
 105   alias mon= month=
 106
 107
 108   def initialize(year, month, day, hour, min, sec)
 109     self.year, self.month, self.day = year, month, day
 110     self.hour, self.min, self.sec   = hour, min, sec
 111   end
 112
 113   def to_time
 114     if @year >= 1970
 115       Time.gm(*to_a)
 116     else
 117       nil
 118     end
 119   end
 120
 121   def to_date
 122     Date.new(*to_a[0,3])
 123   end
 124
 125   def to_a
 126     [@year, @month, @day, @hour, @min, @sec]
 127   end
 128
 129   def ==(o)
 130     self.to_a == Array(o) rescue false
 131   end
 132
 133 end
 134
 135
 136 end # module XMLRPC
 137
 138
 139 =begin
 140 = History
 141     $Id$
 142 =end