From c741ea0be7402fd709207548d78b044fb89dffd0 Mon Sep 17 00:00:00 2001 From: Nobuyoshi Nakada Date: Sun, 6 Jun 2021 12:08:54 +0900 Subject: [PATCH] timev.rb: moved class rdoc from time.c --- time.c | 212 +------------------------------------------------------ timev.rb | 208 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 209 insertions(+), 211 deletions(-) diff --git a/time.c b/time.c index f23accf957..a5c00e2aa2 100644 --- a/time.c +++ b/time.c @@ -5591,217 +5591,7 @@ rb_time_zone_abbreviation(VALUE zone, VALUE time) * nanosecond), Time works slower than when integer is used. */ -/* - * Time is an abstraction of dates and times. Time is stored internally as - * the number of seconds with subsecond since the _Epoch_, - * 1970-01-01 00:00:00 UTC. - * - * The Time class treats GMT - * (Greenwich Mean Time) and UTC (Coordinated Universal Time) as equivalent. - * GMT is the older way of referring to these baseline times but persists in - * the names of calls on POSIX systems. - * - * Note: A \Time object uses the resolution available on your system clock. - * - * All times may have subsecond. Be aware of this fact when comparing times - * with each other -- times that are apparently equal when displayed may be - * different when compared. - * (Since Ruby 2.7.0, Time#inspect shows subsecond but - * Time#to_s still doesn't show subsecond.) - * - * == Examples - * - * All of these examples were done using the EST timezone which is GMT-5. - * - * === Creating a New \Time Instance - * - * You can create a new instance of Time with Time.new. This will use the - * current system time. Time.now is an alias for this. You can also - * pass parts of the time to Time.new such as year, month, minute, etc. When - * you want to construct a time this way you must pass at least a year. If you - * pass the year with nothing else time will default to January 1 of that year - * at 00:00:00 with the current system timezone. Here are some examples: - * - * Time.new(2002) #=> 2002-01-01 00:00:00 -0500 - * Time.new(2002, 10) #=> 2002-10-01 00:00:00 -0500 - * Time.new(2002, 10, 31) #=> 2002-10-31 00:00:00 -0500 - * - * You can pass a UTC offset: - * - * Time.new(2002, 10, 31, 2, 2, 2, "+02:00") #=> 2002-10-31 02:02:02 +0200 - * - * Or a timezone object: - * - * zone = timezone("Europe/Athens") # Eastern European Time, UTC+2 - * Time.new(2002, 10, 31, 2, 2, 2, zone) #=> 2002-10-31 02:02:02 +0200 - * - * You can also use Time.local and Time.utc to infer - * local and UTC timezones instead of using the current system - * setting. - * - * You can also create a new time using Time.at which takes the number of - * seconds (with subsecond) since the {Unix - * Epoch}[https://en.wikipedia.org/wiki/Unix_time]. - * - * Time.at(628232400) #=> 1989-11-28 00:00:00 -0500 - * - * === Working with an Instance of \Time - * - * Once you have an instance of Time there is a multitude of things you can - * do with it. Below are some examples. For all of the following examples, we - * will work on the assumption that you have done the following: - * - * t = Time.new(1993, 02, 24, 12, 0, 0, "+09:00") - * - * Was that a monday? - * - * t.monday? #=> false - * - * What year was that again? - * - * t.year #=> 1993 - * - * Was it daylight savings at the time? - * - * t.dst? #=> false - * - * What's the day a year later? - * - * t + (60*60*24*365) #=> 1994-02-24 12:00:00 +0900 - * - * How many seconds was that since the Unix Epoch? - * - * t.to_i #=> 730522800 - * - * You can also do standard functions like compare two times. - * - * t1 = Time.new(2010) - * t2 = Time.new(2011) - * - * t1 == t2 #=> false - * t1 == t1 #=> true - * t1 < t2 #=> true - * t1 > t2 #=> false - * - * Time.new(2010,10,31).between?(t1, t2) #=> true - * - * == What's Here - * - * \Class \Time provides methods that are useful for: - * - * - {Creating \Time objects}[#class-Time-label-Methods+for+Creating]. - * - {Fetching \Time values}[#class-Time-label-Methods+for+Fetching]. - * - {Querying a \Time object}[#class-Time-label-Methods+for+Querying]. - * - {Comparing \Time objects}[#class-Time-label-Methods+for+Comparing]. - * - {Converting a \Time object}[#class-Time-label-Methods+for+Converting]. - * - {Rounding a \Time}[#class-Time-label-Methods+for+Rounding]. - * - * === Methods for Creating - * - * - ::new: Returns a new time from specified arguments (year, month, etc.), - * including an optional timezone value. - * - ::local (aliased as ::mktime): Same as ::new, except the - * timezone is the local timezone. - * - ::utc (aliased as ::gm): Same as ::new, except the timezone is UTC. - * - ::at: Returns a new time based on seconds since epoch. - * - ::now: Returns a new time based on the current system time. - * - #+ (plus): Returns a new time increased by the given number of seconds. - * - {-}[#method-i-2D] (minus): Returns a new time - * decreased by the given number of seconds. - * - * === Methods for Fetching - * - * - #year: Returns the year of the time. - * - #month (aliased as #mon): Returns the month of the time. - * - #mday (aliased as #day): Returns the day of the month. - * - #hour: Returns the hours value for the time. - * - #min: Returns the minutes value for the time. - * - #sec: Returns the seconds value for the time. - * - #usec (aliased as #tv_usec): Returns the number of microseconds - * in the subseconds value of the time. - * - #nsec (aliased as #tv_nsec: Returns the number of nanoseconds - * in the subsecond part of the time. - * - #subsec: Returns the subseconds value for the time. - * - #wday: Returns the integer weekday value of the time (0 == Sunday). - * - #yday: Returns the integer yearday value of the time (1 == January 1). - * - #hash: Returns the integer hash value for the time. - * - #utc_offset (aliased as #gmt_offset and #gmtoff): Returns the offset - * in seconds between time and UTC. - * - #to_f: Returns the float number of seconds since epoch for the time. - * - #to_i (aliased as #tv_sec): Returns the integer number of seconds since epoch - * for the time. - * - #to_r: Returns the Rational number of seconds since epoch for the time. - * - #zone: Returns a string representation of the timezone of the time. - * - * === Methods for Querying - * - * - #utc? (aliased as #gmt?): Returns whether the time is UTC. - * - #dst? (aliased as #isdst): Returns whether the time is DST (daylight saving time). - * - #sunday?: Returns whether the time is a Sunday. - * - #monday?: Returns whether the time is a Monday. - * - #tuesday?: Returns whether the time is a Tuesday. - * - #wednesday?: Returns whether the time is a Wednesday. - * - #thursday?: Returns whether the time is a Thursday. - * - #friday?: Returns whether time is a Friday. - * - #saturday?: Returns whether the time is a Saturday. - * - * === Methods for Comparing - * - * - {#<=>}[#method-i-3C-3D-3E]: Compares +self+ to another time. - * - #eql?: Returns whether the time is equal to another time. - * - * === Methods for Converting - * - * - #asctime (aliased as #ctime): Returns the time as a string. - * - #inspect: Returns the time in detail as a string. - * - #strftime: Returns the time as a string, according to a given format. - * - #to_a: Returns a 10-element array of values from the time. - * - #to_s: Returns a string representation of the time. - * - #getutc (aliased as #getgm): Returns a new time converted to UTC. - * - #getlocal: Returns a new time converted to local time. - * - #utc (aliased as #gmtime): Converts time to UTC in place. - * - #localtime: Converts time to local time in place. - * - * === Methods for Rounding - * - * - #round:Returns a new time with subseconds rounded. - * - #ceil: Returns a new time with subseconds raised to a ceiling. - * - #floor: Returns a new time with subseconds lowered to a floor. - * - * == Timezone Argument - * - * A timezone argument must have +local_to_utc+ and +utc_to_local+ - * methods, and may have +name+, +abbr+, and +dst?+ methods. - * - * The +local_to_utc+ method should convert a Time-like object from - * the timezone to UTC, and +utc_to_local+ is the opposite. The - * result also should be a Time or Time-like object (not necessary to - * be the same class). The #zone of the result is just ignored. - * Time-like argument to these methods is similar to a Time object in - * UTC without subsecond; it has attribute readers for the parts, - * e.g. #year, #month, and so on, and epoch time readers, #to_i. The - * subsecond attributes are fixed as 0, and #utc_offset, #zone, - * #isdst, and their aliases are same as a Time object in UTC. - * Also #to_time, #+, and #- methods are defined. - * - * The +name+ method is used for marshaling. If this method is not - * defined on a timezone object, Time objects using that timezone - * object can not be dumped by Marshal. - * - * The +abbr+ method is used by '%Z' in #strftime. - * - * The +dst?+ method is called with a +Time+ value and should return whether - * the +Time+ value is in daylight savings time in the zone. - * - * === Auto Conversion to Timezone - * - * At loading marshaled data, a timezone name will be converted to a timezone - * object by +find_timezone+ class method, if the method is defined. - * - * Similarly, that class method will be called when a timezone argument does - * not have the necessary methods mentioned above. - */ - +// void Init_Time(void) { diff --git a/timev.rb b/timev.rb index 07dd208756..d48c7976e9 100644 --- a/timev.rb +++ b/timev.rb @@ -1,3 +1,211 @@ +# Time is an abstraction of dates and times. Time is stored internally as +# the number of seconds with subsecond since the _Epoch_, +# 1970-01-01 00:00:00 UTC. +# +# The Time class treats GMT +# (Greenwich Mean Time) and UTC (Coordinated Universal Time) as equivalent. +# GMT is the older way of referring to these baseline times but persists in +# the names of calls on POSIX systems. +# +# Note: A \Time object uses the resolution available on your system clock. +# +# All times may have subsecond. Be aware of this fact when comparing times +# with each other -- times that are apparently equal when displayed may be +# different when compared. +# (Since Ruby 2.7.0, Time#inspect shows subsecond but +# Time#to_s still doesn't show subsecond.) +# +# == Examples +# +# All of these examples were done using the EST timezone which is GMT-5. +# +# === Creating a New \Time Instance +# +# You can create a new instance of Time with Time.new. This will use the +# current system time. Time.now is an alias for this. You can also +# pass parts of the time to Time.new such as year, month, minute, etc. When +# you want to construct a time this way you must pass at least a year. If you +# pass the year with nothing else time will default to January 1 of that year +# at 00:00:00 with the current system timezone. Here are some examples: +# +# Time.new(2002) #=> 2002-01-01 00:00:00 -0500 +# Time.new(2002, 10) #=> 2002-10-01 00:00:00 -0500 +# Time.new(2002, 10, 31) #=> 2002-10-31 00:00:00 -0500 +# +# You can pass a UTC offset: +# +# Time.new(2002, 10, 31, 2, 2, 2, "+02:00") #=> 2002-10-31 02:02:02 +0200 +# +# Or a timezone object: +# +# zone = timezone("Europe/Athens") # Eastern European Time, UTC+2 +# Time.new(2002, 10, 31, 2, 2, 2, zone) #=> 2002-10-31 02:02:02 +0200 +# +# You can also use Time.local and Time.utc to infer +# local and UTC timezones instead of using the current system +# setting. +# +# You can also create a new time using Time.at which takes the number of +# seconds (with subsecond) since the {Unix +# Epoch}[https://en.wikipedia.org/wiki/Unix_time]. +# +# Time.at(628232400) #=> 1989-11-28 00:00:00 -0500 +# +# === Working with an Instance of \Time +# +# Once you have an instance of Time there is a multitude of things you can +# do with it. Below are some examples. For all of the following examples, we +# will work on the assumption that you have done the following: +# +# t = Time.new(1993, 02, 24, 12, 0, 0, "+09:00") +# +# Was that a monday? +# +# t.monday? #=> false +# +# What year was that again? +# +# t.year #=> 1993 +# +# Was it daylight savings at the time? +# +# t.dst? #=> false +# +# What's the day a year later? +# +# t + (60*60*24*365) #=> 1994-02-24 12:00:00 +0900 +# +# How many seconds was that since the Unix Epoch? +# +# t.to_i #=> 730522800 +# +# You can also do standard functions like compare two times. +# +# t1 = Time.new(2010) +# t2 = Time.new(2011) +# +# t1 == t2 #=> false +# t1 == t1 #=> true +# t1 < t2 #=> true +# t1 > t2 #=> false +# +# Time.new(2010,10,31).between?(t1, t2) #=> true +# +# == What's Here +# +# \Class \Time provides methods that are useful for: +# +# - {Creating \Time objects}[#class-Time-label-Methods+for+Creating]. +# - {Fetching \Time values}[#class-Time-label-Methods+for+Fetching]. +# - {Querying a \Time object}[#class-Time-label-Methods+for+Querying]. +# - {Comparing \Time objects}[#class-Time-label-Methods+for+Comparing]. +# - {Converting a \Time object}[#class-Time-label-Methods+for+Converting]. +# - {Rounding a \Time}[#class-Time-label-Methods+for+Rounding]. +# +# === Methods for Creating +# +# - ::new: Returns a new time from specified arguments (year, month, etc.), +# including an optional timezone value. +# - ::local (aliased as ::mktime): Same as ::new, except the +# timezone is the local timezone. +# - ::utc (aliased as ::gm): Same as ::new, except the timezone is UTC. +# - ::at: Returns a new time based on seconds since epoch. +# - ::now: Returns a new time based on the current system time. +# - #+ (plus): Returns a new time increased by the given number of seconds. +# - {-}[#method-i-2D] (minus): Returns a new time +# decreased by the given number of seconds. +# +# === Methods for Fetching +# +# - #year: Returns the year of the time. +# - #month (aliased as #mon): Returns the month of the time. +# - #mday (aliased as #day): Returns the day of the month. +# - #hour: Returns the hours value for the time. +# - #min: Returns the minutes value for the time. +# - #sec: Returns the seconds value for the time. +# - #usec (aliased as #tv_usec): Returns the number of microseconds +# in the subseconds value of the time. +# - #nsec (aliased as #tv_nsec: Returns the number of nanoseconds +# in the subsecond part of the time. +# - #subsec: Returns the subseconds value for the time. +# - #wday: Returns the integer weekday value of the time (0 == Sunday). +# - #yday: Returns the integer yearday value of the time (1 == January 1). +# - #hash: Returns the integer hash value for the time. +# - #utc_offset (aliased as #gmt_offset and #gmtoff): Returns the offset +# in seconds between time and UTC. +# - #to_f: Returns the float number of seconds since epoch for the time. +# - #to_i (aliased as #tv_sec): Returns the integer number of seconds since epoch +# for the time. +# - #to_r: Returns the Rational number of seconds since epoch for the time. +# - #zone: Returns a string representation of the timezone of the time. +# +# === Methods for Querying +# +# - #utc? (aliased as #gmt?): Returns whether the time is UTC. +# - #dst? (aliased as #isdst): Returns whether the time is DST (daylight saving time). +# - #sunday?: Returns whether the time is a Sunday. +# - #monday?: Returns whether the time is a Monday. +# - #tuesday?: Returns whether the time is a Tuesday. +# - #wednesday?: Returns whether the time is a Wednesday. +# - #thursday?: Returns whether the time is a Thursday. +# - #friday?: Returns whether time is a Friday. +# - #saturday?: Returns whether the time is a Saturday. +# +# === Methods for Comparing +# +# - {#<=>}[#method-i-3C-3D-3E]: Compares +self+ to another time. +# - #eql?: Returns whether the time is equal to another time. +# +# === Methods for Converting +# +# - #asctime (aliased as #ctime): Returns the time as a string. +# - #inspect: Returns the time in detail as a string. +# - #strftime: Returns the time as a string, according to a given format. +# - #to_a: Returns a 10-element array of values from the time. +# - #to_s: Returns a string representation of the time. +# - #getutc (aliased as #getgm): Returns a new time converted to UTC. +# - #getlocal: Returns a new time converted to local time. +# - #utc (aliased as #gmtime): Converts time to UTC in place. +# - #localtime: Converts time to local time in place. +# +# === Methods for Rounding +# +# - #round:Returns a new time with subseconds rounded. +# - #ceil: Returns a new time with subseconds raised to a ceiling. +# - #floor: Returns a new time with subseconds lowered to a floor. +# +# == Timezone Argument +# +# A timezone argument must have +local_to_utc+ and +utc_to_local+ +# methods, and may have +name+, +abbr+, and +dst?+ methods. +# +# The +local_to_utc+ method should convert a Time-like object from +# the timezone to UTC, and +utc_to_local+ is the opposite. The +# result also should be a Time or Time-like object (not necessary to +# be the same class). The #zone of the result is just ignored. +# Time-like argument to these methods is similar to a Time object in +# UTC without subsecond; it has attribute readers for the parts, +# e.g. #year, #month, and so on, and epoch time readers, #to_i. The +# subsecond attributes are fixed as 0, and #utc_offset, #zone, +# #isdst, and their aliases are same as a Time object in UTC. +# Also #to_time, #+, and #- methods are defined. +# +# The +name+ method is used for marshaling. If this method is not +# defined on a timezone object, Time objects using that timezone +# object can not be dumped by Marshal. +# +# The +abbr+ method is used by '%Z' in #strftime. +# +# The +dst?+ method is called with a +Time+ value and should return whether +# the +Time+ value is in daylight savings time in the zone. +# +# === Auto Conversion to Timezone +# +# At loading marshaled data, a timezone name will be converted to a timezone +# object by +find_timezone+ class method, if the method is defined. +# +# Similarly, that class method will be called when a timezone argument does +# not have the necessary methods mentioned above. class Time # Creates a new \Time object from the current system time. # This is the same as Time.new without arguments.