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