diff --git a/stdlib/time/0/time.rbs b/stdlib/time/0/time.rbs new file mode 100644 index 000000000..f99197fa5 --- /dev/null +++ b/stdlib/time/0/time.rbs @@ -0,0 +1,327 @@ +class Time + interface _TimeLike + 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 + # -10:00 or +1330 will work, as will + # simpler hour-only time zones like -10 or + # +13. + # + # 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 + # Time.local(year, 1, 1).zone and + # Time.local(year, 7, 1).zone. + # 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 diff --git a/test/stdlib/TimeExtension_test.rb b/test/stdlib/TimeExtension_test.rb new file mode 100644 index 000000000..49123ce0f --- /dev/null +++ b/test/stdlib/TimeExtension_test.rb @@ -0,0 +1,119 @@ +require_relative "test_helper" +require "time" + +class TimeExtensionSingletonTest < Minitest::Test + include TypeAssertions + + library "time" + testing "singleton(::Time)" + + class MyDate + attr_reader :mon, :day, :year + + def initialize(mon, day, year) + @mon, @day, @year = mon, day, year + end + end + + def test_zone_offset + assert_send_type "(String) -> Integer", + Time, :zone_offset, "EST" + assert_send_type "(String, Integer) -> Integer", + Time, :zone_offset, "EST", 100 + end + + def test_parse + assert_send_type "(String) -> Time", + Time, :parse, "2010-10-31" + assert_send_type "(String, Date) -> Time", + Time, :parse, "12:00", Date.parse("2010-10-28") + assert_send_type "(String, Time) -> Time", + Time, :parse, "12:00", Time.parse("2010-10-29") + assert_send_type "(String, DateTime) -> Time", + Time, :parse, "12:00", DateTime.parse("2010-10-30") + assert_send_type "(String, TimeExtensionSingletonTest::MyDate) -> Time", + Time, :parse, "12:00", MyDate.new(10, 31, 2010) + assert_send_type "(String) { (Integer) -> Integer } -> Time", + Time, :parse, "01-10-31" do |year| year + 1000 end + assert_send_type "(String, Date) { (Integer) -> Integer } -> Time", + Time, :parse, "12:00", Date.parse("2010-10-28") do |year| year + 1000 end + end + + def test_strptime + assert_send_type "(String, String) -> Time", + Time, :strptime, "2010-10-31", "%Y-%m-%d" + assert_send_type "(String, String, Date) -> Time", + Time, :strptime, "12:00", "%H:%M", Date.parse("2010-10-28") + assert_send_type "(String, String, Time) -> Time", + Time, :strptime, "12:00", "%H:%M", Time.parse("2010-10-29") + assert_send_type "(String, String, DateTime) -> Time", + Time, :strptime, "12:00", "%H:%M", DateTime.parse("2010-10-30") + assert_send_type "(String, String, TimeExtensionSingletonTest::MyDate) -> Time", + Time, :strptime, "12:00", "%H:%M", MyDate.new(10, 31, 2010) + assert_send_type "(String, String) { (Integer) -> Integer } -> Time", + Time, :strptime, "01-10-31", "%y-%m-%d" do |year| year + 1000 end + assert_send_type "(String, String, Date) { (Integer) -> Integer } -> Time", + Time, :strptime, "12:00", "%H:%M", Date.parse("2010-10-28") do |year| year + 1000 end + end + + def test_rfc2822 + assert_send_type "(String) -> Time", + Time, :rfc2822, "Wed, 05 Oct 2011 22:26:12 -0400" + end + + def test_rfc822 + assert_send_type "(String) -> Time", + Time, :rfc822, "Wed, 05 Oct 2011 22:26:12 -0400" + end + + def test_httpdate + assert_send_type "(String) -> Time", + Time, :httpdate, "Thu, 06 Oct 2011 02:26:12 GMT" + end + + def test_xmlschema + assert_send_type "(String) -> Time", + Time, :xmlschema, "2011-10-05T22:26:12-04:00" + end + + def test_iso8601 + assert_send_type "(String) -> Time", + Time, :iso8601, "2011-10-05T22:26:12-04:00" + end +end + +class TimeExtensionInstanceTest < Minitest::Test + include TypeAssertions + + library "time" + testing "::Time" + + def test_rfc2822 + assert_send_type "() -> String", + Time.now, :rfc2822 + end + + def test_rfc822 + assert_send_type "() -> String", + Time.now, :rfc822 + end + + def test_httpdate + assert_send_type "() -> String", + Time.now, :httpdate + end + + def test_xmlschema + assert_send_type "() -> String", + Time.now, :xmlschema + assert_send_type "(Integer) -> String", + Time.now, :xmlschema, 3 + end + + def test_iso8601 + assert_send_type "() -> String", + Time.now, :iso8601 + assert_send_type "(Integer) -> String", + Time.now, :iso8601, 3 + end +end