Bug #5402 » 0001-enhancing-documentation-for-Time-extension-in-stdlib.patch
| lib/time.rb | ||
|---|---|---|
|
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
|
||