rbs 3.3.2 → 3.4.0.pre.1

data/stdlib/base64/0/base64.rbs

@@ -1,42 +1,215 @@
 # <!-- 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.
 #
-#     require "base64"
+# Base64 is commonly used in contexts where binary data is not allowed or
+# supported:
 #
-#     enc   = Base64.encode64('Send reinforcements')
-#                         # -> "U2VuZCByZWluZm9yY2VtZW50cw==\n"
-#     plain = Base64.decode64(enc)
-#                         # -> "Send reinforcements"
+# *   Images in HTML or CSS files, or in URLs.
+# *   Email attachments.
 #
-# The purpose of using base64 to encode data is that it translates any binary
-# data into purely printable characters.
+#
+# 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.
+#
+# 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`:
   #
-  #     require 'base64'
-  #     str = 'VGhpcyBpcyBsaW5lIG9uZQpUaGlzIG' +
-  #           'lzIGxpbmUgdHdvClRoaXMgaXMgbGlu' +
-  #           'ZSB0aHJlZQpBbmQgc28gb24uLi4K'
-  #     puts Base64.decode64(str)
+  #     s = "VGhpcyBpcyBsaW5lIDEKVGhpcyBpcyBsaW5lIDIK\n"
+  #     Base64.decode64(s) # => "This is line 1\nThis is line 2\n"
   #
-  # *Generates:*
+  # 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 `/`:
   #
-  #     This is line one
-  #     This is line two
-  #     This is line three
-  #     And so on...
+  #     Base64.decode64("\x00\n-_") # => ""
+  #
+  # 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 +217,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:
+  #
+  #     Base64.encode64("\xFB\xEF\xBE") # => "++++\n"
+  #     Base64.encode64("\xFF\xFF\xFF") # => "////\n"
+  #
+  # The returned string may include padding; see
+  # [Padding](Base64.html#module-Base64-label-Padding) above.
   #
-  #     require 'base64'
-  #     Base64.encode64("Now is the time for all good coders\nto learn Ruby")
+  #     Base64.encode64('*') # => "Kg==\n"
   #
-  # *Generates:*
+  # 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:
   #
-  #     Tm93IGlzIHRoZSB0aW1lIGZvciBhbGwgZ29vZCBjb2RlcnMKdG8gbGVhcm4g
-  #     UnVieQ==
+  #     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 +252,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 +278,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 +312,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:
   #
-  # The padding character is optional. This method accepts both correctly-padded
-  # and unpadded input. Note that it still rejects incorrectly-padded input.
+  #     Base64.urlsafe_decode64('+')  # Raises ArgumentError.
+  #     Base64.urlsafe_decode64('/')  # Raises ArgumentError.
+  #     Base64.urlsafe_decode64("\n") # Raises ArgumentError.
+  #
+  # 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 +334,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/bigdecimal/0/big_decimal.rbs

@@ -122,7 +122,23 @@
 #     (2/3r).to_d(3)  # => 0.667e0
 #     "0.5".to_d      # => 0.5e0
 #
-# ## License
+# ## Methods for Working with JSON
+#
+# *   [::json_create](rdoc-ref:BigDecimal.json_create): Returns a new BigDecimal
+#     object constructed from the given object.
+# *   [#as_json](rdoc-ref:BigDecimal#as_json): Returns a 2-element hash
+#     representing `self`.
+# *   [#to_json](rdoc-ref:BigDecimal#to_json): Returns a JSON string
+#     representing `self`.
+#
+#
+# These methods are provided by the [JSON gem](https://github.com/flori/json).
+# To make these methods available:
+#
+#     require 'json/add/bigdecimal'
+#
+# *   ## License
+#
 #
 # Copyright (C) 2002 by Shigeo Kobayashi <shigeo@tinyforest.gr.jp>.
 #
@@ -145,8 +161,12 @@ class BigDecimal < Numeric
 
   # <!--
   #   rdoc-file=ext/bigdecimal/bigdecimal.c
-  #   - double_fig()
+  #   - BigDecimal.double_fig -> integer
   # -->
+  # Returns the number of digits a Float object is allowed to have; the result is
+  # system-dependent:
+  #
+  #     BigDecimal.double_fig # => 16
   #
   def self.double_fig: () -> Integer
 
@@ -1135,7 +1155,7 @@ class BigDecimal < Numeric
   # A space at the start of s returns positive values with a leading space.
   #
   # If s contains a number, a space is inserted after each group of that many
-  # fractional digits.
+  # digits, starting from '.' and counting outwards.
   #
   # If s ends with an 'E', engineering notation (0.xxxxEnn) is used.
   #
@@ -1143,14 +1163,14 @@ class BigDecimal < Numeric
   #
   # Examples:
   #
-  #     BigDecimal('-123.45678901234567890').to_s('5F')
-  #       #=> '-123.45678 90123 45678 9'
+  #     BigDecimal('-1234567890123.45678901234567890').to_s('5F')
+  #       #=> '-123 45678 90123.45678 90123 45678 9'
   #
-  #     BigDecimal('123.45678901234567890').to_s('+8F')
-  #       #=> '+123.45678901 23456789'
+  #     BigDecimal('1234567890123.45678901234567890').to_s('+8F')
+  #       #=> '+12345 67890123.45678901 23456789'
   #
-  #     BigDecimal('123.45678901234567890').to_s(' F')
-  #       #=> ' 123.4567890123456789'
+  #     BigDecimal('1234567890123.45678901234567890').to_s(' F')
+  #       #=> ' 1234567890123.4567890123456789'
   #
   def to_s: (?String | int s) -> String
 
@@ -1383,7 +1403,7 @@ module Kernel
   # *   Other type:
   #
   #     *   Raises an exception if keyword argument `exception` is `true`.
-  #     *   Returns `nil` if keyword argument `exception` is `true`.
+  #     *   Returns `nil` if keyword argument `exception` is `false`.
   #
   #
   #
@@ -1406,7 +1426,7 @@ class Integer
   #
   #     42.to_d   # => 0.42e2
   #
-  # See also BigDecimal::new.
+  # See also Kernel.BigDecimal.
   #
   def to_d: () -> BigDecimal
 
@@ -1498,7 +1518,7 @@ class Float
   #     1.234.to_d       # => 0.1234e1
   #     1.234.to_d(2)    # => 0.12e1
   #
-  # See also BigDecimal::new.
+  # See also Kernel.BigDecimal.
   #
   def to_d: (?Integer precision) -> BigDecimal
 
@@ -1579,7 +1599,7 @@ class String
   #     "123.45e1".to_d        # => 0.12345e4
   #     "45.67 degrees".to_d   # => 0.4567e2
   #
-  # See also BigDecimal::new.
+  # See also Kernel.BigDecimal.
   #
   def to_d: () -> BigDecimal
 end
@@ -1600,7 +1620,7 @@ class Rational
   #
   #     Rational(22, 7).to_d(3)   # => 0.314e1
   #
-  # See also BigDecimal::new.
+  # See also Kernel.BigDecimal.
   #
   def to_d: (Integer precision) -> BigDecimal
 
@@ -1685,7 +1705,7 @@ class Complex
   #     Complex(0.1234567, 0).to_d(4)   # => 0.1235e0
   #     Complex(Rational(22, 7), 0).to_d(3)   # => 0.314e1
   #
-  # See also BigDecimal::new.
+  # See also Kernel.BigDecimal.
   #
   def to_d: (*untyped args) -> BigDecimal
 

data/stdlib/coverage/0/coverage.rbs

@@ -245,8 +245,8 @@ module Coverage
   # -->
   # Returns true if coverage measurement is supported for the given mode.
   #
-  # The mode should be one of the following symbols: `:lines`, `:branches`,
-  # `:methods`, `:eval`.
+  # The mode should be one of the following symbols: `:lines`, `:oneshot_lines`,
+  # `:branches`, `:methods`, `:eval`.
   #
   # Example:
   #