rbs 2.8.4 → 3.8.1

data/stdlib/base64/0/base64.rbs

@@ -1,42 +1,206 @@
 # <!-- rdoc-file=lib/base64.rb -->
-# The Base64 module provides for the encoding (#encode64, #strict_encode64,
-# #urlsafe_encode64) and decoding (#decode64, #strict_decode64,
-# #urlsafe_decode64) of binary data using a Base64 representation.
+# Module Base64 provides methods for:
 #
-# ## Example
+# *   Encoding a binary string (containing non-ASCII characters) as a string of
+#     printable ASCII characters.
+# *   Decoding such an encoded string.
 #
-# A simple encoding and decoding.
+# Base64 is commonly used in contexts where binary data is not allowed or
+# supported:
 #
-#     require "base64"
+# *   Images in HTML or CSS files, or in URLs.
+# *   Email attachments.
 #
-#     enc   = Base64.encode64('Send reinforcements')
-#                         # -> "U2VuZCByZWluZm9yY2VtZW50cw==\n"
-#     plain = Base64.decode64(enc)
-#                         # -> "Send reinforcements"
+# A Base64-encoded string is about one-third larger that its source. See the
+# [Wikipedia article](https://en.wikipedia.org/wiki/Base64) for more
+# information.
 #
-# The purpose of using base64 to encode data is that it translates any binary
-# data into purely printable characters.
+# This module provides three pairs of encode/decode methods. Your choices among
+# these methods should depend on:
+#
+# *   Which character set is to be used for encoding and decoding.
+# *   Whether "padding" is to be used.
+# *   Whether encoded strings are to contain newlines.
+#
+# Note: Examples on this page assume that the including program has executed:
+#
+#     require 'base64'
+#
+# ## Encoding Character Sets
+#
+# A Base64-encoded string consists only of characters from a 64-character set:
+#
+# *   `('A'..'Z')`.
+# *   `('a'..'z')`.
+# *   `('0'..'9')`.
+# *   `=`, the 'padding' character.
+# *   Either:
+#     *   `%w[+ /]`:
+#         [RFC-2045-compliant](https://datatracker.ietf.org/doc/html/rfc2045);
+#         *not* safe for URLs.
+#     *   `%w[- _]`:
+#         [RFC-4648-compliant](https://datatracker.ietf.org/doc/html/rfc4648);
+#         safe for URLs.
+#
+# If you are working with Base64-encoded strings that will come from or be put
+# into URLs, you should choose this encoder-decoder pair of RFC-4648-compliant
+# methods:
+#
+# *   Base64.urlsafe_encode64 and Base64.urlsafe_decode64.
+#
+# Otherwise, you may choose any of the pairs in this module, including the pair
+# above, or the RFC-2045-compliant pairs:
+#
+# *   Base64.encode64 and Base64.decode64.
+# *   Base64.strict_encode64 and Base64.strict_decode64.
+#
+# ## Padding
+#
+# Base64-encoding changes a triplet of input bytes into a quartet of output
+# characters.
+#
+# **Padding in Encode Methods**
+#
+# Padding -- extending an encoded string with zero, one, or two trailing `=`
+# characters -- is performed by methods Base64.encode64, Base64.strict_encode64,
+# and, by default, Base64.urlsafe_encode64:
+#
+#     Base64.encode64('s')                         # => "cw==\n"
+#     Base64.strict_encode64('s')                  # => "cw=="
+#     Base64.urlsafe_encode64('s')                 # => "cw=="
+#     Base64.urlsafe_encode64('s', padding: false) # => "cw"
+#
+# When padding is performed, the encoded string is always of length *4n*, where
+# `n` is a non-negative integer:
+#
+# *   Input bytes of length *3n* generate unpadded output characters of length
+#     *4n*:
+#
+#         # n = 1:  3 bytes => 4 characters.
+#         Base64.strict_encode64('123')      # => "MDEy"
+#         # n = 2:  6 bytes => 8 characters.
+#         Base64.strict_encode64('123456')   # => "MDEyMzQ1"
+#
+# *   Input bytes of length *3n+1* generate padded output characters of length
+#     *4(n+1)*, with two padding characters at the end:
+#
+#         # n = 1:  4 bytes => 8 characters.
+#         Base64.strict_encode64('1234')     # => "MDEyMw=="
+#         # n = 2:  7 bytes => 12 characters.
+#         Base64.strict_encode64('1234567')  # => "MDEyMzQ1Ng=="
+#
+# *   Input bytes of length *3n+2* generate padded output characters of length
+#     *4(n+1)*, with one padding character at the end:
+#
+#         # n = 1:  5 bytes => 8 characters.
+#         Base64.strict_encode64('12345')    # => "MDEyMzQ="
+#         # n = 2:  8 bytes => 12 characters.
+#         Base64.strict_encode64('12345678') # => "MDEyMzQ1Njc="
+#
+# When padding is suppressed, for a positive integer *n*:
+#
+# *   Input bytes of length *3n* generate unpadded output characters of length
+#     *4n*:
+#
+#         # n = 1:  3 bytes => 4 characters.
+#         Base64.urlsafe_encode64('123', padding: false)      # => "MDEy"
+#         # n = 2:  6 bytes => 8 characters.
+#         Base64.urlsafe_encode64('123456', padding: false)   # => "MDEyMzQ1"
+#
+# *   Input bytes of length *3n+1* generate unpadded output characters of length
+#     *4n+2*, with two padding characters at the end:
+#
+#         # n = 1:  4 bytes => 6 characters.
+#         Base64.urlsafe_encode64('1234', padding: false)     # => "MDEyMw"
+#         # n = 2:  7 bytes => 10 characters.
+#         Base64.urlsafe_encode64('1234567', padding: false)  # => "MDEyMzQ1Ng"
+#
+# *   Input bytes of length *3n+2* generate unpadded output characters of length
+#     *4n+3*, with one padding character at the end:
+#
+#         # n = 1:  5 bytes => 7 characters.
+#         Base64.urlsafe_encode64('12345', padding: false)    # => "MDEyMzQ"
+#         # m = 2:  8 bytes => 11 characters.
+#         Base64.urlsafe_encode64('12345678', padding: false) # => "MDEyMzQ1Njc"
+#
+# **Padding in Decode Methods**
+#
+# All of the Base64 decode methods support (but do not require) padding.
+#
+# Method Base64.decode64 does not check the size of the padding:
+#
+#     Base64.decode64("MDEyMzQ1Njc") # => "01234567"
+#     Base64.decode64("MDEyMzQ1Njc=") # => "01234567"
+#     Base64.decode64("MDEyMzQ1Njc==") # => "01234567"
+#
+# Method Base64.strict_decode64 strictly enforces padding size:
+#
+#     Base64.strict_decode64("MDEyMzQ1Njc")   # Raises ArgumentError
+#     Base64.strict_decode64("MDEyMzQ1Njc=")  # => "01234567"
+#     Base64.strict_decode64("MDEyMzQ1Njc==") # Raises ArgumentError
+#
+# Method Base64.urlsafe_decode64 allows padding in `str`, which if present, must
+# be correct: see [Padding](Base64.html#module-Base64-label-Padding), above:
+#
+#     Base64.urlsafe_decode64("MDEyMzQ1Njc") # => "01234567"
+#     Base64.urlsafe_decode64("MDEyMzQ1Njc=") # => "01234567"
+#     Base64.urlsafe_decode64("MDEyMzQ1Njc==") # Raises ArgumentError.
+#
+# ## Newlines
+#
+# An encoded string returned by Base64.encode64 or Base64.urlsafe_encode64 has
+# an embedded newline character after each 60-character sequence, and, if
+# non-empty, at the end:
+#
+#     # No newline if empty.
+#     encoded = Base64.encode64("\x00" *  0)
+#     encoded.index("\n") # => nil
+#
+#     # Newline at end of short output.
+#     encoded = Base64.encode64("\x00" *  1)
+#     encoded.size        # => 4
+#     encoded.index("\n") # => 4
+#
+#     # Newline at end of longer output.
+#     encoded = Base64.encode64("\x00" * 45)
+#     encoded.size        # => 60
+#     encoded.index("\n") # => 60
+#
+#     # Newlines embedded and at end of still longer output.
+#     encoded = Base64.encode64("\x00" * 46)
+#     encoded.size                          # => 65
+#     encoded.rindex("\n")                  # => 65
+#     encoded.split("\n").map {|s| s.size } # => [60, 4]
+#
+# The string to be encoded may itself contain newlines, which are encoded as
+# Base64:
+#
+#       #   Base64.encode64("\n\n\n") # => "CgoK\n"
+#     s = "This is line 1\nThis is line 2\n"
+#     Base64.encode64(s) # => "VGhpcyBpcyBsaW5lIDEKVGhpcyBpcyBsaW5lIDIK\n"
 #
 module Base64
   # <!--
   #   rdoc-file=lib/base64.rb
   #   - decode64(str)
   # -->
-  # Returns the Base64-decoded version of `str`. This method complies with RFC
-  # 2045. Characters outside the base alphabet are ignored.
+  # Returns a string containing the decoding of an RFC-2045-compliant
+  # Base64-encoded string `str`:
+  #
+  #     s = "VGhpcyBpcyBsaW5lIDEKVGhpcyBpcyBsaW5lIDIK\n"
+  #     Base64.decode64(s) # => "This is line 1\nThis is line 2\n"
   #
-  #     require 'base64'
-  #     str = 'VGhpcyBpcyBsaW5lIG9uZQpUaGlzIG' +
-  #           'lzIGxpbmUgdHdvClRoaXMgaXMgbGlu' +
-  #           'ZSB0aHJlZQpBbmQgc28gb24uLi4K'
-  #     puts Base64.decode64(str)
+  # Non-Base64 characters in `str` are ignored; see [Encoding Character
+  # Set](Base64.html#module-Base64-label-Encoding+Character+Sets) above: these
+  # include newline characters and characters `-` and `/`:
   #
-  # *Generates:*
+  #     Base64.decode64("\x00\n-_") # => ""
   #
-  #     This is line one
-  #     This is line two
-  #     This is line three
-  #     And so on...
+  # Padding in `str` (even if incorrect) is ignored:
+  #
+  #     Base64.decode64("MDEyMzQ1Njc")   # => "01234567"
+  #     Base64.decode64("MDEyMzQ1Njc=")  # => "01234567"
+  #     Base64.decode64("MDEyMzQ1Njc==") # => "01234567"
   #
   def self?.decode64: (String str) -> String
 
@@ -44,16 +208,34 @@ module Base64
   #   rdoc-file=lib/base64.rb
   #   - encode64(bin)
   # -->
-  # Returns the Base64-encoded version of `bin`. This method complies with RFC
-  # 2045. Line feeds are added to every 60 encoded characters.
+  # Returns a string containing the RFC-2045-compliant Base64-encoding of `bin`.
+  #
+  # Per RFC 2045, the returned string may contain the URL-unsafe characters `+` or
+  # `/`; see [Encoding Character
+  # Set](Base64.html#module-Base64-label-Encoding+Character+Sets) above:
   #
-  #     require 'base64'
-  #     Base64.encode64("Now is the time for all good coders\nto learn Ruby")
+  #     Base64.encode64("\xFB\xEF\xBE") # => "++++\n"
+  #     Base64.encode64("\xFF\xFF\xFF") # => "////\n"
   #
-  # *Generates:*
+  # The returned string may include padding; see
+  # [Padding](Base64.html#module-Base64-label-Padding) above.
   #
-  #     Tm93IGlzIHRoZSB0aW1lIGZvciBhbGwgZ29vZCBjb2RlcnMKdG8gbGVhcm4g
-  #     UnVieQ==
+  #     Base64.encode64('*') # => "Kg==\n"
+  #
+  # The returned string ends with a newline character, and if sufficiently long
+  # will have one or more embedded newline characters; see
+  # [Newlines](Base64.html#module-Base64-label-Newlines) above:
+  #
+  #     Base64.encode64('*') # => "Kg==\n"
+  #     Base64.encode64('*' * 46)
+  #     # => "KioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioq\nKg==\n"
+  #
+  # The string to be encoded may itself contain newlines, which will be encoded as
+  # ordinary Base64:
+  #
+  #     Base64.encode64("\n\n\n") # => "CgoK\n"
+  #     s = "This is line 1\nThis is line 2\n"
+  #     Base64.encode64(s) # => "VGhpcyBpcyBsaW5lIDEKVGhpcyBpcyBsaW5lIDIK\n"
   #
   def self?.encode64: (String bin) -> String
 
@@ -61,9 +243,25 @@ module Base64
   #   rdoc-file=lib/base64.rb
   #   - strict_decode64(str)
   # -->
-  # Returns the Base64-decoded version of `str`. This method complies with RFC
-  # 4648. ArgumentError is raised if `str` is incorrectly padded or contains
-  # non-alphabet characters.  Note that CR or LF are also rejected.
+  # Returns a string containing the decoding of an RFC-2045-compliant
+  # Base64-encoded string `str`:
+  #
+  #     s = "VGhpcyBpcyBsaW5lIDEKVGhpcyBpcyBsaW5lIDIK"
+  #     Base64.strict_decode64(s) # => "This is line 1\nThis is line 2\n"
+  #
+  # Non-Base64 characters in `str` not allowed; see [Encoding Character
+  # Set](Base64.html#module-Base64-label-Encoding+Character+Sets) above: these
+  # include newline characters and characters `-` and `/`:
+  #
+  #     Base64.strict_decode64("\n") # Raises ArgumentError
+  #     Base64.strict_decode64('-')  # Raises ArgumentError
+  #     Base64.strict_decode64('_')  # Raises ArgumentError
+  #
+  # Padding in `str`, if present, must be correct:
+  #
+  #     Base64.strict_decode64("MDEyMzQ1Njc")   # Raises ArgumentError
+  #     Base64.strict_decode64("MDEyMzQ1Njc=")  # => "01234567"
+  #     Base64.strict_decode64("MDEyMzQ1Njc==") # Raises ArgumentError
   #
   def self?.strict_decode64: (String str) -> String
 
@@ -71,8 +269,33 @@ module Base64
   #   rdoc-file=lib/base64.rb
   #   - strict_encode64(bin)
   # -->
-  # Returns the Base64-encoded version of `bin`. This method complies with RFC
-  # 4648. No line feeds are added.
+  # Returns a string containing the RFC-2045-compliant Base64-encoding of `bin`.
+  #
+  # Per RFC 2045, the returned string may contain the URL-unsafe characters `+` or
+  # `/`; see [Encoding Character
+  # Set](Base64.html#module-Base64-label-Encoding+Character+Sets) above:
+  #
+  #     Base64.strict_encode64("\xFB\xEF\xBE") # => "++++\n"
+  #     Base64.strict_encode64("\xFF\xFF\xFF") # => "////\n"
+  #
+  # The returned string may include padding; see
+  # [Padding](Base64.html#module-Base64-label-Padding) above.
+  #
+  #     Base64.strict_encode64('*') # => "Kg==\n"
+  #
+  # The returned string will have no newline characters, regardless of its length;
+  # see [Newlines](Base64.html#module-Base64-label-Newlines) above:
+  #
+  #     Base64.strict_encode64('*') # => "Kg=="
+  #     Base64.strict_encode64('*' * 46)
+  #     # => "KioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKg=="
+  #
+  # The string to be encoded may itself contain newlines, which will be encoded as
+  # ordinary Base64:
+  #
+  #     Base64.strict_encode64("\n\n\n") # => "CgoK"
+  #     s = "This is line 1\nThis is line 2\n"
+  #     Base64.strict_encode64(s) # => "VGhpcyBpcyBsaW5lIDEKVGhpcyBpcyBsaW5lIDIK"
   #
   def self?.strict_encode64: (String bin) -> String
 
@@ -80,12 +303,21 @@ module Base64
   #   rdoc-file=lib/base64.rb
   #   - urlsafe_decode64(str)
   # -->
-  # Returns the Base64-decoded version of `str`. This method complies with ``Base
-  # 64 Encoding with URL and Filename Safe Alphabet'' in RFC 4648. The alphabet
-  # uses '-' instead of '+' and '_' instead of '/'.
+  # Returns the decoding of an RFC-4648-compliant Base64-encoded string `str`:
+  #
+  # `str` may not contain non-Base64 characters; see [Encoding Character
+  # Set](Base64.html#module-Base64-label-Encoding+Character+Sets) above:
+  #
+  #     Base64.urlsafe_decode64('+')  # Raises ArgumentError.
+  #     Base64.urlsafe_decode64('/')  # Raises ArgumentError.
+  #     Base64.urlsafe_decode64("\n") # Raises ArgumentError.
   #
-  # The padding character is optional. This method accepts both correctly-padded
-  # and unpadded input. Note that it still rejects incorrectly-padded input.
+  # Padding in `str`, if present, must be correct: see
+  # [Padding](Base64.html#module-Base64-label-Padding), above:
+  #
+  #     Base64.urlsafe_decode64("MDEyMzQ1Njc") # => "01234567"
+  #     Base64.urlsafe_decode64("MDEyMzQ1Njc=") # => "01234567"
+  #     Base64.urlsafe_decode64("MDEyMzQ1Njc==") # Raises ArgumentError.
   #
   def self?.urlsafe_decode64: (String str) -> String
 
@@ -93,10 +325,31 @@ module Base64
   #   rdoc-file=lib/base64.rb
   #   - urlsafe_encode64(bin, padding: true)
   # -->
-  # Returns the Base64-encoded version of `bin`. This method complies with ``Base
-  # 64 Encoding with URL and Filename Safe Alphabet'' in RFC 4648. The alphabet
-  # uses '-' instead of '+' and '_' instead of '/'. Note that the result can still
-  # contain '='. You can remove the padding by setting `padding` as false.
+  # Returns the RFC-4648-compliant Base64-encoding of `bin`.
+  #
+  # Per RFC 4648, the returned string will not contain the URL-unsafe characters
+  # `+` or `/`, but instead may contain the URL-safe characters `-` and `_`; see
+  # [Encoding Character
+  # Set](Base64.html#module-Base64-label-Encoding+Character+Sets) above:
+  #
+  #     Base64.urlsafe_encode64("\xFB\xEF\xBE") # => "----"
+  #     Base64.urlsafe_encode64("\xFF\xFF\xFF") # => "____"
+  #
+  # By default, the returned string may have padding; see
+  # [Padding](Base64.html#module-Base64-label-Padding), above:
+  #
+  #     Base64.urlsafe_encode64('*') # => "Kg=="
+  #
+  # Optionally, you can suppress padding:
+  #
+  #     Base64.urlsafe_encode64('*', padding: false) # => "Kg"
+  #
+  # The returned string will have no newline characters, regardless of its length;
+  # see [Newlines](Base64.html#module-Base64-label-Newlines) above:
+  #
+  #     Base64.urlsafe_encode64('*') # => "Kg=="
+  #     Base64.urlsafe_encode64('*' * 46)
+  #     # => "KioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKg=="
   #
   def self?.urlsafe_encode64: (String bin, ?padding: boolish) -> String
 end

data/stdlib/benchmark/0/benchmark.rbs

@@ -46,7 +46,6 @@
 #           x.report("upto:")  { 1.upto(n) do ; a = "1"; end }
 #         end
 #
-#
 # The result:
 #
 #                   user     system      total        real
@@ -146,7 +145,7 @@ module Benchmark
   #     >total:   2.930000   0.000000   2.930000 (  2.932889)
   #     >avg:     0.976667   0.000000   0.976667 (  0.977630)
   #
-  def self?.benchmark: (String caption, ?Integer? label_width, ?String? format, *String labels) { (Report report) -> (Array[Tms] | void) } -> Array[Tms]
+  def self?.benchmark: (String caption, ?Integer? label_width, ?String? format, *String labels) { (Report report) -> (Array[Tms] | untyped) } -> Array[Tms]
 
   # <!--
   #   rdoc-file=lib/benchmark.rb
@@ -241,7 +240,11 @@ module Benchmark
   #   rdoc-file=lib/benchmark.rb
   #   - realtime() { || ... }
   # -->
-  # Returns the elapsed real time used to execute the given block.
+  # Returns the elapsed real time used to execute the given block. The unit of
+  # time is seconds.
+  #
+  #     Benchmark.realtime { "a" * 1_000_000_000 }
+  #     #=> 0.5098029999935534
   #
   def self?.realtime: () { () -> void } -> Float
 
@@ -366,17 +369,23 @@ module Benchmark
     #
     # `%u`
     # :   Replaced by the user CPU time, as reported by Tms#utime.
+    #
     # `%y`
     # :   Replaced by the system CPU time, as reported by #stime (Mnemonic: y of
     #     "s*y*stem")
+    #
     # `%U`
     # :   Replaced by the children's user CPU time, as reported by Tms#cutime
+    #
     # `%Y`
     # :   Replaced by the children's system CPU time, as reported by Tms#cstime
+    #
     # `%t`
     # :   Replaced by the total CPU time, as reported by Tms#total
+    #
     # `%r`
     # :   Replaced by the elapsed real time, as reported by Tms#real
+    #
     # `%n`
     # :   Replaced by the label string, as reported by Tms#label (Mnemonic: n of
     #     "*n*ame")