From cf53cc75de27a606160eb7e4a52f5436e1054070 Mon Sep 17 00:00:00 2001 From: Shane Emmons Date: Tue, 4 Oct 2011 10:30:27 -0400 Subject: [PATCH 1/2] enhancing documentation for Time extension in stdlib --- lib/time.rb | 146 +++++++++++++++++++++++++++++++++++++++++++++++------------ 1 files changed, 117 insertions(+), 29 deletions(-) diff --git a/lib/time.rb b/lib/time.rb index 4eb888a..112c591 100644 --- a/lib/time.rb +++ b/lib/time.rb @@ -1,51 +1,86 @@ +require 'date' # -# == Introduction +# When 'time' is required, Time is extended with additional methods for parsing +# and converting Times. +# +# = Features +# +# This library extends the Time class with the following: # -# This library extends the Time class: # * conversion between date string and time object. # * date-time defined by RFC 2822 # * HTTP-date defined by RFC 2616 -# * dateTime defined by XML Schema Part 2: Datatypes (ISO 8601) -# * various formats handled by Date._parse (string to time only) +# * datetime defined by XML Schema Part 2: Datatypes (ISO 8601) +# * various formats handled by Date._parse +# * various formats handled by Date._strptime # -# == Design Issues +# = Examples # -# === Specialized interface +# All examples assume you have loaded Time with: # -# This library provides methods dedicated to special purposes: -# * RFC 2822, RFC 2616 and XML Schema. -# * They makes usual life easier. +# require 'time' # -# === Doesn't depend on strftime +# All of these examples were done using the EST timezone which is GMT-5. # -# This library doesn't use +Time#strftime+. Especially #rfc2822 doesn't depend -# on +strftime+ because: +# == Creating a new Time instance # -# * %a and %b are locale sensitive +# The easiest way to create a new time object is to use either #parse or +# #strptime. Each uses Date.__parse and Date.__strptime to create a new +# instance of Time. # -# Since they are locale sensitive, they may be replaced to -# invalid weekday/month name in some locales. -# Since ruby-1.6 doesn't invoke setlocale by default, -# the problem doesn't arise until some external library invokes setlocale. -# Ruby/GTK is the example of such library. +# === Time.parse # -# * %z is not portable +# #parse takes a string representation of a Time and attempts to parse it +# using a heuristic. # -# %z is required to generate zone in date-time of RFC 2822 -# but it is not portable. +# Date.parse("2010-10-31") #=> 2010-10-31 00:00:00 -0500 # -# Note that +Time#strftime+ doesn't use +strftime()+ function in libc since Ruby 1.9. -# This means +Time#strftime+ is locale-insensitive since Ruby 1.9. -# The above statements are not valid now. +# Any missing pieces of the date are inferred based on the current date. # - -require 'date' - +# # assuming the current date is "2011-10-31" +# Time.parse("12:00") #=> 2011-10-31 12:00:00 -0500 +# +# We can change the date used to infer our missing elements by passing a second +# object that responds to #mon, #day and #year, such as Date, Time or DateTime. +# We can also use our own object. +# +# class MyDate +# attr_reader :mon, :day, :year # -# Implements the extensions to the Time class that are described in the -# documentation for the time.rb library. +# def initialize(mon, day, year) +# @mon, @day, @year = mon, day, year +# end +# end # +# d = Date.parse("2010-10-28") +# t = Time.parse("2010-10-29") +# dt = DateTime.parse("2010-10-30") +# md = MyDate.new(10,31,2010) +# +# Time.parse("12:00" d) #=> 2010-10-28 12:00:00 -0500 +# Time.parse("12:00" t) #=> 2010-10-29 12:00:00 -0500 +# Time.parse("12:00" dt) #=> 2010-10-30 12:00:00 -0500 +# Time.parse("12:00" md) #=> 2010-10-31 12:00:00 -0500 +# +# #parse also accepts an optional block. You can use this block to specify how +# to handle the year component of the date. This is specifically designed for +# handling two digit years. For example, if you wanted to treat all two digit +# years prior to 70 as the year 2000+ you could write this: +# +# Time.parse("01-10-31") {|year| year + (year < 70 ? 2000 : 1900)} +# #=> 2001-10-31 00:00:00 -0500 +# Time.parse("70-10-31") {|year| year + (year < 70 ? 2000 : 1900)} +# #=> 1970-10-31 00:00:00 -0500 +# +# === Time.strptime +# +# #strptime works similar to +parse+ except that instead of using a heuristic +# to detect the format of the input string, you provide a second argument that +# is describes the format of the string. For example: +# +# Time.strptime("2000-10-31", "%Y-%m-%d") #=> 2000-10-31 00:00:00 -0500 +# class Time class << Time @@ -277,6 +312,59 @@ class Time # block. For example: # # Time.strptime(...) {|y| y < 100 ? (y >= 69 ? y + 1900 : y + 2000) : y} + # + # Below is a list of the formating options: + # + # %a :: The abbreviated weekday name (``Sun'') + # %A :: The full weekday name (``Sunday'') + # %b :: The abbreviated month name (``Jan'') + # %B :: The full month name (``January'') + # %c :: The preferred local date and time representation + # %C :: Century (20 in 2009) + # %d :: Day of the month (01..31) + # %D :: Date (%m/%d/%y) + # %e :: Day of the month, blank-padded ( 1..31) + # %F :: Equivalent to %Y-%m-%d (the ISO 8601 date format) + # %h :: Equivalent to %b + # %H :: Hour of the day, 24-hour clock (00..23) + # %I :: Hour of the day, 12-hour clock (01..12) + # %j :: Day of the year (001..366) + # %k :: hour, 24-hour clock, blank-padded ( 0..23) + # %l :: hour, 12-hour clock, blank-padded ( 0..12) + # %L :: Millisecond of the second (000..999) + # %m :: Month of the year (01..12) + # %M :: Minute of the hour (00..59) + # %n :: Newline (\n) + # %N :: Fractional seconds digits, default is 9 digits (nanosecond) + # %3N millisecond (3 digits) + # %6N microsecond (6 digits) + # %9N nanosecond (9 digits) + # %p :: Meridian indicator (``AM'' or ``PM'') + # %P :: Meridian indicator (``am'' or ``pm'') + # %r :: time, 12-hour (same as %I:%M:%S %p) + # %R :: time, 24-hour (%H:%M) + # %s :: Number of seconds since 1970-01-01 00:00:00 UTC. + # %S :: Second of the minute (00..60) + # %t :: Tab character (\t) + # %T :: time, 24-hour (%H:%M:%S) + # %u :: Day of the week as a decimal, Monday being 1. (1..7) + # %U :: Week number of the current year, + # starting with the first Sunday as the first + # day of the first week (00..53) + # %v :: VMS date (%e-%b-%Y) + # %V :: Week number of year according to ISO 8601 (01..53) + # %W :: Week number of the current year, + # starting with the first Monday as the first + # day of the first week (00..53) + # %w :: Day of the week (Sunday is 0, 0..6) + # %x :: Preferred representation for the date alone, no time + # %X :: Preferred representation for the time alone, no date + # %y :: Year without a century (00..99) + # %Y :: Year with century + # %z :: Time zone as hour offset from UTC (e.g. +0900) + # %Z :: Time zone name + # %% :: Literal ``%'' character + def strptime(date, format, now=self.now) d = Date._strptime(date, format) raise ArgumentError, "invalid strptime format - `#{format}'" unless d -- 1.7.4.msysgit.0