summaryrefslogtreecommitdiff
path: root/time.c
diff options
context:
space:
mode:
authordrbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2011-10-06 00:14:55 +0000
committerdrbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2011-10-06 00:14:55 +0000
commit0d900cecdfdaa833ab436863bbf2c3dac464d608 (patch)
tree3b2d730f9bfa94566206e522631000d320748943 /time.c
parentf365f19054cefe6b95041d3111edc37117f3e2cb (diff)
* time.c (Init_Time): Improve Time documentation. Patch by Shane
Emmons. [Ruby 1.9 - Bug #5404] * lib/time.rb: Improve time.rb documentation including Time.strptime. Patch by Shane Emmons. [Ruby 1.9 - Bug #5402] git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@33414 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'time.c')
-rw-r--r--time.c92
1 files changed, 78 insertions, 14 deletions
diff --git a/time.c b/time.c
index a18548e..00b8050 100644
--- a/time.c
+++ b/time.c
@@ -4835,20 +4835,84 @@ time_load(VALUE klass, VALUE str)
}
/*
- * <code>Time</code> is an abstraction of dates and times. Time is
- * stored internally as the number of seconds with fraction since
- * the <em>Epoch</em>, January 1, 1970 00:00 UTC.
- * Also see the library modules <code>Date</code>.
- * The <code>Time</code> class treats GMT (Greenwich Mean Time) and
- * UTC (Coordinated Universal Time)<em>[Yes, UTC really does stand for
- * Coordinated Universal Time. There was a committee involved.]</em>
- * as equivalent. GMT is the older way of referring to these
- * baseline times but persists in the names of calls on POSIX
- * systems.
- *
- * All times may have fraction. Be aware of
- * this fact when comparing times with each other---times that are
- * apparently equal when displayed may be different when compared.
+ * Time is an abstraction of dates and times. Time is stored internally as
+ * the number of seconds with fraction since the _Epoch_, January 1, 1970
+ * 00:00 UTC. Also see the library modules Date. The Time class
+ * treats GMT (Greenwich Mean Time) and UTC (Coordinated Universal Time)_[Yes,
+ * UTC really does stand for Coordinated Universal Time. There was a committee
+ * involved.]_ as equivalent. GMT is the older way of referring to these
+ * baseline times but persists in the names of calls on POSIX systems.
+ *
+ * All times may have fraction. Be aware of this fact when comparing times
+ * with each other--times that are apparently equal when displayed may be
+ * different when compared.
+ *
+ * = 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 a synonym 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 with 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
+ * Time.new(2002, 10, 31, 2, 2, 2, "+02:00") #=> 2002-10-31 02:02:02 -0200
+ *
+ * You can also use #gm, #local and #utc to infer GMT, 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 (or fraction of seconds) since the Unix
+ * Epoch[http://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 is 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 second was that from the Unix Epoc?
+ *
+ * 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
*/
void