Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Time (extension) signatures #511

Merged
merged 1 commit into from
Dec 16, 2020
Merged

Add Time (extension) signatures #511

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
327 changes: 327 additions & 0 deletions stdlib/time/0/time.rbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,327 @@
class Time
interface _TimeLike
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[note] I cannot find a good name... 😓

def year: () -> Integer
def mon: () -> Integer
def day: () -> Integer
end

#
# Return the number of seconds the specified time zone differs
# from UTC.
#
# Numeric time zones that include minutes, such as
# <code>-10:00</code> or <code>+1330</code> will work, as will
# simpler hour-only time zones like <code>-10</code> or
# <code>+13</code>.
#
# Textual time zones listed in ZoneOffset are also supported.
#
# If the time zone does not match any of the above, +zone_offset+
# will check if the local time zone (both with and without
# potential Daylight Saving \Time changes being in effect) matches
# +zone+. Specifying a value for +year+ will change the year used
# to find the local time zone.
#
# If +zone_offset+ is unable to determine the offset, nil will be
# returned.
#
# require 'time'
#
# Time.zone_offset("EST") #=> -18000
#
# You must require 'time' to use this method.
#
def self.zone_offset: (String zone, ?Integer year) -> Integer

#
# Takes a string representation of a Time and attempts to parse it
# using a heuristic.
#
# require 'time'
#
# Time.parse("2010-10-31") #=> 2010-10-31 00:00:00 -0500
#
# Any missing pieces of the date are inferred based on the current date.
#
# require 'time'
#
# # 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.
#
# require 'time'
#
# class MyDate
# attr_reader :mon, :day, :year
#
# 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
#
# If a block is given, the year described in +date+ is converted
# by the block. 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:
#
# require 'time'
#
# 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
#
# If the upper components of the given time are broken or missing, they are
# supplied with those of +now+. For the lower components, the minimum
# values (1 or 0) are assumed if broken or missing. For example:
#
# require 'time'
#
# # Suppose it is "Thu Nov 29 14:33:20 2001" now and
# # your time zone is EST which is GMT-5.
# now = Time.parse("Thu Nov 29 14:33:20 2001")
# Time.parse("16:30", now) #=> 2001-11-29 16:30:00 -0500
# Time.parse("7/23", now) #=> 2001-07-23 00:00:00 -0500
# Time.parse("Aug 31", now) #=> 2001-08-31 00:00:00 -0500
# Time.parse("Aug 2000", now) #=> 2000-08-01 00:00:00 -0500
#
# Since there are numerous conflicts among locally defined time zone
# abbreviations all over the world, this method is not intended to
# understand all of them. For example, the abbreviation "CST" is
# used variously as:
#
# -06:00 in America/Chicago,
# -05:00 in America/Havana,
# +08:00 in Asia/Harbin,
# +09:30 in Australia/Darwin,
# +10:30 in Australia/Adelaide,
# etc.
#
# Based on this fact, this method only understands the time zone
# abbreviations described in RFC 822 and the system time zone, in the
# order named. (i.e. a definition in RFC 822 overrides the system
# time zone definition.) The system time zone is taken from
# <tt>Time.local(year, 1, 1).zone</tt> and
# <tt>Time.local(year, 7, 1).zone</tt>.
# If the extracted time zone abbreviation does not match any of them,
# it is ignored and the given time is regarded as a local time.
#
# ArgumentError is raised if Date._parse cannot extract information from
# +date+ or if the Time class cannot represent specified date.
#
# This method can be used as a fail-safe for other parsing methods as:
#
# Time.rfc2822(date) rescue Time.parse(date)
# Time.httpdate(date) rescue Time.parse(date)
# Time.xmlschema(date) rescue Time.parse(date)
#
# A failure of Time.parse should be checked, though.
#
# You must require 'time' to use this method.
#
def self.parse: (String date, ?_TimeLike now) ?{ (Integer) -> Integer } -> Time

#
# 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 describes the format of the string.
#
# If a block is given, the year described in +date+ is converted by the
# block. For example:
#
# Time.strptime(...) {|y| y < 100 ? (y >= 69 ? y + 1900 : y + 2000) : y}
#
# Below is a list of the formatting 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)
# %g :: The last two digits of the commercial year
# %G :: The week-based year according to ISO-8601 (week 1 starts on Monday
# and includes January 4)
# %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
# %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 which may include century, if provided
# %z :: Time zone as hour offset from UTC (e.g. +0900)
# %Z :: Time zone name
# %% :: Literal "%" character
# %+ :: date(1) (%a %b %e %H:%M:%S %Z %Y)
#
# require 'time'
#
# Time.strptime("2000-10-31", "%Y-%m-%d") #=> 2000-10-31 00:00:00 -0500
#
# You must require 'time' to use this method.
#
def self.strptime: (String date, String format, ?_TimeLike now) ?{ (Integer) -> Integer } -> Time

#
# Parses +date+ as date-time defined by RFC 2822 and converts it to a Time
# object. The format is identical to the date format defined by RFC 822 and
# updated by RFC 1123.
#
# ArgumentError is raised if +date+ is not compliant with RFC 2822
# or if the Time class cannot represent specified date.
#
# See #rfc2822 for more information on this format.
#
# require 'time'
#
# Time.rfc2822("Wed, 05 Oct 2011 22:26:12 -0400")
# #=> 2010-10-05 22:26:12 -0400
#
# You must require 'time' to use this method.
#
def self.rfc2822: (String date) -> Time

alias self.rfc822 self.rfc2822

#
# Parses +date+ as an HTTP-date defined by RFC 2616 and converts it to a
# Time object.
#
# ArgumentError is raised if +date+ is not compliant with RFC 2616 or if
# the Time class cannot represent specified date.
#
# See #httpdate for more information on this format.
#
# require 'time'
#
# Time.httpdate("Thu, 06 Oct 2011 02:26:12 GMT")
# #=> 2011-10-06 02:26:12 UTC
#
# You must require 'time' to use this method.
#
def self.httpdate: (String date) -> Time

#
# Parses +date+ as a dateTime defined by the XML Schema and converts it to
# a Time object. The format is a restricted version of the format defined
# by ISO 8601.
#
# ArgumentError is raised if +date+ is not compliant with the format or if
# the Time class cannot represent specified date.
#
# See #xmlschema for more information on this format.
#
# require 'time'
#
# Time.xmlschema("2011-10-05T22:26:12-04:00")
# #=> 2011-10-05 22:26:12-04:00
#
# You must require 'time' to use this method.
#
def self.xmlschema: (String date) -> Time

alias self.iso8601 self.xmlschema

#
# Returns a string which represents the time as date-time defined by RFC 2822:
#
# day-of-week, DD month-name CCYY hh:mm:ss zone
#
# where zone is [+-]hhmm.
#
# If +self+ is a UTC time, -0000 is used as zone.
#
# require 'time'
#
# t = Time.now
# t.rfc2822 # => "Wed, 05 Oct 2011 22:26:12 -0400"
#
# You must require 'time' to use this method.
#
def rfc2822: () -> String

alias rfc822 rfc2822

#
# Returns a string which represents the time as RFC 1123 date of HTTP-date
# defined by RFC 2616:
#
# day-of-week, DD month-name CCYY hh:mm:ss GMT
#
# Note that the result is always UTC (GMT).
#
# require 'time'
#
# t = Time.now
# t.httpdate # => "Thu, 06 Oct 2011 02:26:12 GMT"
#
# You must require 'time' to use this method.
#
def httpdate: () -> String

#
# Returns a string which represents the time as a dateTime defined by XML
# Schema:
#
# CCYY-MM-DDThh:mm:ssTZD
# CCYY-MM-DDThh:mm:ss.sssTZD
#
# where TZD is Z or [+-]hh:mm.
#
# If self is a UTC time, Z is used as TZD. [+-]hh:mm is used otherwise.
#
# +fractional_digits+ specifies a number of digits to use for fractional
# seconds. Its default value is 0.
#
# require 'time'
#
# t = Time.now
# t.iso8601 # => "2011-10-05T22:26:12-04:00"
#
# You must require 'time' to use this method.
#
def xmlschema: (?Integer fraction_digits) -> String

alias iso8601 xmlschema
end
Loading