From 16bb4f33de029587798484ec3eb1ec77bb0e28fb Mon Sep 17 00:00:00 2001 From: Shane Emmons Date: Tue, 4 Oct 2011 10:30:27 -0400 Subject: [PATCH] enhancing documentation for Time extension in stdlib --- lib/time.rb | 145 +++++++++++++++++++++++++++++++++++++++++++++++------------ 1 files changed, 116 insertions(+), 29 deletions(-) diff --git a/lib/time.rb b/lib/time.rb index 4eb888a..9a3fa5e 100644 --- a/lib/time.rb +++ b/lib/time.rb @@ -1,51 +1,138 @@ +require 'date' # -# == Introduction +# Extends the Time class with additional Class and Instance 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-01-01") #=> 2010-01-01 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-04" +# Time.parse("12:00") #=> 2011-10-04 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 +# +# def initialize(mon, day, year) +# @mon, @day, @year = mon, day, year +# end +# end +# +# d = Date.parse("2010-01-01") +# t = Time.parse("2010-01-02") +# dt = DateTime.parse("2010-01-03") +# md = MyDate.new(1,4,2010) +# +# Time.parse("12:00" d) #=> 2010-01-01 12:00:00 -0500 +# Time.parse("12:00" t) #=> 2010-01-02 12:00:00 -0500 +# Time.parse("12:00" dt) #=> 2010-01-03 12:00:00 -0500 +# Time.parse("12:00" md) #=> 2010-01-04 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-01-01") {|year| year + (year < 70 ? 2000 : 1900)} +# #=> 2001-01-01 00:00:00 -0500 +# Time.parse("70-01-01") {|year| year + (year < 70 ? 2000 : 1900)} +# #=> 1970-01-01 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-01-01", "%Y-%m-%d") #=> 2000-01-01 00:00:00 -0500 # -# Implements the extensions to the Time class that are described in the -# documentation for the time.rb library. +# 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 +# class Time class << Time -- 1.7.4.msysgit.0