diff --git a/.github/workflows/bundle-update.yml b/.github/workflows/bundle-update.yml index c82eb79f2..5e4067690 100644 --- a/.github/workflows/bundle-update.yml +++ b/.github/workflows/bundle-update.yml @@ -16,7 +16,7 @@ jobs: - name: Set up Ruby uses: ruby/setup-ruby@v1 with: - ruby-version: '4.0.0-preview2' + ruby-version: '4.0.0-preview3' - name: Set up git run: | diff --git a/.github/workflows/c-check.yml b/.github/workflows/c-check.yml index dd7076d2c..31d506089 100644 --- a/.github/workflows/c-check.yml +++ b/.github/workflows/c-check.yml @@ -12,7 +12,7 @@ jobs: - uses: actions/checkout@v6 - uses: ruby/setup-ruby@v1 with: - ruby-version: "4.0.0-preview2" + ruby-version: "4.0.0-preview3" bundler-cache: none - name: Set working directory as safe run: git config --global --add safe.directory $(pwd) diff --git a/.github/workflows/comments.yml b/.github/workflows/comments.yml index 4b1837af6..53bba5174 100644 --- a/.github/workflows/comments.yml +++ b/.github/workflows/comments.yml @@ -11,12 +11,12 @@ jobs: comments: runs-on: "ubuntu-latest" env: - RUBY_COMMIT: v4.0.0-preview2 + RUBY_COMMIT: v4.0.0-preview3 steps: - uses: actions/checkout@v6 - uses: ruby/setup-ruby@v1 with: - ruby-version: "4.0.0-preview2" + ruby-version: "4.0.0-preview3" bundler: none - name: Install dependencies run: | diff --git a/.github/workflows/ruby.yml b/.github/workflows/ruby.yml index a04583832..cd65f49d7 100644 --- a/.github/workflows/ruby.yml +++ b/.github/workflows/ruby.yml @@ -13,24 +13,24 @@ jobs: strategy: fail-fast: false matrix: - ruby: ['3.2', '3.3', '3.4', '4.0.0-preview2', head] + ruby: ['3.2', '3.3', '3.4', '4.0.0-preview3', head] rubyopt: [""] job: - test include: - ruby: head job: stdlib_test rubocop - - ruby: "4.0.0-preview2" + - ruby: "4.0.0-preview3" job: stdlib_test - - ruby: "4.0.0-preview2" + - ruby: "4.0.0-preview3" job: test rubyopt: "--enable-frozen-string-literal" - - ruby: "4.0.0-preview2" + - ruby: "4.0.0-preview3" job: stdlib_test rubyopt: "--enable-frozen-string-literal" - - ruby: "4.0.0-preview2" + - ruby: "4.0.0-preview3" job: rubocop validate test_doc build test_generate_stdlib raap - - ruby: "4.0.0-preview2" + - ruby: "4.0.0-preview3" job: typecheck_test env: RANDOMIZE_STDLIB_TEST_ORDER: "true" @@ -74,7 +74,7 @@ jobs: strategy: fail-fast: false matrix: - ruby: ['4.0.0-preview2', head] + ruby: ['4.0.0-preview3', head] steps: - uses: actions/checkout@v6 - name: Install dependencies diff --git a/core/array.rbs b/core/array.rbs index 7d01d4a84..a110da352 100644 --- a/core/array.rbs +++ b/core/array.rbs @@ -1213,7 +1213,7 @@ class Array[unchecked out Elem] < Object # Returns the element from `self` found by a binary search, or `nil` if the # search found no suitable element. # - # See [Binary Searching](rdoc-ref:bsearch.rdoc). + # See [Binary Searching](rdoc-ref:language/bsearch.rdoc). # # Related: see [Methods for Fetching](rdoc-ref:Array@Methods+for+Fetching). # @@ -1229,7 +1229,7 @@ class Array[unchecked out Elem] < Object # Returns the integer index of the element from `self` found by a binary search, # or `nil` if the search found no suitable element. # - # See [Binary Searching](rdoc-ref:bsearch.rdoc). + # See [Binary Searching](rdoc-ref:language/bsearch.rdoc). # # Related: see [Methods for Fetching](rdoc-ref:Array@Methods+for+Fetching). # @@ -2618,7 +2618,7 @@ class Array[unchecked out Elem] < Object # - pack(template, buffer: nil) -> string # --> # Formats each element in `self` into a binary string; returns that string. See - # [Packed Data](rdoc-ref:packed_data.rdoc). + # [Packed Data](rdoc-ref:language/packed_data.rdoc). # def pack: (string fmt, ?buffer: String?) -> String diff --git a/core/complex.rbs b/core/complex.rbs index 864d4e057..3b4b4919f 100644 --- a/core/complex.rbs +++ b/core/complex.rbs @@ -184,23 +184,24 @@ class Complex < Numeric # - # Returns the product of `self` and `numeric`: + # Returns the numeric product of `self` and `other`: # + # Complex.rect(9, 8) * 4 # => (36+32i) + # Complex.rect(20, 9) * 9.8 # => (196.0+88.2i) # Complex.rect(2, 3) * Complex.rect(2, 3) # => (-5+12i) # Complex.rect(900) * Complex.rect(1) # => (900+0i) # Complex.rect(-2, 9) * Complex.rect(-9, 2) # => (0-85i) - # Complex.rect(9, 8) * 4 # => (36+32i) - # Complex.rect(20, 9) * 9.8 # => (196.0+88.2i) + # Complex.rect(9, 8) * Rational(2, 3) # => ((6/1)+(16/3)*i) # def *: (Numeric) -> Complex # - # Returns `self` raised to power `numeric`: + # Returns `self` raised to the power `exponent`: # # Complex.rect(0, 1) ** 2 # => (-1+0i) # Complex.rect(-8) ** Rational(1, 3) # => (1.0000000000000002+1.7320508075688772i) @@ -209,23 +210,33 @@ class Complex < Numeric # - # Returns the sum of `self` and `numeric`: + # Returns the sum of `self` and `other`: + # + # Complex(1, 2) + 0 # => (1+2i) + # Complex(1, 2) + 1 # => (2+2i) + # Complex(1, 2) + -1 # => (0+2i) + # + # Complex(1, 2) + 1.0 # => (2.0+2i) + # + # Complex(1, 2) + Complex(2, 1) # => (3+3i) + # Complex(1, 2) + Complex(2.0, 1.0) # => (3.0+3.0i) + # + # Complex(1, 2) + Rational(1, 1) # => ((2/1)+2i) + # Complex(1, 2) + Rational(1, 2) # => ((3/2)+2i) + # + # For a computation involving Floats, the result may be inexact (see Float#+): # - # Complex.rect(2, 3) + Complex.rect(2, 3) # => (4+6i) - # Complex.rect(900) + Complex.rect(1) # => (901+0i) - # Complex.rect(-2, 9) + Complex.rect(-9, 2) # => (-11+11i) - # Complex.rect(9, 8) + 4 # => (13+8i) - # Complex.rect(20, 9) + 9.8 # => (29.8+9i) + # Complex(1, 2) + 3.14 # => (4.140000000000001+2i) # def +: (Numeric) -> Complex # - # Returns the difference of `self` and `numeric`: + # Returns the difference of `self` and `other`: # # Complex.rect(2, 3) - Complex.rect(2, 3) # => (0+0i) # Complex.rect(900) - Complex.rect(1) # => (899+0i) @@ -237,9 +248,9 @@ class Complex < Numeric # - # Returns the negation of `self`, which is the negation of each of its parts: + # Returns `self`, negated, which is the negation of each of its parts: # # -Complex.rect(1, 2) # => (-1-2i) # -Complex.rect(-1, -2) # => (1+2i) @@ -248,9 +259,9 @@ class Complex < Numeric # - # Returns the quotient of `self` and `numeric`: + # Returns the quotient of `self` and `other`: # # Complex.rect(2, 3) / Complex.rect(2, 3) # => (1+0i) # Complex.rect(900) / Complex.rect(1) # => (900+0i) @@ -597,9 +608,9 @@ class Complex < Numeric # - # Returns the quotient of `self` and `numeric`: + # Returns the quotient of `self` and `other`: # # Complex.rect(2, 3) / Complex.rect(2, 3) # => (1+0i) # Complex.rect(900) / Complex.rect(1) # => (900+0i) diff --git a/core/encoding.rbs b/core/encoding.rbs index 349b62ec9..1960bcc0d 100644 --- a/core/encoding.rbs +++ b/core/encoding.rbs @@ -281,7 +281,7 @@ class Encoding def inspect: () -> String # - # Returns the name of the encoding. + # The name of the encoding. # # Encoding::UTF_8.name #=> "UTF-8" # @@ -297,12 +297,8 @@ class Encoding # def names: () -> Array[String] - # - # Returns the name of the encoding. + # + # The name of the encoding. # # Encoding::UTF_8.name #=> "UTF-8" # diff --git a/core/enumerable.rbs b/core/enumerable.rbs index ce8930f80..f3a4a8b93 100644 --- a/core/enumerable.rbs +++ b/core/enumerable.rbs @@ -2136,7 +2136,7 @@ module Enumerable[unchecked out Elem] : _Each[Elem] # ["F", 6860] # # You can use the special symbol `:_alone` to force an element into its own - # separate chuck: + # separate chunk: # # a = [0, 0, 1, 1] # e = a.chunk{|i| i.even? ? :_alone : true } diff --git a/core/enumerator.rbs b/core/enumerator.rbs index af5a8679f..f53645a14 100644 --- a/core/enumerator.rbs +++ b/core/enumerator.rbs @@ -137,7 +137,7 @@ class Enumerator[unchecked out Elem, out Return = void] < Object # # Creates an infinite enumerator from any block, just called over and over. The # result of the previous iteration is passed to the next one. If `initial` is @@ -169,6 +169,23 @@ class Enumerator[unchecked out Elem, out Return = void] < Object # Enumerator.produce { scanner.scan(PATTERN) }.slice_after { scanner.eos? }.first # # => ["7", "+", "38", "/", "6"] # + # The optional `size` keyword argument specifies the size of the enumerator, + # which can be retrieved by Enumerator#size. It can be an integer, + # `Float::INFINITY`, a callable object (such as a lambda), or `nil` to indicate + # unknown size. When not specified, the size defaults to `Float::INFINITY`. + # + # # Infinite enumerator + # enum = Enumerator.produce(1, size: Float::INFINITY, &:succ) + # enum.size # => Float::INFINITY + # + # # Finite enumerator with known/computable size + # abs_dir = File.expand_path("./baz") # => "/foo/bar/baz" + # traverser = Enumerator.produce(abs_dir, size: -> { abs_dir.count("/") + 1 }) { + # raise StopIteration if it == "/" + # File.dirname(it) + # } + # traverser.size # => 4 + # def self.produce: [T] () { (T? prev) -> T } -> Enumerator[T, bot] | [T] (T initial) { (T prev) -> T } -> Enumerator[T, bot] diff --git a/core/fiber.rbs b/core/fiber.rbs index d24f1796d..3d68f2c7b 100644 --- a/core/fiber.rbs +++ b/core/fiber.rbs @@ -82,7 +82,8 @@ class Fiber < Object # --> # Returns the value of the fiber storage variable identified by `key`. # - # The `key` must be a symbol, and the value is set by Fiber#[]= or Fiber#store. + # The `key` must be a symbol, and the value is set by Fiber#[]= or + # Fiber#storage. # # See also Fiber::[]=. # diff --git a/core/file.rbs b/core/file.rbs index 79e1c6ec1..6a31cbcbd 100644 --- a/core/file.rbs +++ b/core/file.rbs @@ -1414,7 +1414,7 @@ class File < IO # rdoc-file=file.c # - File.owned?(file_name) -> true or false # --> - # Returns `true` if the named file exists and the effective used id of the + # Returns `true` if the named file exists and the effective user id of the # calling process is the owner of the file. # # *file_name* can be an IO object. diff --git a/core/file_test.rbs b/core/file_test.rbs index af401f320..fa4e8de71 100644 --- a/core/file_test.rbs +++ b/core/file_test.rbs @@ -145,7 +145,7 @@ module FileTest # rdoc-file=file.c # - File.owned?(file_name) -> true or false # --> - # Returns `true` if the named file exists and the effective used id of the + # Returns `true` if the named file exists and the effective user id of the # calling process is the owner of the file. # # *file_name* can be an IO object. diff --git a/core/float.rbs b/core/float.rbs index 5be1e73d6..aab9f1a92 100644 --- a/core/float.rbs +++ b/core/float.rbs @@ -1,15 +1,193 @@ -# -# A Float object represents a sometimes-inexact real number using the native -# architecture's double-precision floating point representation. +# +# A Float object stores a real number using the native architecture's +# double-precision floating-point representation. +# +# ## Float Imprecisions +# +# Some real numbers can be represented precisely as Float objects: +# +# 37.5 # => 37.5 +# 98.75 # => 98.75 +# 12.3125 # => 12.3125 +# +# Others cannot; among these are the transcendental numbers, including: +# +# * Pi, *π*: in mathematics, a number of infinite precision: +# 3.1415926535897932384626433... (to 25 places); in Ruby, it is of limited +# precision (in this case, to 16 decimal places): +# +# Math::PI # => 3.141592653589793 +# +# * Euler's number, *e*: in mathematics, a number of infinite precision: +# 2.7182818284590452353602874... (to 25 places); in Ruby, it is of limited +# precision (in this case, to 15 decimal places): +# +# Math::E # => 2.718281828459045 +# +# Some floating-point computations in Ruby give precise results: +# +# 1.0/2 # => 0.5 +# 100.0/8 # => 12.5 +# +# Others do not: +# +# * In mathematics, 2/3 as a decimal number is an infinitely-repeating +# decimal: 0.666... (forever); in Ruby, `2.0/3` is of limited precision (in +# this case, to 16 decimal places): +# +# 2.0/3 # => 0.6666666666666666 +# +# * In mathematics, the square root of 2 is an irrational number of infinite +# precision: 1.4142135623730950488016887... (to 25 decimal places); in Ruby, +# it is of limited precision (in this case, to 16 decimal places): +# +# Math.sqrt(2.0) # => 1.4142135623730951 +# +# * Even a simple computation can introduce imprecision: +# +# x = 0.1 + 0.2 # => 0.30000000000000004 +# y = 0.3 # => 0.3 +# x == y # => false +# +# See: +# +# * https://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html +# * https://github.com/rdp/ruby_tutorials_core/wiki/Ruby-Talk-FAQ#-why-are-rub +# ys-floats-imprecise +# * https://en.wikipedia.org/wiki/Floating_point#Accuracy_problems +# +# Note that precise storage and computation of rational numbers is possible +# using Rational objects. +# +# ## Creating a Float +# +# You can create a Float object explicitly with: +# +# * A [floating-point literal](rdoc-ref:syntax/literals.rdoc@Float+Literals). +# +# You can convert certain objects to Floats with: +# +# * Method #Float. +# +# ## What's Here +# +# First, what's elsewhere. Class Float: +# +# * Inherits from [class Numeric](rdoc-ref:Numeric@What-27s+Here) and [class +# Object](rdoc-ref:Object@What-27s+Here). +# * Includes [module Comparable](rdoc-ref:Comparable@What-27s+Here). +# +# Here, class Float provides methods for: +# +# * [Querying](rdoc-ref:Float@Querying) +# * [Comparing](rdoc-ref:Float@Comparing) +# * [Converting](rdoc-ref:Float@Converting) +# +# ### Querying +# +# * #finite?: Returns whether `self` is finite. +# * #hash: Returns the integer hash code for `self`. +# * #infinite?: Returns whether `self` is infinite. +# * #nan?: Returns whether `self` is a NaN (not-a-number). +# +# ### Comparing # -# Floating point has a different arithmetic and is an inexact number. So you -# should know its esoteric system. See following: +# * #<: Returns whether `self` is less than the given value. +# * #<=: Returns whether `self` is less than or equal to the given value. +# * #<=>: Returns a number indicating whether `self` is less than, equal to, +# or greater than the given value. +# * #== (aliased as #=== and #eql?): Returns whether `self` is equal to the +# given value. +# * #>: Returns whether `self` is greater than the given value. +# * #>=: Returns whether `self` is greater than or equal to the given value. +# +# ### Converting +# +# * #% (aliased as #modulo): Returns `self` modulo the given value. +# * #*: Returns the product of `self` and the given value. +# * #**: Returns the value of `self` raised to the power of the given value. +# * #+: Returns the sum of `self` and the given value. +# * #-: Returns the difference of `self` and the given value. +# * #/: Returns the quotient of `self` and the given value. +# * #ceil: Returns the smallest number greater than or equal to `self`. +# * #coerce: Returns a 2-element array containing the given value converted to +# a Float and `self` +# * #divmod: Returns a 2-element array containing the quotient and remainder +# results of dividing `self` by the given value. +# * #fdiv: Returns the Float result of dividing `self` by the given value. +# * #floor: Returns the greatest number smaller than or equal to `self`. +# * #next_float: Returns the next-larger representable Float. +# * #prev_float: Returns the next-smaller representable Float. +# * #quo: Returns the quotient from dividing `self` by the given value. +# * #round: Returns `self` rounded to the nearest value, to a given precision. +# * #to_i (aliased as #to_int): Returns `self` truncated to an Integer. +# * #to_s (aliased as #inspect): Returns a string containing the place-value +# representation of `self` in the given radix. +# * #truncate: Returns `self` truncated to a given precision. +# +# +# A Float object stores a real number using the native architecture's +# double-precision floating-point representation. +# +# ## Float Imprecisions +# +# Some real numbers can be represented precisely as Float objects: +# +# 37.5 # => 37.5 +# 98.75 # => 98.75 +# 12.3125 # => 12.3125 +# +# Others cannot; among these are the transcendental numbers, including: +# +# * Pi, *π*: in mathematics, a number of infinite precision: +# 3.1415926535897932384626433... (to 25 places); in Ruby, it is of limited +# precision (in this case, to 16 decimal places): +# +# Math::PI # => 3.141592653589793 +# +# * Euler's number, *e*: in mathematics, a number of infinite precision: +# 2.7182818284590452353602874... (to 25 places); in Ruby, it is of limited +# precision (in this case, to 15 decimal places): +# +# Math::E # => 2.718281828459045 +# +# Some floating-point computations in Ruby give precise results: +# +# 1.0/2 # => 0.5 +# 100.0/8 # => 12.5 +# +# Others do not: +# +# * In mathematics, 2/3 as a decimal number is an infinitely-repeating +# decimal: 0.666... (forever); in Ruby, `2.0/3` is of limited precision (in +# this case, to 16 decimal places): +# +# 2.0/3 # => 0.6666666666666666 +# +# * In mathematics, the square root of 2 is an irrational number of infinite +# precision: 1.4142135623730950488016887... (to 25 decimal places); in Ruby, +# it is of limited precision (in this case, to 16 decimal places): +# +# Math.sqrt(2.0) # => 1.4142135623730951 +# +# * Even a simple computation can introduce imprecision: +# +# x = 0.1 + 0.2 # => 0.30000000000000004 +# y = 0.3 # => 0.3 +# x == y # => false +# +# See: # # * https://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html # * https://github.com/rdp/ruby_tutorials_core/wiki/Ruby-Talk-FAQ#-why-are-rub # ys-floats-imprecise # * https://en.wikipedia.org/wiki/Floating_point#Accuracy_problems # +# Note that precise storage and computation of rational numbers is possible +# using Rational objects. +# +# ## Creating a Float +# # You can create a Float object explicitly with: # # * A [floating-point literal](rdoc-ref:syntax/literals.rdoc@Float+Literals). @@ -79,7 +257,7 @@ class Float < Numeric # rdoc-file=numeric.c # - self % other -> float # --> - # Returns `self` modulo `other` as a float. + # Returns `self` modulo `other` as a Float. # # For float `f` and real number `r`, these expressions are equivalent: # @@ -111,7 +289,7 @@ class Float < Numeric # rdoc-file=numeric.c # - self * other -> numeric # --> - # Returns a new Float which is the product of `self` and `other`: + # Returns the numeric product of `self` and `other`: # # f = 3.14 # f * 2 # => 6.28 @@ -124,9 +302,9 @@ class Float < Numeric # - # Raises `self` to the power of `other`: + # Returns `self` raised to the power `exponent`: # # f = 3.14 # f ** 2 # => 9.8596 @@ -140,15 +318,20 @@ class Float < Numeric # - # Returns a new Float which is the sum of `self` and `other`: + # Returns the sum of `self` and `other`; the result may be inexact (see Float): # - # f = 3.14 - # f + 1 # => 4.140000000000001 - # f + 1.0 # => 4.140000000000001 - # f + Rational(1, 1) # => 4.140000000000001 - # f + Complex(1, 0) # => (4.140000000000001+0i) + # 3.14 + 0 # => 3.14 + # 3.14 + 1 # => 4.140000000000001 + # -3.14 + 0 # => -3.14 + # -3.14 + 1 # => -2.14 + # + # 3.14 + -3.14 # => 0.0 + # -3.14 + -3.14 # => -6.28 + # + # 3.14 + Complex(1, 0) # => (4.140000000000001+0i) + # 3.14 + Rational(1, 1) # => 4.140000000000001 # def +: (Complex) -> Complex | (Numeric) -> Float @@ -157,7 +340,7 @@ class Float < Numeric # rdoc-file=numeric.c # - self - other -> numeric # --> - # Returns a new Float which is the difference of `self` and `other`: + # Returns the difference of `self` and `other`: # # f = 3.14 # f - 1 # => 2.14 @@ -170,9 +353,13 @@ class Float < Numeric # - # Returns `self`, negated. + # Returns `self`, negated: + # + # -3.14 # => -3.14 + # -(-3.14) # => 3.14 + # -0.0 # => -0.0 # def -@: () -> Float @@ -180,7 +367,7 @@ class Float < Numeric # rdoc-file=numeric.c # - self / other -> numeric # --> - # Returns a new Float which is the result of dividing `self` by `other`: + # Returns the quotient of `self` and `other`: # # f = 3.14 # f / 2 # => 1.57 @@ -626,7 +813,7 @@ class Float < Numeric alias magnitude abs # - # Returns `self` modulo `other` as a float. + # Returns `self` modulo `other` as a Float. # # For float `f` and real number `r`, these expressions are equivalent: # diff --git a/core/gc.rbs b/core/gc.rbs index 98217e265..868d05b88 100644 --- a/core/gc.rbs +++ b/core/gc.rbs @@ -281,7 +281,7 @@ module GC # execution both before the method returns and afterward; therefore # sweeping may not be completed before the return. # - # Note that these keword arguments are implementation- and version-dependent, + # Note that these keyword arguments are implementation- and version-dependent, # are not guaranteed to be future-compatible, and may be ignored in some # implementations. # @@ -351,8 +351,9 @@ module GC # * `:count`: The total number of garbage collections run since application # start (count includes both minor and major garbage collections). # * `:time`: The total time spent in garbage collections (in milliseconds). - # * `:heap_allocated_pages`: The total number of `:heap_eden_pages` + - # `:heap_tomb_pages`. + # * `:heap_allocated_pages`: The total number of allocated pages. + # * `:heap_empty_pages`: The number of pages with no live objects, and that + # could be released to the system. # * `:heap_sorted_length`: The number of pages that can fit into the buffer # that holds references to all pages. # * `:heap_allocatable_pages`: The total number of pages the application could @@ -367,8 +368,6 @@ module GC # * `:heap_marked_slots`: The total number of objects marked in the last GC. # * `:heap_eden_pages`: The total number of pages which contain at least one # live slot. - # * `:heap_tomb_pages`: The total number of pages which do not contain any - # live slots. # * `:total_allocated_pages`: The cumulative number of pages allocated since # application start. # * `:total_freed_pages`: The cumulative number of pages freed since @@ -582,10 +581,6 @@ module GC # * `:heap_eden_pages`: The number of pages in the eden heap. # * `:heap_eden_slots`: The total number of slots in all of the pages in the # eden heap. - # * `:heap_tomb_pages`: The number of pages in the tomb heap. The tomb heap - # only contains pages that do not have any live objects. - # * `:heap_tomb_slots`: The total number of slots in all of the pages in the - # tomb heap. # * `:total_allocated_pages`: The total number of pages that have been # allocated in the heap. # * `:total_freed_pages`: The total number of pages that have been freed and diff --git a/core/hash.rbs b/core/hash.rbs index c1ab14d31..9c8fb8396 100644 --- a/core/hash.rbs +++ b/core/hash.rbs @@ -547,7 +547,7 @@ class Hash[unchecked out K, unchecked out V] < Object # h < {foo: 0, bar: 1, baz: 2} # => false # Different key. # h < {foo: 0, bar: 1, baz: 2} # => false # Different value. # - # See [Hash Inclusion](rdoc-ref:hash_inclusion.rdoc). + # See [Hash Inclusion](rdoc-ref:language/hash_inclusion.rdoc). # # Raises TypeError if `other_hash` is not a hash and cannot be converted to a # hash. @@ -569,7 +569,7 @@ class Hash[unchecked out K, unchecked out V] < Object # h0 <= h1 # => true # h1 <= h0 # => false # - # See [Hash Inclusion](rdoc-ref:hash_inclusion.rdoc). + # See [Hash Inclusion](rdoc-ref:language/hash_inclusion.rdoc). # # Raises TypeError if `other_hash` is not a hash and cannot be converted to a # hash. @@ -621,7 +621,7 @@ class Hash[unchecked out K, unchecked out V] < Object # h > {foo: 0, bar: 1} # => false # Different key. # h > {foo: 0, bar: 1} # => false # Different value. # - # See [Hash Inclusion](rdoc-ref:hash_inclusion.rdoc). + # See [Hash Inclusion](rdoc-ref:language/hash_inclusion.rdoc). # # Raises TypeError if `other_hash` is not a hash and cannot be converted to a # hash. @@ -643,7 +643,7 @@ class Hash[unchecked out K, unchecked out V] < Object # h0 >= h0 # => true # h1 >= h0 # => false # - # See [Hash Inclusion](rdoc-ref:hash_inclusion.rdoc). + # See [Hash Inclusion](rdoc-ref:language/hash_inclusion.rdoc). # # Raises TypeError if `other_hash` is not a hash and cannot be converted to a # hash. diff --git a/core/integer.rbs b/core/integer.rbs index 1ff05487c..7baceef79 100644 --- a/core/integer.rbs +++ b/core/integer.rbs @@ -146,9 +146,9 @@ class Integer < Numeric # - # Returns `self` modulo `other` as a real number. + # Returns `self` modulo `other` as a real numeric (Integer, Float, or Rational). # # For integer `n` and real number `r`, these expressions are equivalent: # @@ -193,13 +193,13 @@ class Integer < Numeric # - # Performs multiplication: + # Returns the numeric product of `self` and `other`: # # 4 * 2 # => 8 - # 4 * -2 # => -8 # -4 * 2 # => -8 + # 4 * -2 # => -8 # 4 * 2.0 # => 8.0 # 4 * Rational(1, 3) # => (4/3) # 4 * Complex(2, 0) # => (8+0i) @@ -211,17 +211,47 @@ class Integer < Numeric # - # Raises `self` to the power of `numeric`: - # - # 2 ** 3 # => 8 - # 2 ** -3 # => (1/8) - # -2 ** 3 # => -8 - # -2 ** -3 # => (-1/8) - # 2 ** 3.3 # => 9.849155306759329 - # 2 ** Rational(3, 1) # => (8/1) - # 2 ** Complex(3, 0) # => (8+0i) + # Returns `self` raised to the power `exponent`: + # + # # Result for non-negative Integer exponent is Integer. + # 2 ** 0 # => 1 + # 2 ** 1 # => 2 + # 2 ** 2 # => 4 + # 2 ** 3 # => 8 + # -2 ** 3 # => -8 + # # Result for negative Integer exponent is Rational, not Float. + # 2 ** -3 # => (1/8) + # -2 ** -3 # => (-1/8) + # + # # Result for Float exponent is Float. + # 2 ** 0.0 # => 1.0 + # 2 ** 1.0 # => 2.0 + # 2 ** 2.0 # => 4.0 + # 2 ** 3.0 # => 8.0 + # -2 ** 3.0 # => -8.0 + # 2 ** -3.0 # => 0.125 + # -2 ** -3.0 # => -0.125 + # + # # Result for non-negative Complex exponent is Complex with Integer parts. + # 2 ** Complex(0, 0) # => (1+0i) + # 2 ** Complex(1, 0) # => (2+0i) + # 2 ** Complex(2, 0) # => (4+0i) + # 2 ** Complex(3, 0) # => (8+0i) + # -2 ** Complex(3, 0) # => (-8+0i) + # # Result for negative Complex exponent is Complex with Rational parts. + # 2 ** Complex(-3, 0) # => ((1/8)+(0/1)*i) + # -2 ** Complex(-3, 0) # => ((-1/8)+(0/1)*i) + # + # # Result for Rational exponent is Rational. + # 2 ** Rational(0, 1) # => (1/1) + # 2 ** Rational(1, 1) # => (2/1) + # 2 ** Rational(2, 1) # => (4/1) + # 2 ** Rational(3, 1) # => (8/1) + # -2 ** Rational(3, 1) # => (-8/1) + # 2 ** Rational(-3, 1) # => (1/8) + # -2 ** Rational(-3, 1) # => (-1/8) # def **: (Integer) -> Numeric | (Float) -> Numeric @@ -230,16 +260,20 @@ class Integer < Numeric # - # Performs addition: + # Returns the sum of `self` and `other`: + # + # 1 + 1 # => 2 + # 1 + -1 # => 0 + # 1 + 0 # => 1 + # 1 + -2 # => -1 + # 1 + Complex(1, 0) # => (2+0i) + # 1 + Rational(1, 1) # => (2/1) # - # 2 + 2 # => 4 - # -2 + 2 # => 0 - # -2 + -2 # => -4 - # 2 + 2.0 # => 4.0 - # 2 + Rational(2, 1) # => (4/1) - # 2 + Complex(2, 0) # => (4+0i) + # For a computation involving Floats, the result may be inexact (see Float#+): + # + # 1 + 3.14 # => 4.140000000000001 # def +: (Integer) -> Integer | (Float) -> Float @@ -248,9 +282,9 @@ class Integer < Numeric # - # Performs subtraction: + # Returns the difference of `self` and `other`: # # 4 - 2 # => 2 # -4 - 2 # => -6 @@ -266,28 +300,34 @@ class Integer < Numeric # - # Returns `self`, negated. + # Returns `self`, negated: + # + # -1 # => -1 + # -(-1) # => 1 + # -0 # => 0 # def -@: () -> Integer # - # Performs division; for integer `numeric`, truncates the result to an integer: + # Returns the quotient of `self` and `other`. + # + # For integer `other`, truncates the result to an integer: # - # 4 / 3 # => 1 - # 4 / -3 # => -2 - # -4 / 3 # => -2 - # -4 / -3 # => 1 + # 4 / 3 # => 1 + # 4 / -3 # => -2 + # -4 / 3 # => -2 + # -4 / -3 # => 1 # - # For other +numeric+, returns non-integer result: + # For non-integer `other`, returns a non-integer result: # - # 4 / 3.0 # => 1.3333333333333333 - # 4 / Rational(3, 1) # => (4/3) - # 4 / Complex(3, 0) # => ((4/3)+0i) + # 4 / 3.0 # => 1.3333333333333333 + # 4 / Rational(3, 1) # => (4/3) + # 4 / Complex(3, 0) # => ((4/3)+0i) # def /: (Integer) -> Integer | (Float) -> Float @@ -931,7 +971,7 @@ class Integer < Numeric def magnitude: () -> Integer # - # Returns `self` modulo `other` as a real number. + # Returns `self` modulo `other` as a real numeric (Integer, Float, or Rational). # # For integer `n` and real number `r`, these expressions are equivalent: # diff --git a/core/io.rbs b/core/io.rbs index bb8e28710..a82c96759 100644 --- a/core/io.rbs +++ b/core/io.rbs @@ -1373,7 +1373,7 @@ class IO < Object # Formats and writes `objects` to the stream. # # For details on `format_string`, see [Format - # Specifications](rdoc-ref:format_specifications.rdoc). + # Specifications](rdoc-ref:language/format_specifications.rdoc). # def printf: (String format_string, *untyped objects) -> nil @@ -2331,7 +2331,7 @@ class IO < Object # # When called from class IO (but not subclasses of IO), this method has # potential security vulnerabilities if called with untrusted input; see - # [Command Injection](rdoc-ref:command_injection.rdoc). + # [Command Injection](rdoc-ref:security/command_injection.rdoc). # def self.binread: (path name, ?Integer? length, ?Integer offset) -> String @@ -2344,7 +2344,7 @@ class IO < Object # # When called from class IO (but not subclasses of IO), this method has # potential security vulnerabilities if called with untrusted input; see - # [Command Injection](rdoc-ref:command_injection.rdoc). + # [Command Injection](rdoc-ref:security/command_injection.rdoc). # def self.binwrite: (path name, _ToS string, ?Integer offset, ?mode: String mode) -> Integer @@ -2409,7 +2409,7 @@ class IO < Object # connected to a new stream `io`. # # This method has potential security vulnerabilities if called with untrusted - # input; see [Command Injection](rdoc-ref:command_injection.rdoc). + # input; see [Command Injection](rdoc-ref:security/command_injection.rdoc). # # If no block is given, returns the new stream, which depending on given `mode` # may be open for reading, writing, or both. The stream should be explicitly @@ -2584,7 +2584,7 @@ class IO < Object # # When called from class IO (but not subclasses of IO), this method has # potential security vulnerabilities if called with untrusted input; see - # [Command Injection](rdoc-ref:command_injection.rdoc). + # [Command Injection](rdoc-ref:security/command_injection.rdoc). # # The first argument must be a string that is the path to a file. # @@ -2741,7 +2741,7 @@ class IO < Object # # When called from class IO (but not subclasses of IO), this method has # potential security vulnerabilities if called with untrusted input; see - # [Command Injection](rdoc-ref:command_injection.rdoc). + # [Command Injection](rdoc-ref:security/command_injection.rdoc). # # The first argument must be a string that is the path to a file. # @@ -2784,7 +2784,7 @@ class IO < Object # # When called from class IO (but not subclasses of IO), this method has # potential security vulnerabilities if called with untrusted input; see - # [Command Injection](rdoc-ref:command_injection.rdoc). + # [Command Injection](rdoc-ref:security/command_injection.rdoc). # # The first argument must be a string that is the path to a file. # @@ -3009,7 +3009,7 @@ class IO < Object # # When called from class IO (but not subclasses of IO), this method has # potential security vulnerabilities if called with untrusted input; see - # [Command Injection](rdoc-ref:command_injection.rdoc). + # [Command Injection](rdoc-ref:security/command_injection.rdoc). # # The first argument must be a string that is the path to a file. # diff --git a/core/io/buffer.rbs b/core/io/buffer.rbs index 5087d2615..e7f3ed0fd 100644 --- a/core/io/buffer.rbs +++ b/core/io/buffer.rbs @@ -131,18 +131,25 @@ class IO # - IO::Buffer.map(file, [size, [offset, [flags]]]) -> io_buffer # --> # Create an IO::Buffer for reading from `file` by memory-mapping the file. - # `file_io` should be a `File` instance, opened for reading. + # `file` should be a `File` instance, opened for reading or reading and writing. # - # Optional `size` and `offset` of mapping can be specified. + # Optional `size` and `offset` of mapping can be specified. Trying to map an + # empty file or specify `size` of 0 will raise an error. Valid values for + # `offset` are system-dependent. # - # By default, the buffer would be immutable (read only); to create a writable - # mapping, you need to open a file in read-write mode, and explicitly pass - # `flags` argument without IO::Buffer::IMMUTABLE. + # By default, the buffer is writable and expects the file to be writable. It is + # also shared, so several processes can use the same mapping. + # + # You can pass IO::Buffer::READONLY in `flags` argument to make a read-only + # buffer; this allows to work with files opened only for reading. Specifying + # IO::Buffer::PRIVATE in `flags` creates a private mapping, which will not + # impact other processes or the underlying file. It also allows updating a + # buffer created from a read-only file. # # File.write('test.txt', 'test') # # buffer = IO::Buffer.map(File.open('test.txt'), nil, 0, IO::Buffer::READONLY) - # # => # + # # => # # # buffer.readonly? # => true # @@ -150,7 +157,7 @@ class IO # # => "test" # # buffer.set_string('b', 0) - # # `set_string': Buffer is not writable! (IO::Buffer::AccessError) + # # 'IO::Buffer#set_string': Buffer is not writable! (IO::Buffer::AccessError) # # # create read/write mapping: length 4 bytes, offset 0, flags 0 # buffer = IO::Buffer.map(File.open('test.txt', 'r+'), 4, 0) @@ -382,6 +389,10 @@ class IO # * `:U64`: unsigned integer, 8 bytes, big-endian # * `:s64`: signed integer, 8 bytes, little-endian # * `:S64`: signed integer, 8 bytes, big-endian + # * `:u128`: unsigned integer, 16 bytes, little-endian + # * `:U128`: unsigned integer, 16 bytes, big-endian + # * `:s128`: signed integer, 16 bytes, little-endian + # * `:S128`: signed integer, 16 bytes, big-endian # * `:f32`: float, 4 bytes, little-endian # * `:F32`: float, 4 bytes, big-endian # * `:f64`: double, 8 bytes, little-endian diff --git a/core/kernel.rbs b/core/kernel.rbs index 777ea2947..9a50d9684 100644 --- a/core/kernel.rbs +++ b/core/kernel.rbs @@ -718,7 +718,7 @@ module Kernel : BasicObject # variable `$?` to the process status. # # This method has potential security vulnerabilities if called with untrusted - # input; see [Command Injection](rdoc-ref:command_injection.rdoc). + # input; see [Command Injection](rdoc-ref:security/command_injection.rdoc). # # Examples: # @@ -1118,7 +1118,7 @@ module Kernel : BasicObject # Returns the string resulting from formatting `objects` into `format_string`. # # For details on `format_string`, see [Format - # Specifications](rdoc-ref:format_specifications.rdoc). + # Specifications](rdoc-ref:language/format_specifications.rdoc). # def self?.format: (String format, *untyped args) -> String @@ -1129,7 +1129,7 @@ module Kernel : BasicObject # Returns the string resulting from formatting `objects` into `format_string`. # # For details on `format_string`, see [Format - # Specifications](rdoc-ref:format_specifications.rdoc). + # Specifications](rdoc-ref:language/format_specifications.rdoc). # alias sprintf format @@ -1249,7 +1249,7 @@ module Kernel : BasicObject # Creates an IO object connected to the given file. # # This method has potential security vulnerabilities if called with untrusted - # input; see [Command Injection](rdoc-ref:command_injection.rdoc). + # input; see [Command Injection](rdoc-ref:security/command_injection.rdoc). # # With no block given, file stream is returned: # @@ -1327,7 +1327,7 @@ module Kernel : BasicObject # io.write(sprintf(format_string, *objects)) # # For details on `format_string`, see [Format - # Specifications](rdoc-ref:format_specifications.rdoc). + # Specifications](rdoc-ref:language/format_specifications.rdoc). # # With the single argument `format_string`, formats `objects` into the string, # then writes the formatted string to $stdout: @@ -1907,7 +1907,7 @@ module Kernel : BasicObject # * Invoking the executable at `exe_path`. # # This method has potential security vulnerabilities if called with untrusted - # input; see [Command Injection](rdoc-ref:command_injection.rdoc). + # input; see [Command Injection](rdoc-ref:security/command_injection.rdoc). # # The new process is created using the [exec system # call](https://pubs.opengroup.org/onlinepubs/9699919799.2018edition/functions/e @@ -1999,7 +1999,7 @@ module Kernel : BasicObject # * Invoking the executable at `exe_path`. # # This method has potential security vulnerabilities if called with untrusted - # input; see [Command Injection](rdoc-ref:command_injection.rdoc). + # input; see [Command Injection](rdoc-ref:security/command_injection.rdoc). # # Returns the process ID (pid) of the new process, without waiting for it to # complete. @@ -2102,7 +2102,7 @@ module Kernel : BasicObject # * Invoking the executable at `exe_path`. # # This method has potential security vulnerabilities if called with untrusted - # input; see [Command Injection](rdoc-ref:command_injection.rdoc). + # input; see [Command Injection](rdoc-ref:security/command_injection.rdoc). # # Returns: # diff --git a/core/module.rbs b/core/module.rbs index 8bbc2a7f1..0f9c8b20b 100644 --- a/core/module.rbs +++ b/core/module.rbs @@ -135,14 +135,25 @@ class Module < Object # - # Comparison---Returns -1, 0, +1 or nil depending on whether `module` includes - # `other_module`, they are the same, or if `module` is included by - # `other_module`. + # Returns: # - # Returns `nil` if `module` has no relationship with `other_module`, if - # `other_module` is not a module, or if the two values are incomparable. + # * `-1`, if `self` includes `object`, if or `self` is a subclass of `object`. + # * `0`, if `self` and `object` are the same. + # * `1`, if `object` includes `self`, or if `object` is a subclass of `self`. + # * `nil`, if none of the above is true. + # + # Examples: + # + # # Class Array includes module Enumerable. + # Array <=> Enumerable # => -1 + # Enumerable <=> Enumerable # => 0 + # Enumerable <=> Array # => 1 + # # Class File is a subclass of class IO. + # File <=> IO # => -1 + # IO <=> File # => 1 + # File <=> File # => 0 # def <=>: (untyped other) -> Integer? diff --git a/core/numeric.rbs b/core/numeric.rbs index 8e3f037bc..0928b38db 100644 --- a/core/numeric.rbs +++ b/core/numeric.rbs @@ -160,7 +160,7 @@ class Numeric # rdoc-file=numeric.c # - self % other -> real_numeric # --> - # Returns `self` modulo `other` as a real number. + # Returns `self` modulo `other` as a real numeric (Integer, Float, or Rational). # # Of the Core and Standard Library classes, only Rational uses this # implementation. @@ -212,7 +212,7 @@ class Numeric # rdoc-file=numeric.c # - -self -> numeric # --> - # Unary Minus---Returns the receiver, negated. + # Returns `self`, negated. # def -@: () -> self @@ -336,7 +336,7 @@ class Numeric # - div(other) -> integer # --> # Returns the quotient `self/other` as an integer (via `floor`), using method - # `/` in the derived class of `self`. (Numeric itself does not define method + # `/` as defined in the subclass of Numeric. (Numeric itself does not define # `/`.) # # Of the Core and Standard Library classes, Only Float and Rational use this @@ -398,8 +398,8 @@ class Numeric # rdoc-file=numeric.c # - fdiv(other) -> float # --> - # Returns the quotient `self/other` as a float, using method `/` in the derived - # class of `self`. (Numeric itself does not define method `/`.) + # Returns the quotient `self/other` as a float, using method `/` as defined in + # the subclass of Numeric. (Numeric itself does not define `/`.) # # Of the Core and Standard Library classes, only BigDecimal uses this # implementation. @@ -488,7 +488,7 @@ class Numeric alias magnitude abs # - # Returns `self` modulo `other` as a real number. + # Returns `self` modulo `other` as a real numeric (Integer, Float, or Rational). # # Of the Core and Standard Library classes, only Rational uses this # implementation. @@ -765,8 +765,8 @@ class Numeric # rdoc-file=numeric.c # - to_int -> integer # --> - # Returns `self` as an integer; converts using method `to_i` in the derived - # class. + # Returns `self` as an integer; converts using method `to_i` in the subclass of + # Numeric. (Numeric itself does not define `to_i`.) # # Of the Core and Standard Library classes, only Rational and Complex use this # implementation. diff --git a/core/object_space.rbs b/core/object_space.rbs index 8e58cefe6..ab1622c5b 100644 --- a/core/object_space.rbs +++ b/core/object_space.rbs @@ -137,33 +137,26 @@ module ObjectSpace # Calls the block once for each living, nonimmediate object in this Ruby # process. If *module* is specified, calls the block for only those classes or # modules that match (or are a subclass of) *module*. Returns the number of - # objects found. Immediate objects (`Fixnum`s, `Symbol`s `true`, `false`, and - # `nil`) are never returned. In the example below, #each_object returns both the - # numbers we defined and several constants defined in the Math module. + # objects found. Immediate objects (such as `Fixnum`s, static `Symbol`s `true`, + # `false` and `nil`) are never returned. # # If no block is given, an enumerator is returned instead. # - # a = 102.7 - # b = 95 # Won't be returned - # c = 12345678987654321 - # count = ObjectSpace.each_object(Numeric) {|x| p x } + # Job = Class.new + # jobs = [Job.new, Job.new] + # count = ObjectSpace.each_object(Job) {|x| p x } # puts "Total count: #{count}" # # *produces:* # - # 12345678987654321 - # 102.7 - # 2.71828182845905 - # 3.14159265358979 - # 2.22044604925031e-16 - # 1.7976931348623157e+308 - # 2.2250738585072e-308 - # Total count: 7 - # - # Due to a current known Ractor implementation issue, this method will not yield - # Ractor-unshareable objects in multi-Ractor mode (when `Ractor.new` has been - # called within the process at least once). See - # https://bugs.ruby-lang.org/issues/19387 for more information. + # # + # # + # Total count: 2 + # + # Due to a current Ractor implementation issue, this method does not yield + # Ractor-unshareable objects when the process is in multi-Ractor mode. + # Multi-ractor mode is enabled when `Ractor.new` has been called for the first + # time. See https://bugs.ruby-lang.org/issues/19387 for more information. # # a = 12345678987654321 # shareable # b = [].freeze # shareable diff --git a/core/pathname.rbs b/core/pathname.rbs index 607d50c3f..9baf1cbcd 100644 --- a/core/pathname.rbs +++ b/core/pathname.rbs @@ -712,6 +712,7 @@ class Pathname # rdoc-file=pathname_builtin.rb # - freeze() # --> + # Freze self. # def freeze: () -> Pathname @@ -1154,9 +1155,7 @@ class Pathname # def taint: () -> Pathname - # - # Return the path as a String. - # + # # to_path is implemented so Pathname objects are usable with File.open, etc. # def to_path: () -> String diff --git a/core/ractor.rbs b/core/ractor.rbs index 561e08c21..b8b34e624 100644 --- a/core/ractor.rbs +++ b/core/ractor.rbs @@ -382,7 +382,7 @@ class Ractor # # It returns shareable Proc object. The Proc object is shareable and the self in # a block will be replaced with the value passed via `self:` keyword. @@ -393,7 +393,7 @@ class Ractor # Ractor.shareable_proc{ p a } # #=> can not isolate a Proc because it accesses outer variables (a). (ArgumentError) # - # The `self` should be a sharable object + # The `self` should be a shareable object # # Ractor.shareable_proc(self: self){} # #=> self should be shareable: main (Ractor::IsolationError) @@ -403,9 +403,9 @@ class Ractor # - # Same as Ractor.sharable_proc, but returns lambda proc. + # Same as Ractor.shareable_proc, but returns lambda proc. # def self.shareable_lambda: [T] () { (?) [self: nil] -> T } -> ^(?) [self: nil] -> T | [T, S] (self: S) { (?) [self: S] -> T } -> ^(?) [self: S] -> T diff --git a/core/range.rbs b/core/range.rbs index 9eee56627..09838ed5f 100644 --- a/core/range.rbs +++ b/core/range.rbs @@ -351,7 +351,7 @@ class Range[out Elem] < Object # --> # Returns an element from `self` selected by a binary search. # - # See [Binary Searching](rdoc-ref:bsearch.rdoc). + # See [Binary Searching](rdoc-ref:language/bsearch.rdoc). # def bsearch: () -> ::Enumerator[Elem, Elem?] | () { (Elem) -> (true | false) } -> Elem? diff --git a/core/rational.rbs b/core/rational.rbs index fc91a4ef9..891027ed1 100644 --- a/core/rational.rbs +++ b/core/rational.rbs @@ -53,15 +53,16 @@ class Rational < Numeric # - # Performs multiplication. + # Returns the numeric product of `self` and `other`: # - # Rational(2, 3) * Rational(2, 3) #=> (4/9) - # Rational(900) * Rational(1) #=> (900/1) - # Rational(-2, 9) * Rational(-9, 2) #=> (1/1) - # Rational(9, 8) * 4 #=> (9/2) - # Rational(20, 9) * 9.8 #=> 21.77777777777778 + # Rational(9, 8) * 4 #=> (9/2) + # Rational(20, 9) * 9.8 #=> 21.77777777777778 + # Rational(9, 8) * Complex(1, 2) # => ((9/8)+(9/4)*i) + # Rational(2, 3) * Rational(2, 3) #=> (4/9) + # Rational(900) * Rational(1) #=> (900/1) + # Rational(-2, 9) * Rational(-9, 2) #=> (1/1) # def *: (Integer) -> Rational | (Rational) -> Rational @@ -69,9 +70,9 @@ class Rational < Numeric # - # Performs exponentiation. + # Returns `self` raised to the power `exponent`: # # Rational(2) ** Rational(3) #=> (8/1) # Rational(10) ** -2 #=> (1/100) @@ -85,15 +86,25 @@ class Rational < Numeric # - # Performs addition. + # Returns the sum of `self` and `other`: # - # Rational(2, 3) + Rational(2, 3) #=> (4/3) - # Rational(900) + Rational(1) #=> (901/1) - # Rational(-2, 9) + Rational(-9, 2) #=> (-85/18) - # Rational(9, 8) + 4 #=> (41/8) - # Rational(20, 9) + 9.8 #=> 12.022222222222222 + # Rational(2, 3) + 0 # => (2/3) + # Rational(2, 3) + 1 # => (5/3) + # Rational(2, 3) + -1 # => (-1/3) + # + # Rational(2, 3) + Complex(1, 0) # => ((5/3)+0i) + # + # Rational(2, 3) + Rational(1, 1) # => (5/3) + # Rational(2, 3) + Rational(3, 2) # => (13/6) + # Rational(2, 3) + Rational(3.0, 2.0) # => (13/6) + # Rational(2, 3) + Rational(3.1, 2.1) # => (30399297484750849/14186338826217063) + # + # For a computation involving Floats, the result may be inexact (see Float#+): + # + # Rational(2, 3) + 1.0 # => 1.6666666666666665 + # Rational(2, 3) + Complex(1.0, 0.0) # => (1.6666666666666665+0.0i) # def +: (Float) -> Float | (Complex) -> Complex @@ -101,9 +112,9 @@ class Rational < Numeric # - # Performs subtraction. + # Returns the difference of `self` and `other`: # # Rational(2, 3) - Rational(2, 3) #=> (0/1) # Rational(900) - Rational(1) #=> (899/1) @@ -117,18 +128,20 @@ class Rational < Numeric # - # Negates `rat`. + # Returns `self`, negated: + # + # -(1/3r) # => (-1/3) + # -(-1/3r) # => (1/3) # def -@: () -> Rational # - # Performs division. + # Returns the quotient of `self` and `other`: # # Rational(2, 3) / Rational(2, 3) #=> (1/1) # Rational(900) / Rational(1) #=> (900/1) @@ -330,7 +343,7 @@ class Rational < Numeric def positive?: () -> bool # - # Performs division. + # Returns the quotient of `self` and `other`: # # Rational(2, 3) / Rational(2, 3) #=> (1/1) # Rational(900) / Rational(1) #=> (900/1) diff --git a/core/rbs/unnamed/argf.rbs b/core/rbs/unnamed/argf.rbs index e3081062e..d2ca18293 100644 --- a/core/rbs/unnamed/argf.rbs +++ b/core/rbs/unnamed/argf.rbs @@ -836,7 +836,7 @@ module RBS # Formats and writes `objects` to the stream. # # For details on `format_string`, see [Format - # Specifications](rdoc-ref:format_specifications.rdoc). + # Specifications](rdoc-ref:language/format_specifications.rdoc). # %a{annotate:rdoc:copy:ARGF#printf} def printf: (String format_string, *untyped args) -> nil diff --git a/core/regexp.rbs b/core/regexp.rbs index 7f6473dd3..6224bd305 100644 --- a/core/regexp.rbs +++ b/core/regexp.rbs @@ -39,7 +39,7 @@ # most such methods accept an argument that may be either a string or the # (much more powerful) regexp. # -# See [Regexp Methods](rdoc-ref:regexp/methods.rdoc). +# See [Regexp Methods](rdoc-ref:language/regexp/methods.rdoc). # # ## Regexp Objects # @@ -821,8 +821,8 @@ # /\P{Alpha}/.match('1') # => # # /\P{Alpha}/.match('a') # => nil # -# See [Unicode Properties](rdoc-ref:regexp/unicode_properties.rdoc) for regexps -# based on the numerous properties. +# See [Unicode Properties](rdoc-ref:language/regexp/unicode_properties.rdoc) for +# regexps based on the numerous properties. # # Some commonly-used properties correspond to POSIX bracket expressions: # diff --git a/core/rubygems/version.rbs b/core/rubygems/version.rbs index 1687d7ff2..7aec81635 100644 --- a/core/rubygems/version.rbs +++ b/core/rubygems/version.rbs @@ -180,7 +180,6 @@ module Gem # # ver1 = Version.create('1.3.17') # -> (Version object) # ver2 = Version.create(ver1) # -> (ver1) - # ver3 = Version.create(nil) # -> nil # def self.create: (_ToS | Version input) -> instance | (nil input) -> nil @@ -199,8 +198,8 @@ module Gem # - <=>(other) # --> # Compares this version with `other` returning -1, 0, or 1 if the other version - # is larger, the same, or smaller than this one. Attempts to compare to - # something that's not a `Gem::Version` or a valid version String return `nil`. + # is larger, the same, or smaller than this one. `other` must be an instance of + # Gem::Version, comparing with other types may raise an exception. # def <=>: (untyped other) -> Integer? diff --git a/core/set.rbs b/core/set.rbs index cbe887c51..2e6717cb7 100644 --- a/core/set.rbs +++ b/core/set.rbs @@ -1,16 +1,9 @@ # -# Copyright (c) 2002-2024 Akinori MUSHA -# -# Documentation by Akinori MUSHA and Gavin Sinclair. -# -# All rights reserved. You can redistribute and/or modify it under the same -# terms as Ruby. -# # The Set class implements a collection of unordered values with no duplicates. # It is a hybrid of Array's intuitive inter-operation facilities and Hash's fast # lookup. # -# Set is easy to use with Enumerable objects (implementing `each`). Most of the +# Set is easy to use with Enumerable objects (implementing #each). Most of the # initializer methods and binary operators accept generic Enumerable objects # besides sets and arrays. An Enumerable object can be converted to Set using # the `to_set` method. @@ -36,11 +29,11 @@ # # ## Example # -# s1 = Set[1, 2] #=> # -# s2 = [1, 2].to_set #=> # +# s1 = Set[1, 2] #=> Set[1, 2] +# s2 = [1, 2].to_set #=> Set[1, 2] # s1 == s2 #=> true -# s1.add("foo") #=> # -# s1.merge([2, 6]) #=> # +# s1.add("foo") #=> Set[1, 2, "foo"] +# s1.merge([2, 6]) #=> Set[1, 2, "foo", 6] # s1.subset?(s2) #=> false # s2.subset?(s1) #=> true # @@ -48,9 +41,39 @@ # # * Akinori MUSHA (current maintainer) # -# ## What's Here +# ## Inheriting from Set +# +# Before Ruby 4.0 (released December 2025), Set had a different, less efficient +# implementation. It was reimplemented in C, and the behavior of some of the +# core methods were adjusted. +# +# To keep backward compatibility, when a class is inherited from Set, additional +# module `Set::SubclassCompatible` is included, which makes the inherited class +# behavior, as well as internal method names, closer to what it was before Ruby +# 4.0. +# +# It can be easily seen, for example, in the #inspect method behavior: +# +# p Set[1, 2, 3] +# # prints "Set[1, 2, 3]" +# +# class MySet < Set +# end +# p MySet[1, 2, 3] +# # prints "#", like it was in Ruby 3.4 +# +# For new code, if backward compatibility is not necessary, it is recommended to +# instead inherit from `Set::CoreSet`, which avoids including the +# "compatibility" layer: +# +# class MyCoreSet < Set::CoreSet +# end +# p MyCoreSet[1, 2, 3] +# # prints "MyCoreSet[1, 2, 3]" +# +# ## Set's methods # -# First, what's elsewhere. \Class \Set: +# First, what's elsewhere. Class Set: # # * Inherits from [class Object](rdoc-ref:Object@What-27s+Here). # * Includes [module Enumerable](rdoc-ref:Enumerable@What-27s+Here), which @@ -61,16 +84,15 @@ # # Here, class Set provides methods that are useful for: # -# * [Creating an Array](rdoc-ref:Array@Methods+for+Creating+an+Array) # * [Creating a Set](rdoc-ref:Set@Methods+for+Creating+a+Set) # * [Set Operations](rdoc-ref:Set@Methods+for+Set+Operations) -# * [Comparing](rdoc-ref:Array@Methods+for+Comparing) -# * [Querying](rdoc-ref:Array@Methods+for+Querying) -# * [Assigning](rdoc-ref:Array@Methods+for+Assigning) -# * [Deleting](rdoc-ref:Array@Methods+for+Deleting) -# * [Converting](rdoc-ref:Array@Methods+for+Converting) -# * [Iterating](rdoc-ref:Array@Methods+for+Iterating) -# * [And more....](rdoc-ref:Array@Other+Methods) +# * [Comparing](rdoc-ref:Set@Methods+for+Comparing) +# * [Querying](rdoc-ref:Set@Methods+for+Querying) +# * [Assigning](rdoc-ref:Set@Methods+for+Assigning) +# * [Deleting](rdoc-ref:Set@Methods+for+Deleting) +# * [Converting](rdoc-ref:Set@Methods+for+Converting) +# * [Iterating](rdoc-ref:Set@Methods+for+Iterating) +# * [And more....](rdoc-ref:Set@Other+Methods) # # ### Methods for Creating a Set # @@ -183,11 +205,11 @@ class Set[unchecked out A] # # If a block is given, the elements of enum are preprocessed by the given block. # - # Set.new([1, 2]) #=> # - # Set.new([1, 2, 1]) #=> # - # Set.new([1, 'c', :s]) #=> # - # Set.new(1..5) #=> # - # Set.new([1, 2, 3]) { |x| x * x } #=> # + # Set.new([1, 2]) #=> Set[1, 2] + # Set.new([1, 2, 1]) #=> Set[1, 2] + # Set.new([1, 'c', :s]) #=> Set[1, "c", :s] + # Set.new(1..5) #=> Set[1, 2, 3, 4, 5] + # Set.new([1, 2, 3]) { |x| x * x } #=> Set[1, 4, 9] # def initialize: (_Each[A]) -> untyped | [X] (_Each[X]) { (X) -> A } -> untyped @@ -208,8 +230,8 @@ class Set[unchecked out A] # Returns a new set containing elements common to the set and the given # enumerable object. # - # Set[1, 3, 5] & Set[3, 2, 1] #=> # - # Set['a', 'b', 'z'] & ['a', 'b', 'c'] #=> # + # Set[1, 3, 5] & Set[3, 2, 1] #=> Set[3, 1] + # Set['a', 'b', 'z'] & ['a', 'b', 'c'] #=> Set["a", "b"] # def &: (_Each[A]) -> self @@ -217,8 +239,8 @@ class Set[unchecked out A] # Returns a new set containing elements common to the set and the given # enumerable object. # - # Set[1, 3, 5] & Set[3, 2, 1] #=> # - # Set['a', 'b', 'z'] & ['a', 'b', 'c'] #=> # + # Set[1, 3, 5] & Set[3, 2, 1] #=> Set[3, 1] + # Set['a', 'b', 'z'] & ['a', 'b', 'c'] #=> Set["a", "b"] # alias intersection & @@ -229,8 +251,8 @@ class Set[unchecked out A] # Returns a new set built by merging the set and the elements of the given # enumerable object. # - # Set[1, 2, 3] | Set[2, 4, 5] #=> # - # Set[1, 5, 'z'] | (1..6) #=> # + # Set[1, 2, 3] | Set[2, 4, 5] #=> Set[1, 2, 3, 4, 5] + # Set[1, 5, 'z'] | (1..6) #=> Set[1, 5, "z", 2, 3, 4, 6] # def |: (_Each[A]) -> self @@ -238,8 +260,8 @@ class Set[unchecked out A] # Returns a new set built by merging the set and the elements of the given # enumerable object. # - # Set[1, 2, 3] | Set[2, 4, 5] #=> # - # Set[1, 5, 'z'] | (1..6) #=> # + # Set[1, 2, 3] | Set[2, 4, 5] #=> Set[1, 2, 3, 4, 5] + # Set[1, 5, 'z'] | (1..6) #=> Set[1, 5, "z", 2, 3, 4, 6] # alias union | @@ -247,8 +269,8 @@ class Set[unchecked out A] # Returns a new set built by merging the set and the elements of the given # enumerable object. # - # Set[1, 2, 3] | Set[2, 4, 5] #=> # - # Set[1, 5, 'z'] | (1..6) #=> # + # Set[1, 2, 3] | Set[2, 4, 5] #=> Set[1, 2, 3, 4, 5] + # Set[1, 5, 'z'] | (1..6) #=> Set[1, 5, "z", 2, 3, 4, 6] # alias + | @@ -259,8 +281,8 @@ class Set[unchecked out A] # Returns a new set built by duplicating the set, removing every element that # appears in the given enumerable object. # - # Set[1, 3, 5] - Set[1, 5] #=> # - # Set['a', 'b', 'z'] - ['a', 'c'] #=> # + # Set[1, 3, 5] - Set[1, 5] #=> Set[3] + # Set['a', 'b', 'z'] - ['a', 'c'] #=> Set["b", "z"] # def -: (_Each[A]) -> self @@ -268,8 +290,8 @@ class Set[unchecked out A] # Returns a new set built by duplicating the set, removing every element that # appears in the given enumerable object. # - # Set[1, 3, 5] - Set[1, 5] #=> # - # Set['a', 'b', 'z'] - ['a', 'c'] #=> # + # Set[1, 3, 5] - Set[1, 5] #=> Set[3] + # Set['a', 'b', 'z'] - ['a', 'c'] #=> Set["b", "z"] # alias difference - @@ -280,9 +302,9 @@ class Set[unchecked out A] # Adds the given object to the set and returns self. Use `merge` to add many # elements at once. # - # Set[1, 2].add(3) #=> # - # Set[1, 2].add([3, 4]) #=> # - # Set[1, 2].add(2) #=> # + # Set[1, 2].add(3) #=> Set[1, 2, 3] + # Set[1, 2].add([3, 4]) #=> Set[1, 2, [3, 4]] + # Set[1, 2].add(2) #=> Set[1, 2] # def add: (A) -> self @@ -290,9 +312,9 @@ class Set[unchecked out A] # Adds the given object to the set and returns self. Use `merge` to add many # elements at once. # - # Set[1, 2].add(3) #=> # - # Set[1, 2].add([3, 4]) #=> # - # Set[1, 2].add(2) #=> # + # Set[1, 2].add(3) #=> Set[1, 2, 3] + # Set[1, 2].add([3, 4]) #=> Set[1, 2, [3, 4]] + # Set[1, 2].add(2) #=> Set[1, 2] # alias << add @@ -303,8 +325,8 @@ class Set[unchecked out A] # Adds the given object to the set and returns self. If the object is already in # the set, returns nil. # - # Set[1, 2].add?(3) #=> # - # Set[1, 2].add?([3, 4]) #=> # + # Set[1, 2].add?(3) #=> Set[1, 2, 3] + # Set[1, 2].add?([3, 4]) #=> Set[1, 2, [3, 4]] # Set[1, 2].add?(2) #=> nil # def add?: (A) -> self? @@ -366,8 +388,8 @@ class Set[unchecked out A] # enumerable object. `(set ^ enum)` is equivalent to `((set | enum) - (set & # enum))`. # - # Set[1, 2] ^ Set[2, 3] #=> # - # Set[1, 'b', 'c'] ^ ['b', 'd'] #=> # + # Set[1, 2] ^ Set[2, 3] #=> Set[3, 1] + # Set[1, 'b', 'c'] ^ ['b', 'd'] #=> Set["d", 1, "c"] # def ^: (_Each[A]) -> self @@ -382,9 +404,9 @@ class Set[unchecked out A] # # files = Set.new(Dir.glob("*.rb")) # hash = files.classify { |f| File.mtime(f).year } - # hash #=> {2000 => #, - # # 2001 => #, - # # 2002 => #} + # hash #=> {2000 => Set["a.rb", "b.rb"], + # # 2001 => Set["c.rb", "d.rb", "e.rb"], + # # 2002 => Set["f.rb"]} # # Returns an enumerator if no block is given. # @@ -396,9 +418,9 @@ class Set[unchecked out A] # --> # Removes all elements and returns self. # - # set = Set[1, 'c', :s] #=> # - # set.clear #=> # - # set #=> # + # set = Set[1, 'c', :s] #=> Set[1, "c", :s] + # set.clear #=> Set[] + # set #=> Set[] # def clear: () -> self @@ -502,10 +524,10 @@ class Set[unchecked out A] # # numbers = Set[1, 3, 4, 6, 9, 10, 11] # set = numbers.divide { |i,j| (i - j).abs == 1 } - # set #=> #, - # # #, - # # #}> - # # #, + # set #=> Set[Set[1], + # # Set[3, 4], + # # Set[6], + # # Set[9, 10, 11]] # # Returns an enumerator if no block is given. # @@ -654,9 +676,9 @@ class Set[unchecked out A] # Replaces the contents of the set with the contents of the given enumerable # object and returns self. # - # set = Set[1, 'c', :s] #=> # - # set.replace([1, 2]) #=> # - # set #=> # + # set = Set[1, 'c', :s] #=> Set[1, "c", :s] + # set.replace([1, 2]) #=> Set[1, 2] + # set #=> Set[1, 2] # def replace: (_Each[A]) -> self diff --git a/core/string.rbs b/core/string.rbs index 93ddb1fed..f9e49719d 100644 --- a/core/string.rbs +++ b/core/string.rbs @@ -187,10 +187,10 @@ # # *Counts* # -# * #length (aliased as #size): Returns the count of characters (not bytes). -# * #empty?: Returns whether the length of `self` is zero. # * #bytesize: Returns the count of bytes. # * #count: Returns the count of substrings matching given strings. +# * #empty?: Returns whether the length of `self` is zero. +# * #length (aliased as #size): Returns the count of characters (not bytes). # # *Substrings* # @@ -350,8 +350,8 @@ # *Substitution* # # * #dump: Returns a printable version of `self`, enclosed in double-quotes. -# * #undump: Returns a copy of `self` with all `\xNN` notations replaced by -# `\uNNNN` notations and all escaped characters unescaped. +# * #undump: Inverse of #dump; returns a copy of `self` with changes of the +# kinds made by #dump "undone." # * #sub: Returns a copy of `self` with the first substring matching a given # pattern replaced with a given replacement string. # * #gsub: Returns a copy of `self` with each substring that matches a given @@ -660,10 +660,10 @@ # # *Counts* # -# * #length (aliased as #size): Returns the count of characters (not bytes). -# * #empty?: Returns whether the length of `self` is zero. # * #bytesize: Returns the count of bytes. # * #count: Returns the count of substrings matching given strings. +# * #empty?: Returns whether the length of `self` is zero. +# * #length (aliased as #size): Returns the count of characters (not bytes). # # *Substrings* # @@ -823,8 +823,8 @@ # *Substitution* # # * #dump: Returns a printable version of `self`, enclosed in double-quotes. -# * #undump: Returns a copy of `self` with all `\xNN` notations replaced by -# `\uNNNN` notations and all escaped characters unescaped. +# * #undump: Inverse of #dump; returns a copy of `self` with changes of the +# kinds made by #dump "undone." # * #sub: Returns a copy of `self` with the first substring matching a given # pattern replaced with a given replacement string. # * #gsub: Returns a copy of `self` with each substring that matches a given @@ -1042,7 +1042,7 @@ class String # --> # Returns the result of formatting `object` into the format specifications # contained in `self` (see [Format - # Specifications](rdoc-ref:format_specifications.rdoc)): + # Specifications](rdoc-ref:language/format_specifications.rdoc)): # # '%05d' % 123 # => "00123" # @@ -1306,7 +1306,7 @@ class String # 'hello'[0] # => "h" # 'hello'[4] # => "o" # 'hello'[5] # => nil - # 'тест'[2] # => "с" + # 'Привет'[2] # => "и" # 'こんにちは'[4] # => "は" # # With negative integer argument `index` given, counts backward from the end of @@ -1387,7 +1387,7 @@ class String # 'hello'['ell'] # => "ell" # 'hello'[''] # => "" # 'hello'['nosuch'] # => nil - # 'тест'['ес'] # => "ес" + # 'Привет'['ив'] # => "ив" # 'こんにちは'['んにち'] # => "んにち" # # Related: see [Converting to New @@ -1449,7 +1449,7 @@ class String # size `length` characters (as available) beginning at character offset # specified by `start`. # - # If argument `start` is non-negative, the offset is +start': + # If argument `start` is non-negative, the offset is `start`: # # s = 'hello' # s[0, 1] = 'foo' # => "foo" @@ -1989,23 +1989,30 @@ class String # # Returns a string containing the characters in `self`, each with possibly # changed case: # - # * The first character is upcased. - # * All other characters are downcased. + # * The first character made uppercase. + # * All other characters are made lowercase. # # Examples: # - # 'hello world'.capitalize # => "Hello world" - # 'HELLO WORLD'.capitalize # => "Hello world" + # 'hello'.capitalize # => "Hello" + # 'HELLO'.capitalize # => "Hello" + # 'straße'.capitalize # => "Straße" # Lowercase 'ß' not changed. + # 'STRAẞE'.capitalize # => "Straße" # Uppercase 'ẞ' downcased to 'ß'. + # 'привет'.capitalize # => "Привет" + # 'ПРИВЕТ'.capitalize # => "Привет" # - # Some characters do not have upcase and downcase, and so are not changed; see - # [Case Mapping](rdoc-ref:case_mapping.rdoc): + # Some characters (and some character sets) do not have upcase and downcase + # versions; see [Case Mapping](rdoc-ref:case_mapping.rdoc): # - # '1, 2, 3, ...'.capitalize # => "1, 2, 3, ..." + # s = '1, 2, 3, ...' + # s.capitalize == s # => true + # s = 'こんにちは' + # s.capitalize == s # => true # # The casing is affected by the given `mapping`, which may be `:ascii`, `:fold`, # or `:turkic`; see [Case Mappings](rdoc-ref:case_mapping.rdoc@Case+Mappings). @@ -2632,18 +2639,25 @@ class String # # Returns a new string containing the downcased characters in `self`: # - # 'Hello, World!'.downcase # => "hello, world!" - # 'ТЕСТ'.downcase # => "тест" - # 'よろしくお願いします'.downcase # => "よろしくお願いします" + # 'HELLO'.downcase # => "hello" + # 'STRAẞE'.downcase # => "straße" + # 'ПРИВЕТ'.downcase # => "привет" + # 'RubyGems.org'.downcase # => "rubygems.org" + # + # Some characters (and some character sets) do not have upcase and downcase + # versions; see [Case Mapping](rdoc-ref:case_mapping.rdoc): # - # Some characters do not have upcased and downcased versions. + # s = '1, 2, 3, ...' + # s.downcase == s # => true + # s = 'こんにちは' + # s.downcase == s # => true # - # The casing may be affected by the given `mapping`; see [Case - # Mapping](rdoc-ref:case_mapping.rdoc). + # The casing is affected by the given `mapping`, which may be `:ascii`, `:fold`, + # or `:turkic`; see [Case Mappings](rdoc-ref:case_mapping.rdoc@Case+Mappings). # # Related: see [Converting to New # String](rdoc-ref:String@Converting+to+New+String). @@ -2673,60 +2687,104 @@ class String # rdoc-file=string.c # - dump -> new_string # --> - # Returns a printable version of `self`, enclosed in double-quotes: + # For an ordinary string, this method, +String#dump+, returns a printable + # ASCII-only version of `self`, enclosed in double-quotes. + # + # For a dumped string, method String#undump is the inverse of +String#dump+; it + # returns a "restored" version of `self`, where all the dumping changes have + # been undone. + # + # In the simplest case, the dumped string contains the original string, enclosed + # in double-quotes; this example is done in `irb` (interactive Ruby), which uses + # method `inspect` to render the results: + # + # s = 'hello' # => "hello" + # s.dump # => "\"hello\"" + # s.dump.undump # => "hello" + # + # Keep in mind that in the second line above: + # + # * The outer double-quotes are put on by `inspect`, and *are* *not* part of + # the output of #dump. + # * The inner double-quotes *are* part of the output of `dump`, and are + # escaped by `inspect` because they are within the outer double-quotes. + # + # To avoid confusion, we'll use this helper method to omit the outer + # double-quotes: + # + # def dump(s) + # print "String: ", s, "\n" + # print "Dumped: ", s.dump, "\n" + # print "Undumped: ", s.dump.undump, "\n" + # end # - # 'hello'.dump # => "\"hello\"" + # So that for string `'hello'`, we'll see: # - # Certain special characters are rendered with escapes: + # String: hello + # Dumped: "hello" + # Undumped: hello # - # '"'.dump # => "\"\\\"\"" - # '\\'.dump # => "\"\\\\\"" + # In a dump, certain special characters are escaped: # - # Non-printing characters are rendered with escapes: + # String: " + # Dumped: "\"" + # Undumped: " + # + # String: \ + # Dumped: "\\" + # Undumped: \ + # + # In a dump, unprintable characters are replaced by printable ones; the + # unprintable characters are the whitespace characters (other than space + # itself); here we see the ordinals for those characers, together with + # explanatory text: + # + # h = { + # 7 => 'Alert (BEL)', + # 8 => 'Backspace (BS)', + # 9 => 'Horizontal tab (HT)', + # 10 => 'Linefeed (LF)', + # 11 => 'Vertical tab (VT)', + # 12 => 'Formfeed (FF)', + # 13 => 'Carriage return (CR)' + # } + # + # In this example, the dumped output is printed by method #inspect, and so + # contains both outer double-quotes and escaped inner double-quotes: # # s = '' - # s << 7 # Alarm (bell). - # s << 8 # Back space. - # s << 9 # Horizontal tab. - # s << 10 # Line feed. - # s << 11 # Vertical tab. - # s << 12 # Form feed. - # s << 13 # Carriage return. - # s # => "\a\b\t\n\v\f\r" - # s.dump # => "\"\\a\\b\\t\\n\\v\\f\\r\"" - # - # If `self` is encoded in UTF-8 and contains Unicode characters, renders Unicode - # characters in Unicode escape sequence: - # - # 'тест'.dump # => "\"\\u0442\\u0435\\u0441\\u0442\"" - # 'こんにちは'.dump # => "\"\\u3053\\u3093\\u306B\\u3061\\u306F\"" - # - # If the encoding of `self` is not ASCII-compatible (i.e., - # `self.encoding.ascii_compatible?` returns `false`), renders all - # ASCII-compatible bytes as ASCII characters and all other bytes as hexadecimal. - # Appends `.dup.force_encoding(\"encoding\")`, where `` is - # `self.encoding.name`: + # h.keys.each {|i| s << i } # => [7, 8, 9, 10, 11, 12, 13] + # s # => "\a\b\t\n\v\f\r" + # s.dump # => "\"\\a\\b\\t\\n\\v\\f\\r\"" # - # s = 'hello' - # s.encoding # => # - # s.dump # => "\"hello\"" - # s.encode('utf-16').dump # => "\"\\xFE\\xFF\\x00h\\x00e\\x00l\\x00l\\x00o\".dup.force_encoding(\"UTF-16\")" - # s.encode('utf-16le').dump # => "\"h\\x00e\\x00l\\x00l\\x00o\\x00\".dup.force_encoding(\"UTF-16LE\")" + # If `self` is encoded in UTF-8 and contains Unicode characters, each Unicode + # character is dumped as a Unicode escape sequence: # - # s = 'тест' - # s.encoding # => # - # s.dump # => "\"\\u0442\\u0435\\u0441\\u0442\"" - # s.encode('utf-16').dump # => "\"\\xFE\\xFF\\x04B\\x045\\x04A\\x04B\".dup.force_encoding(\"UTF-16\")" - # s.encode('utf-16le').dump # => "\"B\\x045\\x04A\\x04B\\x04\".dup.force_encoding(\"UTF-16LE\")" + # String: тест + # Dumped: "\u0442\u0435\u0441\u0442" + # Undumped: тест # - # s = 'こんにちは' - # s.encoding # => # - # s.dump # => "\"\\u3053\\u3093\\u306B\\u3061\\u306F\"" - # s.encode('utf-16').dump # => "\"\\xFE\\xFF0S0\\x930k0a0o\".dup.force_encoding(\"UTF-16\")" - # s.encode('utf-16le').dump # => "\"S0\\x930k0a0o0\".dup.force_encoding(\"UTF-16LE\")" + # String: こんにちは + # Dumped: "\u3053\u3093\u306B\u3061\u306F" + # Undumped: こんにちは # - # Related: see [Converting to New - # String](rdoc-ref:String@Converting+to+New+String). + # If the encoding of `self` is not ASCII-compatible (i.e., if + # `self.encoding.ascii_compatible?` returns `false`), each ASCII-compatible byte + # is dumped as an ASCII character, and all other bytes are dumped as + # hexadecimal; also appends `.dup.force_encoding(\"encoding\")`, where + # `` is `self.encoding.name`: + # + # String: hello + # Dumped: "\xFE\xFF\x00h\x00e\x00l\x00l\x00o".dup.force_encoding("UTF-16") + # Undumped: hello + # + # String: тест + # Dumped: "\xFE\xFF\x04B\x045\x04A\x04B".dup.force_encoding("UTF-16") + # Undumped: тест + # + # String: こんにちは + # Dumped: "\xFE\xFF0S0\x930k0a0o".dup.force_encoding("UTF-16") + # Undumped: こんにちは # def dump: () -> String @@ -3580,7 +3638,7 @@ class String # # Returns a copy of `self` with leading whitespace removed; see [Whitespace in # Strings](rdoc-ref:String@Whitespace+in+Strings): @@ -3591,6 +3649,19 @@ class String # s.lstrip # # => "abc\u0000\t\n\v\f\r " # + # If `selectors` are given, removes characters of `selectors` from the beginning + # of `self`: + # + # s = "---abc+++" + # s.lstrip("-") # => "abc+++" + # + # `selectors` must be valid character selectors (see [Character + # Selectors](rdoc-ref:character_selectors.rdoc)), and may use any of its valid + # forms, including negation, ranges, and escapes: + # + # "01234abc56789".lstrip("0-9") # "abc56789" + # "01234abc56789".lstrip("0-9", "^4-6") # "4abc56789" + # # Related: see [Converting to New # String](rdoc-ref:String@Converting+to+New+String). # @@ -3598,7 +3669,7 @@ class String # # Like String#lstrip, except that: # @@ -3858,7 +3929,7 @@ class String # # If `pattern` is a Regexp, performs the equivalent of `self.match(pattern)` # (also setting [pattern-matching global - # variables](rdoc-ref:globals.md@Pattern+Matching)): + # variables](rdoc-ref:language/globals.md@Pattern+Matching)): # # 'hello'.partition(/h/) # => ["", "h", "ello"] # 'hello'.partition(/l/) # => ["he", "l", "lo"] @@ -3872,7 +3943,7 @@ class String # If `pattern` is not a Regexp, converts it to a string (if it is not already # one), then performs the equivalent of `self.index(pattern)` (and does *not* # set [pattern-matching global - # variables](rdoc-ref:globals.md@Pattern+Matching)): + # variables](rdoc-ref:language/globals.md@Pattern+Matching)): # # 'hello'.partition('h') # => ["", "h", "ello"] # 'hello'.partition('l') # => ["he", "l", "lo"] @@ -4063,7 +4134,7 @@ class String # # If `pattern` is a Regexp, searches for the last matching substring (also # setting [pattern-matching global - # variables](rdoc-ref:globals.md@Pattern+Matching)): + # variables](rdoc-ref:language/globals.md@Pattern+Matching)): # # 'hello'.rpartition(/l/) # => ["hel", "l", "o"] # 'hello'.rpartition(/ll/) # => ["he", "ll", "o"] @@ -4076,7 +4147,8 @@ class String # # If `pattern` is not a Regexp, converts it to a string (if it is not already # one), then searches for the last matching substring (and does *not* set - # [pattern-matching global variables](rdoc-ref:globals.md@Pattern+Matching)): + # [pattern-matching global + # variables](rdoc-ref:language/globals.md@Pattern+Matching)): # # 'hello'.rpartition('l') # => ["hel", "l", "o"] # 'hello'.rpartition('ll') # => ["he", "ll", "o"] @@ -4093,7 +4165,7 @@ class String # # Returns a copy of `self` with trailing whitespace removed; see [Whitespace in # Strings](rdoc-ref:String@Whitespace+in+Strings): @@ -4103,6 +4175,19 @@ class String # s # => "\u0000\t\n\v\f\r abc\u0000\t\n\v\f\r " # s.rstrip # => "\u0000\t\n\v\f\r abc" # + # If `selectors` are given, removes characters of `selectors` from the end of + # `self`: + # + # s = "---abc+++" + # s.rstrip("+") # => "---abc" + # + # `selectors` must be valid character selectors (see [Character + # Selectors](rdoc-ref:character_selectors.rdoc)), and may use any of its valid + # forms, including negation, ranges, and escapes: + # + # "01234abc56789".rstrip("0-9") # "01234abc" + # "01234abc56789".rstrip("0-9", "^4-6") # "01234abc56" + # # Related: see [Converting to New # String](rdoc-ref:String@Converting+to+New+String). # @@ -4110,7 +4195,7 @@ class String # # Like String#rstrip, except that: # @@ -4259,7 +4344,7 @@ class String # 'hello'[0] # => "h" # 'hello'[4] # => "o" # 'hello'[5] # => nil - # 'тест'[2] # => "с" + # 'Привет'[2] # => "и" # 'こんにちは'[4] # => "は" # # With negative integer argument `index` given, counts backward from the end of @@ -4340,7 +4425,7 @@ class String # 'hello'['ell'] # => "ell" # 'hello'[''] # => "" # 'hello'['nosuch'] # => nil - # 'тест'['ес'] # => "ес" + # 'Привет'['ив'] # => "ив" # 'こんにちは'['んにち'] # => "んにち" # # Related: see [Converting to New @@ -4565,7 +4650,7 @@ class String # # Returns a copy of `self` with leading and trailing whitespace removed; see # [Whitespace in Strings](rdoc-ref:String@Whitespace+in+Strings): @@ -4575,6 +4660,20 @@ class String # # => "\u0000\t\n\v\f\r abc\u0000\t\n\v\f\r " # s.strip # => "abc" # + # If `selectors` are given, removes characters of `selectors` from both ends of + # `self`: + # + # s = "---abc+++" + # s.strip("-+") # => "abc" + # s.strip("+-") # => "abc" + # + # `selectors` must be valid character selectors (see [Character + # Selectors](rdoc-ref:character_selectors.rdoc)), and may use any of its valid + # forms, including negation, ranges, and escapes: + # + # "01234abc56789".strip("0-9") # "abc" + # "01234abc56789".strip("0-9", "^4-6") # "4abc56" + # # Related: see [Converting to New # String](rdoc-ref:String@Converting+to+New+String). # @@ -4582,7 +4681,7 @@ class String # # Like String#strip, except that: # @@ -4743,7 +4842,7 @@ class String # # Returns a string containing the characters in `self`, with cases reversed: # @@ -4752,16 +4851,28 @@ class String # # Examples: # - # 'Hello World!'.swapcase # => "hELLO wORLD!" - # 'тест'.swapcase # => "ТЕСТ" + # 'Hello'.swapcase # => "hELLO" + # 'Straße'.swapcase # => "sTRASSE" + # 'Привет'.swapcase # => "пРИВЕТ" + # 'RubyGems.org'.swapcase # => "rUBYgEMS.ORG" + # + # The sizes of `self` and the upcased result may differ: # - # Some characters (and even character sets) do not have casing: + # s = 'Straße' + # s.size # => 6 + # s.swapcase # => "sTRASSE" + # s.swapcase.size # => 7 # - # '12345'.swapcase # => "12345" - # 'こんにちは'.swapcase # => "こんにちは" + # Some characters (and some character sets) do not have upcase and downcase + # versions; see [Case Mapping](rdoc-ref:case_mapping.rdoc): # - # The casing may be affected by the given `mapping`; see [Case - # Mapping](rdoc-ref:case_mapping.rdoc). + # s = '1, 2, 3, ...' + # s.swapcase == s # => true + # s = 'こんにちは' + # s.swapcase == s # => true + # + # The casing is affected by the given `mapping`, which may be `:ascii`, `:fold`, + # or `:turkic`; see [Case Mappings](rdoc-ref:case_mapping.rdoc@Case+Mappings). # # Related: see [Converting to New # String](rdoc-ref:String@Converting+to+New+String). @@ -5150,16 +5261,13 @@ class String # - # Returns an unescaped version of `self`: - # - # s_orig = "\f\x00\xff\\\"" # => "\f\u0000\xFF\\\"" - # s_dumped = s_orig.dump # => "\"\\f\\x00\\xFF\\\\\\\"\"" - # s_undumped = s_dumped.undump # => "\f\u0000\xFF\\\"" - # s_undumped == s_orig # => true + # Inverse of String#dump; returns a copy of `self` with changes of the kinds + # made by String#dump "undone." # - # Related: String#dump (inverse of String#undump). + # Related: see [Converting to New + # String](rdoc-ref:String@Converting+to+New+String). # def undump: () -> String @@ -5180,21 +5288,22 @@ class String # # The encoding of `self` must be one of: # - # * Encoding::UTF_8 - # * Encoding::UTF_16BE - # * Encoding::UTF_16LE - # * Encoding::UTF_32BE - # * Encoding::UTF_32LE - # * Encoding::GB18030 - # * Encoding::UCS_2BE - # * Encoding::UCS_4BE + # * `Encoding::UTF_8`. + # * `Encoding::UTF_16BE`. + # * `Encoding::UTF_16LE`. + # * `Encoding::UTF_32BE`. + # * `Encoding::UTF_32LE`. + # * `Encoding::GB18030`. + # * `Encoding::UCS_2BE`. + # * `Encoding::UCS_4BE`. # # Examples: # - # "a\u0300".unicode_normalize # => "a" - # "\u00E0".unicode_normalize(:nfd) # => "a " + # "a\u0300".unicode_normalize # => "à" # Lowercase 'a' with grave accens. + # "a\u0300".unicode_normalize(:nfd) # => "à" # Same. # - # Related: String#unicode_normalize!, String#unicode_normalized?. + # Related: see [Converting to New + # String](rdoc-ref:String@Converting+to+New+String). # def unicode_normalize: (?:nfc | :nfd | :nfkc | :nfkd form) -> self @@ -5240,7 +5349,7 @@ class String # - unpack(template, offset: 0) -> array # --> # Extracts data from `self` to form new objects; see [Packed - # Data](rdoc-ref:packed_data.rdoc). + # Data](rdoc-ref:language/packed_data.rdoc). # # With a block given, calls the block with each unpacked object. # @@ -5257,7 +5366,7 @@ class String # - unpack1(template, offset: 0) -> object # --> # Like String#unpack with no block, but unpacks and returns only the first - # extracted object. See [Packed Data](rdoc-ref:packed_data.rdoc). + # extracted object. See [Packed Data](rdoc-ref:language/packed_data.rdoc). # # Related: see [Converting to # Non-String](rdoc-ref:String@Converting+to+Non--5CString). @@ -5266,17 +5375,35 @@ class String # - # Returns a string containing the upcased characters in `self`: + # Returns a new string containing the upcased characters in `self`: # - # s = 'Hello World!' # => "Hello World!" - # s.upcase # => "HELLO WORLD!" + # 'hello'.upcase # => "HELLO" + # 'straße'.upcase # => "STRASSE" + # 'привет'.upcase # => "ПРИВЕТ" + # 'RubyGems.org'.upcase # => "RUBYGEMS.ORG" + # + # The sizes of `self` and the upcased result may differ: + # + # s = 'Straße' + # s.size # => 6 + # s.upcase # => "STRASSE" + # s.upcase.size # => 7 + # + # Some characters (and some character sets) do not have upcase and downcase + # versions; see [Case Mapping](rdoc-ref:case_mapping.rdoc): + # + # s = '1, 2, 3, ...' + # s.upcase == s # => true + # s = 'こんにちは' + # s.upcase == s # => true # - # The casing may be affected by the given `mapping`; see [Case - # Mapping](rdoc-ref:case_mapping.rdoc). + # The casing is affected by the given `mapping`, which may be `:ascii`, `:fold`, + # or `:turkic`; see [Case Mappings](rdoc-ref:case_mapping.rdoc@Case+Mappings). # - # Related: String#upcase!, String#downcase, String#downcase!. + # Related: see [Converting to New + # String](rdoc-ref:String@Converting+to+New+String). # def upcase: () -> String | (:ascii | :lithuanian | :turkic) -> String @@ -5287,18 +5414,12 @@ class String # rdoc-file=string.c # - upcase!(mapping) -> self or nil # --> - # Upcases the characters in `self`; returns `self` if any changes were made, - # `nil` otherwise: - # - # s = 'Hello World!' # => "Hello World!" - # s.upcase! # => "HELLO WORLD!" - # s # => "HELLO WORLD!" - # s.upcase! # => nil + # Like String#upcase, except that: # - # The casing may be affected by the given `mapping`; see [Case - # Mapping](rdoc-ref:case_mapping.rdoc). + # * Changes character casings in `self` (not in a copy of `self`). + # * Returns `self` if any changes are made, `nil` otherwise. # - # Related: String#upcase, String#downcase, String#downcase!. + # Related: See [Modifying](rdoc-ref:String@Modifying). # def upcase!: () -> self? | (:ascii | :lithuanian | :turkic) -> self? @@ -5315,20 +5436,28 @@ class String # `self.succ`, and so on; the sequence terminates when value `other_string` is # reached; returns `self`: # - # 'a8'.upto('b6') {|s| print s, ' ' } # => "a8" + # a = [] + # 'a'.upto('f') {|c| a.push(c) } + # a # => ["a", "b", "c", "d", "e", "f"] # - # Output: + # a = [] + # 'Ж'.upto('П') {|c| a.push(c) } + # a # => ["Ж", "З", "И", "Й", "К", "Л", "М", "Н", "О", "П"] # - # a8 a9 b0 b1 b2 b3 b4 b5 b6 + # a = [] + # 'よ'.upto('ろ') {|c| a.push(c) } + # a # => ["よ", "ら", "り", "る", "れ", "ろ"] + # + # a = [] + # 'a8'.upto('b6') {|c| a.push(c) } + # a # => ["a8", "a9", "b0", "b1", "b2", "b3", "b4", "b5", "b6"] # # If argument `exclusive` is given as a truthy object, the last value is # omitted: # - # 'a8'.upto('b6', true) {|s| print s, ' ' } # => "a8" - # - # Output: - # - # a8 a9 b0 b1 b2 b3 b4 b5 + # a = [] + # 'a'.upto('f', true) {|c| a.push(c) } + # a # => ["a", "b", "c", "d", "e"] # # If `other_string` would not be reached, does not call the block: # @@ -5339,6 +5468,8 @@ class String # # 'a8'.upto('b6') # => # # + # Related: see [Iterating](rdoc-ref:String@Iterating). + # def upto: (string other_string, ?boolish exclusive) -> Enumerator[String, self] | (string other_string, ?boolish exclusive) { (String s) -> void } -> self @@ -5346,11 +5477,14 @@ class String # rdoc-file=string.c # - valid_encoding? -> true or false # --> - # Returns `true` if `self` is encoded correctly, `false` otherwise: + # Returns whether `self` is encoded correctly: # - # "\xc2\xa1".force_encoding(Encoding::UTF_8).valid_encoding? # => true - # "\xc2".force_encoding(Encoding::UTF_8).valid_encoding? # => false - # "\x80".force_encoding(Encoding::UTF_8).valid_encoding? # => false + # s = 'Straße' + # s.valid_encoding? # => true + # s.encoding # => # + # s.force_encoding(Encoding::ASCII).valid_encoding? # => false + # + # Related: see [Querying](rdoc-ref:String@Querying). # def valid_encoding?: () -> bool end diff --git a/core/thread.rbs b/core/thread.rbs index bb63ae41d..641f85e7b 100644 --- a/core/thread.rbs +++ b/core/thread.rbs @@ -1516,7 +1516,7 @@ end # class Thread::Mutex < Object # # Attempts to grab the lock and waits if it isn't available. Raises @@ -1525,7 +1525,7 @@ class Thread::Mutex < Object def lock: () -> self # # Returns `true` if this lock is currently held by some thread. @@ -1533,7 +1533,7 @@ class Thread::Mutex < Object def locked?: () -> bool # # Returns `true` if this lock is currently held by current thread. @@ -1541,7 +1541,7 @@ class Thread::Mutex < Object def owned?: () -> bool # # Obtains a lock, runs the block, and releases the lock when the block @@ -1550,7 +1550,7 @@ class Thread::Mutex < Object def synchronize: [X] () { () -> X } -> X # # Attempts to obtain the lock and returns immediately. Returns `true` if the @@ -1559,11 +1559,11 @@ class Thread::Mutex < Object def try_lock: () -> bool # - # Releases the lock. Raises `ThreadError` if `mutex` wasn't locked by the - # current thread. + # Attempts to grab the lock and waits if it isn't available. Raises + # `ThreadError` if `mutex` was locked by the current thread. # def unlock: () -> self end diff --git a/core/trace_point.rbs b/core/trace_point.rbs index 473200105..a4eea5f4e 100644 --- a/core/trace_point.rbs +++ b/core/trace_point.rbs @@ -25,7 +25,8 @@ # change. Instead, it is recommended to specify the types of events you want to # use. # -# To filter what is traced, you can pass any of the following as `events`: +# To filter what is traced, you can pass any number of the following as +# `events`: # # `:line` # : Execute an expression or statement on a new line. @@ -107,8 +108,8 @@ class TracePoint # # A block must be given; otherwise, an ArgumentError is raised. # - # If the trace method isn't included in the given events filter, a RuntimeError - # is raised. + # If the trace method isn't supported for the given event(s) filter, a + # RuntimeError is raised. # # TracePoint.trace(:line) do |tp| # p tp.raised_exception @@ -122,7 +123,9 @@ class TracePoint # end # $tp.lineno #=> access from outside (RuntimeError) # - # Access from other threads is also forbidden. + # Access from other ractors, threads or fibers is forbidden. TracePoints are + # active per-ractor so if you enable a TracePoint in one ractor, other ractors + # will not be affected. # def self.new: (*_ToSym events) { (instance tp) -> void } -> instance diff --git a/stdlib/bigdecimal/0/big_decimal.rbs b/stdlib/bigdecimal/0/big_decimal.rbs index 8792f0c68..5553734f6 100644 --- a/stdlib/bigdecimal/0/big_decimal.rbs +++ b/stdlib/bigdecimal/0/big_decimal.rbs @@ -1260,33 +1260,35 @@ class Integer # - # Performs division; for integer `numeric`, truncates the result to an integer: + # Returns the quotient of `self` and `other`. + # + # For integer `other`, truncates the result to an integer: # - # 4 / 3 # => 1 - # 4 / -3 # => -2 - # -4 / 3 # => -2 - # -4 / -3 # => 1 + # 4 / 3 # => 1 + # 4 / -3 # => -2 + # -4 / 3 # => -2 + # -4 / -3 # => 1 # - # For other +numeric+, returns non-integer result: + # For non-integer `other`, returns a non-integer result: # - # 4 / 3.0 # => 1.3333333333333333 - # 4 / Rational(3, 1) # => (4/3) - # 4 / Complex(3, 0) # => ((4/3)+0i) + # 4 / 3.0 # => 1.3333333333333333 + # 4 / Rational(3, 1) # => (4/3) + # 4 / Complex(3, 0) # => ((4/3)+0i) # def /: (BigDecimal) -> BigDecimal | ... # - # Performs multiplication: + # Returns the numeric product of `self` and `other`: # # 4 * 2 # => 8 - # 4 * -2 # => -8 # -4 * 2 # => -8 + # 4 * -2 # => -8 # 4 * 2.0 # => 8.0 # 4 * Rational(1, 3) # => (4/3) # 4 * Complex(2, 0) # => (8+0i) @@ -1296,25 +1298,29 @@ class Integer # - # Performs addition: + # Returns the sum of `self` and `other`: + # + # 1 + 1 # => 2 + # 1 + -1 # => 0 + # 1 + 0 # => 1 + # 1 + -2 # => -1 + # 1 + Complex(1, 0) # => (2+0i) + # 1 + Rational(1, 1) # => (2/1) + # + # For a computation involving Floats, the result may be inexact (see Float#+): # - # 2 + 2 # => 4 - # -2 + 2 # => 0 - # -2 + -2 # => -4 - # 2 + 2.0 # => 4.0 - # 2 + Rational(2, 1) # => (4/1) - # 2 + Complex(2, 0) # => (4+0i) + # 1 + 3.14 # => 4.140000000000001 # def +: (BigDecimal) -> BigDecimal | ... # - # Performs subtraction: + # Returns the difference of `self` and `other`: # # 4 - 2 # => 2 # -4 - 2 # => -6 @@ -1354,7 +1360,7 @@ class Float # rdoc-file=numeric.c # - self / other -> numeric # --> - # Returns a new Float which is the result of dividing `self` by `other`: + # Returns the quotient of `self` and `other`: # # f = 3.14 # f / 2 # => 1.57 @@ -1369,7 +1375,7 @@ class Float # rdoc-file=numeric.c # - self * other -> numeric # --> - # Returns a new Float which is the product of `self` and `other`: + # Returns the numeric product of `self` and `other`: # # f = 3.14 # f * 2 # => 6.28 @@ -1382,15 +1388,20 @@ class Float # - # Returns a new Float which is the sum of `self` and `other`: + # Returns the sum of `self` and `other`; the result may be inexact (see Float): # - # f = 3.14 - # f + 1 # => 4.140000000000001 - # f + 1.0 # => 4.140000000000001 - # f + Rational(1, 1) # => 4.140000000000001 - # f + Complex(1, 0) # => (4.140000000000001+0i) + # 3.14 + 0 # => 3.14 + # 3.14 + 1 # => 4.140000000000001 + # -3.14 + 0 # => -3.14 + # -3.14 + 1 # => -2.14 + # + # 3.14 + -3.14 # => 0.0 + # -3.14 + -3.14 # => -6.28 + # + # 3.14 + Complex(1, 0) # => (4.140000000000001+0i) + # 3.14 + Rational(1, 1) # => 4.140000000000001 # def +: (BigDecimal) -> BigDecimal | ... @@ -1399,7 +1410,7 @@ class Float # rdoc-file=numeric.c # - self - other -> numeric # --> - # Returns a new Float which is the difference of `self` and `other`: + # Returns the difference of `self` and `other`: # # f = 3.14 # f - 1 # => 2.14 @@ -1454,10 +1465,9 @@ class Rational # - # Performs division. + # Returns the quotient of `self` and `other`: # # Rational(2, 3) / Rational(2, 3) #=> (1/1) # Rational(900) / Rational(1) #=> (900/1) @@ -1470,39 +1480,50 @@ class Rational # - # Performs multiplication. + # Returns the numeric product of `self` and `other`: # - # Rational(2, 3) * Rational(2, 3) #=> (4/9) - # Rational(900) * Rational(1) #=> (900/1) - # Rational(-2, 9) * Rational(-9, 2) #=> (1/1) - # Rational(9, 8) * 4 #=> (9/2) - # Rational(20, 9) * 9.8 #=> 21.77777777777778 + # Rational(9, 8) * 4 #=> (9/2) + # Rational(20, 9) * 9.8 #=> 21.77777777777778 + # Rational(9, 8) * Complex(1, 2) # => ((9/8)+(9/4)*i) + # Rational(2, 3) * Rational(2, 3) #=> (4/9) + # Rational(900) * Rational(1) #=> (900/1) + # Rational(-2, 9) * Rational(-9, 2) #=> (1/1) # def *: (BigDecimal) -> BigDecimal | ... # - # Performs addition. + # Returns the sum of `self` and `other`: # - # Rational(2, 3) + Rational(2, 3) #=> (4/3) - # Rational(900) + Rational(1) #=> (901/1) - # Rational(-2, 9) + Rational(-9, 2) #=> (-85/18) - # Rational(9, 8) + 4 #=> (41/8) - # Rational(20, 9) + 9.8 #=> 12.022222222222222 + # Rational(2, 3) + 0 # => (2/3) + # Rational(2, 3) + 1 # => (5/3) + # Rational(2, 3) + -1 # => (-1/3) + # + # Rational(2, 3) + Complex(1, 0) # => ((5/3)+0i) + # + # Rational(2, 3) + Rational(1, 1) # => (5/3) + # Rational(2, 3) + Rational(3, 2) # => (13/6) + # Rational(2, 3) + Rational(3.0, 2.0) # => (13/6) + # Rational(2, 3) + Rational(3.1, 2.1) # => (30399297484750849/14186338826217063) + # + # For a computation involving Floats, the result may be inexact (see Float#+): + # + # Rational(2, 3) + 1.0 # => 1.6666666666666665 + # Rational(2, 3) + Complex(1.0, 0.0) # => (1.6666666666666665+0.0i) # def +: (BigDecimal) -> BigDecimal | ... # - # Performs subtraction. + # Returns the difference of `self` and `other`: # # Rational(2, 3) - Rational(2, 3) #=> (0/1) # Rational(900) - Rational(1) #=> (899/1) @@ -1539,9 +1560,9 @@ class Complex # - # Returns the quotient of `self` and `numeric`: + # Returns the quotient of `self` and `other`: # # Complex.rect(2, 3) / Complex.rect(2, 3) # => (1+0i) # Complex.rect(900) / Complex.rect(1) # => (900+0i) @@ -1554,39 +1575,50 @@ class Complex # - # Returns the product of `self` and `numeric`: + # Returns the numeric product of `self` and `other`: # + # Complex.rect(9, 8) * 4 # => (36+32i) + # Complex.rect(20, 9) * 9.8 # => (196.0+88.2i) # Complex.rect(2, 3) * Complex.rect(2, 3) # => (-5+12i) # Complex.rect(900) * Complex.rect(1) # => (900+0i) # Complex.rect(-2, 9) * Complex.rect(-9, 2) # => (0-85i) - # Complex.rect(9, 8) * 4 # => (36+32i) - # Complex.rect(20, 9) * 9.8 # => (196.0+88.2i) + # Complex.rect(9, 8) * Rational(2, 3) # => ((6/1)+(16/3)*i) # def *: (BigDecimal) -> Complex | ... # - # Returns the sum of `self` and `numeric`: + # Returns the sum of `self` and `other`: + # + # Complex(1, 2) + 0 # => (1+2i) + # Complex(1, 2) + 1 # => (2+2i) + # Complex(1, 2) + -1 # => (0+2i) + # + # Complex(1, 2) + 1.0 # => (2.0+2i) + # + # Complex(1, 2) + Complex(2, 1) # => (3+3i) + # Complex(1, 2) + Complex(2.0, 1.0) # => (3.0+3.0i) + # + # Complex(1, 2) + Rational(1, 1) # => ((2/1)+2i) + # Complex(1, 2) + Rational(1, 2) # => ((3/2)+2i) + # + # For a computation involving Floats, the result may be inexact (see Float#+): # - # Complex.rect(2, 3) + Complex.rect(2, 3) # => (4+6i) - # Complex.rect(900) + Complex.rect(1) # => (901+0i) - # Complex.rect(-2, 9) + Complex.rect(-9, 2) # => (-11+11i) - # Complex.rect(9, 8) + 4 # => (13+8i) - # Complex.rect(20, 9) + 9.8 # => (29.8+9i) + # Complex(1, 2) + 3.14 # => (4.140000000000001+2i) # def +: (BigDecimal) -> Complex | ... # - # Returns the difference of `self` and `numeric`: + # Returns the difference of `self` and `other`: # # Complex.rect(2, 3) - Complex.rect(2, 3) # => (0+0i) # Complex.rect(900) - Complex.rect(1) # => (899+0i) diff --git a/stdlib/date/0/date.rbs b/stdlib/date/0/date.rbs index 8c50184bf..ee9c2340b 100644 --- a/stdlib/date/0/date.rbs +++ b/stdlib/date/0/date.rbs @@ -5,7 +5,7 @@ # # * You need both dates and times; Date handles only dates. # * You need only Gregorian dates (and not Julian dates); see [Julian and -# Gregorian Calendars](rdoc-ref:date/calendars.rdoc). +# Gregorian Calendars](rdoc-ref:language/calendars.rdoc). # # A Date object, once created, is immutable, and cannot be modified. # @@ -53,7 +53,7 @@ # # See also the specialized methods in ["Specialized Format Strings" in Formats # for Dates and -# Times](rdoc-ref:strftime_formatting.rdoc@Specialized+Format+Strings) +# Times](rdoc-ref:language/strftime_formatting.rdoc@Specialized+Format+Strings) # # ## Argument `limit` # @@ -88,7 +88,7 @@ class Date # number of days in the month; when the argument is negative, counts backward # from the end of the month. # - # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). + # See argument [start](rdoc-ref:language/calendars.rdoc@Argument+start). # # Related: Date.jd. # @@ -101,7 +101,7 @@ class Date # - Date._httpdate(string, limit: 128) -> hash # --> # Returns a hash of values parsed from `string`, which should be a valid [HTTP - # date format](rdoc-ref:strftime_formatting.rdoc@HTTP+Format): + # date format](rdoc-ref:language/strftime_formatting.rdoc@HTTP+Format): # # d = Date.new(2001, 2, 3) # s = d.httpdate # => "Sat, 03 Feb 2001 00:00:00 GMT" @@ -118,7 +118,8 @@ class Date # --> # Returns a hash of values parsed from `string`, which should contain an [ISO # 8601 formatted - # date](rdoc-ref:strftime_formatting.rdoc@ISO+8601+Format+Specifications): + # date](rdoc-ref:language/strftime_formatting.rdoc@ISO+8601+Format+Specification + # s): # # d = Date.new(2001, 2, 3) # s = d.iso8601 # => "2001-02-03" @@ -135,7 +136,8 @@ class Date # - Date._jisx0301(string, limit: 128) -> hash # --> # Returns a hash of values parsed from `string`, which should be a valid [JIS X - # 0301 date format](rdoc-ref:strftime_formatting.rdoc@JIS+X+0301+Format): + # 0301 date + # format](rdoc-ref:language/strftime_formatting.rdoc@JIS+X+0301+Format): # # d = Date.new(2001, 2, 3) # s = d.jisx0301 # => "H13.02.03" @@ -153,7 +155,8 @@ class Date # --> # **Note**: This method recognizes many forms in `string`, but it is not a # validator. For formats, see ["Specialized Format Strings" in Formats for Dates - # and Times](rdoc-ref:strftime_formatting.rdoc@Specialized+Format+Strings) + # and + # Times](rdoc-ref:language/strftime_formatting.rdoc@Specialized+Format+Strings) # # If `string` does not specify a valid date, the result is unpredictable; # consider using Date._strptime instead. @@ -179,7 +182,7 @@ class Date # - Date._rfc2822(string, limit: 128) -> hash # --> # Returns a hash of values parsed from `string`, which should be a valid [RFC - # 2822 date format](rdoc-ref:strftime_formatting.rdoc@RFC+2822+Format): + # 2822 date format](rdoc-ref:language/strftime_formatting.rdoc@RFC+2822+Format): # # d = Date.new(2001, 2, 3) # s = d.rfc2822 # => "Sat, 3 Feb 2001 00:00:00 +0000" @@ -197,7 +200,7 @@ class Date # - Date._rfc3339(string, limit: 128) -> hash # --> # Returns a hash of values parsed from `string`, which should be a valid [RFC - # 3339 format](rdoc-ref:strftime_formatting.rdoc@RFC+3339+Format): + # 3339 format](rdoc-ref:language/strftime_formatting.rdoc@RFC+3339+Format): # # d = Date.new(2001, 2, 3) # s = d.rfc3339 # => "2001-02-03T00:00:00+00:00" @@ -215,7 +218,7 @@ class Date # - Date._rfc2822(string, limit: 128) -> hash # --> # Returns a hash of values parsed from `string`, which should be a valid [RFC - # 2822 date format](rdoc-ref:strftime_formatting.rdoc@RFC+2822+Format): + # 2822 date format](rdoc-ref:language/strftime_formatting.rdoc@RFC+2822+Format): # # d = Date.new(2001, 2, 3) # s = d.rfc2822 # => "Sat, 3 Feb 2001 00:00:00 +0000" @@ -237,8 +240,8 @@ class Date # Date._strptime('2001-02-03', '%Y-%m-%d') # => {:year=>2001, :mon=>2, :mday=>3} # # For other formats, see [Formats for Dates and - # Times](rdoc-ref:strftime_formatting.rdoc). (Unlike Date.strftime, does not - # support flags and width.) + # Times](rdoc-ref:language/strftime_formatting.rdoc). (Unlike Date.strftime, + # does not support flags and width.) # # See also [strptime(3)](https://man7.org/linux/man-pages/man3/strptime.3.html). # @@ -309,7 +312,7 @@ class Date # Date.commercial(2020, 1, 1).to_s # => "2019-12-30" # Date.commercial(2020, 1, 7).to_s # => "2020-01-05" # - # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). + # See argument [start](rdoc-ref:language/calendars.rdoc@Argument+start). # # Related: Date.jd, Date.new, Date.ordinal. # @@ -335,7 +338,8 @@ class Date # - Date.httpdate(string = 'Mon, 01 Jan -4712 00:00:00 GMT', start = Date::ITALY, limit: 128) -> date # --> # Returns a new Date object with values parsed from `string`, which should be a - # valid [HTTP date format](rdoc-ref:strftime_formatting.rdoc@HTTP+Format): + # valid [HTTP date + # format](rdoc-ref:language/strftime_formatting.rdoc@HTTP+Format): # # d = Date.new(2001, 2, 3) # s = d.httpdate # => "Sat, 03 Feb 2001 00:00:00 GMT" @@ -343,7 +347,7 @@ class Date # # See: # - # * Argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). + # * Argument [start](rdoc-ref:language/calendars.rdoc@Argument+start). # * Argument [limit](rdoc-ref:Date@Argument+limit). # # Related: Date._httpdate (returns a hash). @@ -356,7 +360,8 @@ class Date # --> # Returns a new Date object with values parsed from `string`, which should # contain an [ISO 8601 formatted - # date](rdoc-ref:strftime_formatting.rdoc@ISO+8601+Format+Specifications): + # date](rdoc-ref:language/strftime_formatting.rdoc@ISO+8601+Format+Specification + # s): # # d = Date.new(2001, 2, 3) # s = d.iso8601 # => "2001-02-03" @@ -364,7 +369,7 @@ class Date # # See: # - # * Argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). + # * Argument [start](rdoc-ref:language/calendars.rdoc@Argument+start). # * Argument [limit](rdoc-ref:Date@Argument+limit). # # Related: Date._iso8601 (returns a hash). @@ -393,7 +398,7 @@ class Date # # Date.jd(Date::ITALY - 1).julian? # => true # - # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). + # See argument [start](rdoc-ref:language/calendars.rdoc@Argument+start). # # Related: Date.new. # @@ -405,7 +410,7 @@ class Date # --> # Returns a new Date object with values parsed from `string`, which should be a # valid [JIS X 0301 - # format](rdoc-ref:strftime_formatting.rdoc@JIS+X+0301+Format): + # format](rdoc-ref:language/strftime_formatting.rdoc@JIS+X+0301+Format): # # d = Date.new(2001, 2, 3) # s = d.jisx0301 # => "H13.02.03" @@ -417,7 +422,7 @@ class Date # # See: # - # * Argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). + # * Argument [start](rdoc-ref:language/calendars.rdoc@Argument+start). # * Argument [limit](rdoc-ref:Date@Argument+limit). # # Related: Date._jisx0301 (returns a hash). @@ -480,7 +485,7 @@ class Date # # Raises an exception if `yday` is zero or out of range. # - # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). + # See argument [start](rdoc-ref:language/calendars.rdoc@Argument+start). # # Related: Date.jd, Date.new. # @@ -492,9 +497,10 @@ class Date # --> # **Note**: This method recognizes many forms in `string`, but it is not a # validator. For formats, see ["Specialized Format Strings" in Formats for Dates - # and Times](rdoc-ref:strftime_formatting.rdoc@Specialized+Format+Strings) If - # `string` does not specify a valid date, the result is unpredictable; consider - # using Date._strptime instead. + # and + # Times](rdoc-ref:language/strftime_formatting.rdoc@Specialized+Format+Strings) + # If `string` does not specify a valid date, the result is unpredictable; + # consider using Date._strptime instead. # # Returns a new Date object with values parsed from `string`: # @@ -510,7 +516,7 @@ class Date # # See: # - # * Argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). + # * Argument [start](rdoc-ref:language/calendars.rdoc@Argument+start). # * Argument [limit](rdoc-ref:Date@Argument+limit). # # Related: Date._parse (returns a hash). @@ -523,7 +529,7 @@ class Date # --> # Returns a new Date object with values parsed from `string`, which should be a # valid [RFC 2822 date - # format](rdoc-ref:strftime_formatting.rdoc@RFC+2822+Format): + # format](rdoc-ref:language/strftime_formatting.rdoc@RFC+2822+Format): # # d = Date.new(2001, 2, 3) # s = d.rfc2822 # => "Sat, 3 Feb 2001 00:00:00 +0000" @@ -531,7 +537,7 @@ class Date # # See: # - # * Argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). + # * Argument [start](rdoc-ref:language/calendars.rdoc@Argument+start). # * Argument [limit](rdoc-ref:Date@Argument+limit). # # Related: Date._rfc2822 (returns a hash). @@ -543,7 +549,8 @@ class Date # - Date.rfc3339(string = '-4712-01-01T00:00:00+00:00', start = Date::ITALY, limit: 128) -> date # --> # Returns a new Date object with values parsed from `string`, which should be a - # valid [RFC 3339 format](rdoc-ref:strftime_formatting.rdoc@RFC+3339+Format): + # valid [RFC 3339 + # format](rdoc-ref:language/strftime_formatting.rdoc@RFC+3339+Format): # # d = Date.new(2001, 2, 3) # s = d.rfc3339 # => "2001-02-03T00:00:00+00:00" @@ -551,7 +558,7 @@ class Date # # See: # - # * Argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). + # * Argument [start](rdoc-ref:language/calendars.rdoc@Argument+start). # * Argument [limit](rdoc-ref:Date@Argument+limit). # # Related: Date._rfc3339 (returns a hash). @@ -564,7 +571,7 @@ class Date # --> # Returns a new Date object with values parsed from `string`, which should be a # valid [RFC 2822 date - # format](rdoc-ref:strftime_formatting.rdoc@RFC+2822+Format): + # format](rdoc-ref:language/strftime_formatting.rdoc@RFC+2822+Format): # # d = Date.new(2001, 2, 3) # s = d.rfc2822 # => "Sat, 3 Feb 2001 00:00:00 +0000" @@ -572,7 +579,7 @@ class Date # # See: # - # * Argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). + # * Argument [start](rdoc-ref:language/calendars.rdoc@Argument+start). # * Argument [limit](rdoc-ref:Date@Argument+limit). # # Related: Date._rfc2822 (returns a hash). @@ -595,10 +602,10 @@ class Date # Date.strptime('sat3feb01', '%a%d%b%y') # => # # # For other formats, see [Formats for Dates and - # Times](rdoc-ref:strftime_formatting.rdoc). (Unlike Date.strftime, does not - # support flags and width.) + # Times](rdoc-ref:language/strftime_formatting.rdoc). (Unlike Date.strftime, + # does not support flags and width.) # - # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). + # See argument [start](rdoc-ref:language/calendars.rdoc@Argument+start). # # See also [strptime(3)](https://man7.org/linux/man-pages/man3/strptime.3.html). # @@ -614,7 +621,7 @@ class Date # # Date.today.to_s # => "2022-07-06" # - # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). + # See argument [start](rdoc-ref:language/calendars.rdoc@Argument+start). # def self.today: (?Integer start) -> Date @@ -629,7 +636,7 @@ class Date # Date.valid_date?(2001, 2, 29) # => false # Date.valid_date?(2001, 2, -1) # => true # - # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). + # See argument [start](rdoc-ref:language/calendars.rdoc@Argument+start). # # Related: Date.jd, Date.new. # @@ -647,7 +654,7 @@ class Date # # See Date.commercial. # - # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). + # See argument [start](rdoc-ref:language/calendars.rdoc@Argument+start). # # Related: Date.jd, Date.commercial. # @@ -664,7 +671,7 @@ class Date # Date.valid_date?(2001, 2, 29) # => false # Date.valid_date?(2001, 2, -1) # => true # - # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). + # See argument [start](rdoc-ref:language/calendars.rdoc@Argument+start). # # Related: Date.jd, Date.new. # @@ -679,7 +686,7 @@ class Date # # Date.valid_jd?(2451944) # => true # - # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). + # See argument [start](rdoc-ref:language/calendars.rdoc@Argument+start). # # Related: Date.jd. # @@ -695,7 +702,7 @@ class Date # Date.valid_ordinal?(2001, 34) # => true # Date.valid_ordinal?(2001, 366) # => false # - # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). + # See argument [start](rdoc-ref:language/calendars.rdoc@Argument+start). # # Related: Date.jd, Date.ordinal. # @@ -714,7 +721,7 @@ class Date # # See: # - # * Argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). + # * Argument [start](rdoc-ref:language/calendars.rdoc@Argument+start). # * Argument [limit](rdoc-ref:Date@Argument+limit). # # Related: Date._xmlschema (returns a hash). @@ -922,8 +929,8 @@ class Date # - asctime -> string # --> # Equivalent to #strftime with argument `'%a %b %e %T %Y'` (or its [shorthand - # form](rdoc-ref:strftime_formatting.rdoc@Shorthand+Conversion+Specifiers) - # `'%c'`): + # form](rdoc-ref:language/strftime_formatting.rdoc@Shorthand+Conversion+Specifie + # rs) `'%c'`): # # Date.new(2001, 2, 3).asctime # => "Sat Feb 3 00:00:00 2001" # @@ -933,8 +940,8 @@ class Date # # Equivalent to #strftime with argument `'%a %b %e %T %Y'` (or its [shorthand - # form](rdoc-ref:strftime_formatting.rdoc@Shorthand+Conversion+Specifiers) - # `'%c'`): + # form](rdoc-ref:language/strftime_formatting.rdoc@Shorthand+Conversion+Specifie + # rs) `'%c'`): # # Date.new(2001, 2, 3).asctime # => "Sat Feb 3 00:00:00 2001" # @@ -1065,7 +1072,7 @@ class Date # - httpdate -> string # --> # Equivalent to #strftime with argument `'%a, %d %b %Y %T GMT'`; see [Formats - # for Dates and Times](rdoc-ref:strftime_formatting.rdoc): + # for Dates and Times](rdoc-ref:language/strftime_formatting.rdoc): # # Date.new(2001, 2, 3).httpdate # => "Sat, 03 Feb 2001 00:00:00 GMT" # @@ -1087,8 +1094,8 @@ class Date # - iso8601 -> string # --> # Equivalent to #strftime with argument `'%Y-%m-%d'` (or its [shorthand - # form](rdoc-ref:strftime_formatting.rdoc@Shorthand+Conversion+Specifiers) - # `'%F'`); + # form](rdoc-ref:language/strftime_formatting.rdoc@Shorthand+Conversion+Specifie + # rs) `'%F'`); # # Date.new(2001, 2, 3).iso8601 # => "2001-02-03" # @@ -1225,7 +1232,7 @@ class Date # d1 = d0.new_start(Date::JULIAN) # d1.julian? # => true # - # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). + # See argument [start](rdoc-ref:language/calendars.rdoc@Argument+start). # def new_start: (?Integer start) -> Date @@ -1294,7 +1301,7 @@ class Date # - rfc2822 -> string # --> # Equivalent to #strftime with argument `'%a, %-d %b %Y %T %z'`; see [Formats - # for Dates and Times](rdoc-ref:strftime_formatting.rdoc): + # for Dates and Times](rdoc-ref:language/strftime_formatting.rdoc): # # Date.new(2001, 2, 3).rfc2822 # => "Sat, 3 Feb 2001 00:00:00 +0000" # @@ -1305,7 +1312,7 @@ class Date # - rfc3339 -> string # --> # Equivalent to #strftime with argument `'%FT%T%:z'`; see [Formats for Dates and - # Times](rdoc-ref:strftime_formatting.rdoc): + # Times](rdoc-ref:language/strftime_formatting.rdoc): # # Date.new(2001, 2, 3).rfc3339 # => "2001-02-03T00:00:00+00:00" # @@ -1314,7 +1321,7 @@ class Date # # Returns a new Date object with values parsed from `string`, which should be a # valid [RFC 2822 date - # format](rdoc-ref:strftime_formatting.rdoc@RFC+2822+Format): + # format](rdoc-ref:language/strftime_formatting.rdoc@RFC+2822+Format): # # d = Date.new(2001, 2, 3) # s = d.rfc2822 # => "Sat, 3 Feb 2001 00:00:00 +0000" @@ -1322,7 +1329,7 @@ class Date # # See: # - # * Argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). + # * Argument [start](rdoc-ref:language/calendars.rdoc@Argument+start). # * Argument [limit](rdoc-ref:Date@Argument+limit). # # Related: Date._rfc2822 (returns a hash). @@ -1355,7 +1362,7 @@ class Date # Date.new(2001, 2, 3, Date::GREGORIAN).start # => -Infinity # Date.new(2001, 2, 3, Date::JULIAN).start # => Infinity # - # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). + # See argument [start](rdoc-ref:language/calendars.rdoc@Argument+start). # def start: () -> Float @@ -1401,7 +1408,7 @@ class Date # Date.new(2001, 2, 3).strftime # => "2001-02-03" # # For other formats, see [Formats for Dates and - # Times](rdoc-ref:strftime_formatting.rdoc). + # Times](rdoc-ref:language/strftime_formatting.rdoc). # def strftime: (?String format) -> String @@ -1453,8 +1460,9 @@ class Date # - to_s -> string # --> # Returns a string representation of the date in `self` in [ISO 8601 extended - # date format](rdoc-ref:strftime_formatting.rdoc@ISO+8601+Format+Specifications) - # (`'%Y-%m-%d'`): + # date + # format](rdoc-ref:language/strftime_formatting.rdoc@ISO+8601+Format+Specificati + # ons) (`'%Y-%m-%d'`): # # Date.new(2001, 2, 3).to_s # => "2001-02-03" # @@ -1509,8 +1517,8 @@ class Date # # Equivalent to #strftime with argument `'%Y-%m-%d'` (or its [shorthand - # form](rdoc-ref:strftime_formatting.rdoc@Shorthand+Conversion+Specifiers) - # `'%F'`); + # form](rdoc-ref:language/strftime_formatting.rdoc@Shorthand+Conversion+Specifie + # rs) `'%F'`); # # Date.new(2001, 2, 3).iso8601 # => "2001-02-03" # diff --git a/stdlib/date/0/date_time.rbs b/stdlib/date/0/date_time.rbs index 96c6b71ae..f4aa0c0ab 100644 --- a/stdlib/date/0/date_time.rbs +++ b/stdlib/date/0/date_time.rbs @@ -555,7 +555,7 @@ class DateTime < Date # DateTime.now.strftime # => "2022-07-01T11:03:19-05:00" # # For other formats, see [Formats for Dates and - # Times](rdoc-ref:strftime_formatting.rdoc): + # Times](rdoc-ref:language/strftime_formatting.rdoc): # def strftime: (?String format) -> String diff --git a/stdlib/json/0/json.rbs b/stdlib/json/0/json.rbs index c1d642544..1fe8f538c 100644 --- a/stdlib/json/0/json.rbs +++ b/stdlib/json/0/json.rbs @@ -880,6 +880,7 @@ module JSON # # Returns the Ruby objects created by parsing the given `source`. diff --git a/stdlib/openssl/0/openssl.rbs b/stdlib/openssl/0/openssl.rbs index 560534519..75bc338d0 100644 --- a/stdlib/openssl/0/openssl.rbs +++ b/stdlib/openssl/0/openssl.rbs @@ -367,7 +367,7 @@ # ## SSL and TLS Connections # # Using our created key and certificate we can create an SSL or TLS connection. -# An SSLContext is used to set up an SSL session. +# An OpenSSL::SSL::SSLContext is used to set up an SSL session. # # context = OpenSSL::SSL::SSLContext.new # @@ -379,8 +379,8 @@ # context.cert = cert # context.key = key # -# Then create an SSLServer with a TCP server socket and the context. Use the -# SSLServer like an ordinary TCP server. +# Then create an OpenSSL::SSL::SSLServer with a TCP server socket and the +# context. Use the SSLServer like an ordinary TCP server. # # require 'socket' # @@ -401,12 +401,13 @@ # # ### SSL client # -# An SSL client is created with a TCP socket and the context. SSLSocket#connect -# must be called to initiate the SSL handshake and start encryption. A key and -# certificate are not required for the client socket. +# An SSL client is created with a TCP socket and the context. +# OpenSSL::SSL::SSLSocket#connect must be called to initiate the SSL handshake +# and start encryption. A key and certificate are not required for the client +# socket. # -# Note that SSLSocket#close doesn't close the underlying socket by default. Set -# SSLSocket#sync_close to true if you want. +# Note that OpenSSL::SSL::SSLSocket#close doesn't close the underlying socket by +# default. Set OpenSSL::SSL::SSLSocket#sync_close to true if you want. # # require 'socket' # @@ -455,7 +456,7 @@ module OpenSSL # OpenSSL::Digest("MD5") # # => OpenSSL::Digest::MD5 # - # Digest("Foo") + # OpenSSL::Digest("Foo") # # => NameError: wrong constant name Foo # def self.Digest: (String name) -> singleton(Digest) @@ -464,12 +465,13 @@ module OpenSSL # rdoc-file=ext/openssl/ossl.c # - OpenSSL.debug -> true | false # --> + # Returns whether Ruby/OpenSSL's debug mode is currently enabled. # def self.debug: () -> bool # # Turns on or off debug mode. With debug mode, all errors added to the OpenSSL # error queue will be printed to stderr. @@ -480,10 +482,14 @@ module OpenSSL # rdoc-file=ext/openssl/ossl.c # - OpenSSL.errors -> [String...] # --> - # See any remaining errors held in queue. + # Returns any remaining errors held in the OpenSSL thread-local error queue and + # clears the queue. This should normally return an empty array. # - # Any errors you see here are probably due to a bug in Ruby's OpenSSL - # implementation. + # This is intended for debugging Ruby/OpenSSL. If you see any errors here, it + # likely indicates a bug in the extension. Please file an issue at + # https://github.com/ruby/openssl. + # + # For debugging your program, OpenSSL.debug= may be useful. # def self.errors: () -> Array[String] @@ -491,12 +497,13 @@ module OpenSSL # rdoc-file=ext/openssl/ossl.c # - OpenSSL.fips_mode -> true | false # --> + # Returns whether the FIPS mode is currently enabled. # def self.fips_mode: () -> bool # # Turns FIPS mode on or off. Turning on FIPS mode will obviously only have an # effect for FIPS-capable installations of the OpenSSL library. Trying to do so @@ -510,60 +517,74 @@ module OpenSSL # # Constant time memory comparison for fixed length strings, such as results of # HMAC calculations. # # Returns `true` if the strings are identical, `false` if they are of the same - # length but not identical. If the length is different, `ArgumentError` is - # raised. + # length but not identical. If the length is different, ArgumentError is raised. # def self.fixed_length_secure_compare: (String, String) -> bool # # Constant time memory comparison. Inputs are hashed using SHA-256 to mask the # length of the secret. Returns `true` if the strings are identical, `false` # otherwise. # + # This method is expensive due to the SHA-256 hashing. In most cases, where the + # input lengths are known to be equal or are not sensitive, + # OpenSSL.fixed_length_secure_compare should be used instead. + # def self.secure_compare: (String a, String b) -> bool # - # Boolean indicating whether OpenSSL is FIPS-capable or not + # Boolean indicating whether the OpenSSL library is FIPS-capable or not. Always + # `true` for OpenSSL 3.0 and later. + # + # This is obsolete and will be removed in the future. See also + # OpenSSL.fips_mode. # OPENSSL_FIPS: bool # - # Version of OpenSSL the ruby OpenSSL extension is running with + # OpenSSL library version string currently used at runtime. # OPENSSL_LIBRARY_VERSION: String # - # Version of OpenSSL the ruby OpenSSL extension was built with + # OpenSSL library version string used to compile the Ruby/OpenSSL extension. + # This may differ from the version used at runtime. # OPENSSL_VERSION: String # - # Version number of OpenSSL the ruby OpenSSL extension was built with (base 16). - # The formats are below. + # OpenSSL library version number used to compile the Ruby/OpenSSL extension. + # This may differ from the version used at runtime. # - # OpenSSL 3 - # : `0xMNN00PP0 (major minor 00 patch 0)` + # The version number is encoded into a single integer value. The number follows + # the format: # - # OpenSSL before 3 - # : `0xMNNFFPPS (major minor fix patch status)` + # OpenSSL 3.0.0 or later + # : `0xMNN00PP0` (major minor 00 patch 0) + # + # OpenSSL 1.1.1 or earlier + # : `0xMNNFFPPS` (major minor fix patch status) # # LibreSSL - # : `0x20000000 (fixed value)` + # : `0x20000000` (a fixed value) # # # See also the man page OPENSSL_VERSION_NUMBER(3). # OPENSSL_VERSION_NUMBER: Integer + # + # The version string of Ruby/OpenSSL. + # VERSION: String # @@ -934,7 +955,7 @@ module OpenSSL # puts int2.value # => 1 # class ASN1Data - # + # # Never `nil`. A boolean value indicating whether the encoding uses indefinite # length (in the case of parsing) or whether an indefinite length form shall be # used (in the encoding case). In DER, every value uses definite length form. @@ -951,7 +972,7 @@ module OpenSSL # def indefinite_length: () -> bool - # + # # Never `nil`. A boolean value indicating whether the encoding uses indefinite # length (in the case of parsing) or whether an indefinite length form shall be # used (in the encoding case). In DER, every value uses definite length form. @@ -968,7 +989,7 @@ module OpenSSL # def indefinite_length=: [U] (boolish) -> U - # + # # Never `nil`. A boolean value indicating whether the encoding uses indefinite # length (in the case of parsing) or whether an indefinite length form shall be # used (in the encoding case). In DER, every value uses definite length form. @@ -985,7 +1006,7 @@ module OpenSSL # alias infinite_length indefinite_length - # + # # Never `nil`. A boolean value indicating whether the encoding uses indefinite # length (in the case of parsing) or whether an indefinite length form shall be # used (in the encoding case). In DER, every value uses definite length form. @@ -1002,24 +1023,24 @@ module OpenSSL # alias infinite_length= indefinite_length= - # + # # An Integer representing the tag number of this ASN1Data. Never `nil`. # def tag: () -> bn - # + # # An Integer representing the tag number of this ASN1Data. Never `nil`. # def tag=: (::Integer) -> ::Integer | (BN) -> BN - # + # # A Symbol representing the tag class of this ASN1Data. Never `nil`. See # ASN1Data for possible values. # def tag_class: () -> tag_class - # + # # A Symbol representing the tag class of this ASN1Data. Never `nil`. See # ASN1Data for possible values. # @@ -1036,13 +1057,13 @@ module OpenSSL # def to_der: () -> String - # + # # Carries the value of a ASN.1 type. Please confer Constructive and Primitive # for the mappings between ASN.1 data types and Ruby classes. # def value: () -> untyped - # + # # Carries the value of a ASN.1 type. Please confer Constructive and Primitive # for the mappings between ASN.1 data types and Ruby classes. # @@ -1051,7 +1072,7 @@ module OpenSSL private # # *value*: Please have a look at Constructive and Primitive to see how Ruby @@ -1123,7 +1144,7 @@ module OpenSSL include Enumerable[ASN1Data] # # Calls the given block once for each element in self, passing that element as @@ -5076,7 +5097,11 @@ module OpenSSL end # - # Generic error, common for all classes under OpenSSL module + # Generic error class for OpenSSL. All error classes in this library inherit + # from this class. + # + # This class indicates that an error was reported by the underlying OpenSSL + # library. # class OpenSSLError < StandardError end @@ -6677,9 +6702,10 @@ module OpenSSL # - # Returns the curve name (sn). + # Returns the curve name (short name) corresponding to this group, or `nil` if + # OpenSSL does not have an OID associated with the group. # # See the OpenSSL documentation for EC_GROUP_get_curve_name() # @@ -9568,45 +9594,33 @@ module OpenSSL # fac.additional_certificates = [ inter1, inter2 ] # timestamp = fac.create_timestamp(p12.key, p12.certificate, req) # - # ## Attributes - # - # ### default_policy_id - # - # Request#policy_id will always be preferred over this if present in the - # Request, only if Request#policy_id is nil default_policy will be used. If none - # of both is present, a TimestampError will be raised when trying to create a - # Response. - # - # ### serial_number - # - # Sets or retrieves the serial number to be used for timestamp creation. Must be - # present for timestamp creation. - # - # ### gen_time - # - # Sets or retrieves the Time value to be used in the Response. Must be present - # for timestamp creation. - # - # ### additional_certs - # - # Sets or retrieves additional certificates apart from the timestamp certificate - # (e.g. intermediate certificates) to be added to the Response. Must be an Array - # of OpenSSL::X509::Certificate. - # - # ### allowed_digests - # - # Sets or retrieves the digest algorithms that the factory is allowed create - # timestamps for. Known vulnerable or weak algorithms should not be allowed - # where possible. Must be an Array of String or OpenSSL::Digest subclass - # instances. - # class Factory + # + # Additional certificates apart from the timestamp certificate (e.g. + # intermediate certificates) to be added to the Response. Must be an Array of + # OpenSSL::X509::Certificate, or `nil`. + # def additional_certs: () -> Array[X509::Certificate]? + # + # Additional certificates apart from the timestamp certificate (e.g. + # intermediate certificates) to be added to the Response. Must be an Array of + # OpenSSL::X509::Certificate, or `nil`. + # def additional_certs=: (Array[X509::Certificate]? certs) -> Array[X509::Certificate]? + # + # The list of digest algorithms that the factory is allowed create timestamps + # for. Known vulnerable or weak algorithms should not be allowed where possible. + # Must be an Array of String or OpenSSL::Digest subclass instances. + # def allowed_digests: () -> Array[String | Digest]? + # + # The list of digest algorithms that the factory is allowed create timestamps + # for. Known vulnerable or weak algorithms should not be allowed where possible. + # Must be an Array of String or OpenSSL::Digest subclass instances. + # def allowed_digests=: (Array[String | Digest]) -> Array[String | Digest] # + # A String representing the default policy object identifier, or `nil`. + # + # Request#policy_id will always be preferred over this if present in the + # Request, only if Request#policy_id is `nil` default_policy will be used. If + # none of both is present, a TimestampError will be raised when trying to create + # a Response. + # def default_policy_id: () -> String? + # + # A String representing the default policy object identifier, or `nil`. + # + # Request#policy_id will always be preferred over this if present in the + # Request, only if Request#policy_id is `nil` default_policy will be used. If + # none of both is present, a TimestampError will be raised when trying to create + # a Response. + # def default_policy_id=: (String) -> String + # + # The Time value to be used in the Response. Must be present for timestamp + # creation. + # def gen_time: () -> Time? + # + # The Time value to be used in the Response. Must be present for timestamp + # creation. + # def gen_time=: (Time) -> Time + # + # The serial number to be used for timestamp creation. Must be present for + # timestamp creation. Must be an instance of OpenSSL::BN or Integer. + # def serial_number: () -> Integer? + # + # The serial number to be used for timestamp creation. Must be present for + # timestamp creation. Must be an instance of OpenSSL::BN or Integer. + # def serial_number=: (Integer) -> Integer end @@ -10338,8 +10384,10 @@ module OpenSSL # + # Returns the OID of the attribute. Returns the short name or the dotted decimal + # notation. # def oid: () -> String @@ -10501,8 +10549,12 @@ module OpenSSL # + # Returns the signature algorithm used to sign this CRL. + # + # Returns the long name of the signature algorithm, or the dotted decimal + # notation if OpenSSL does not define a long name for it. # def signature_algorithm: () -> String @@ -10682,6 +10734,12 @@ module OpenSSL # Compares the two certificates. Note that this takes into account all fields, # not just the issuer name and the serial number. # + # This method uses X509_cmp() from OpenSSL, which compares certificates based on + # their cached DER encodings. The comparison can be unreliable if a certificate + # is incomplete. + # + # See also the man page X509_cmp(3). + # def ==: (self other) -> bool # # @@ -10809,6 +10867,12 @@ module OpenSSL # rdoc-file=ext/openssl/ossl_x509cert.c # - cert.signature_algorithm => string # --> + # Returns the signature algorithm used to sign this certificate. This returns + # the algorithm name found in the TBSCertificate structure, not the outer + # Certificate structure. + # + # Returns the long name of the signature algorithm, or the dotted decimal + # notation if OpenSSL does not define a long name for it. # def signature_algorithm: () -> String @@ -10926,8 +10990,10 @@ module OpenSSL # + # Returns the OID of the extension. Returns the short name or the dotted decimal + # notation. # def oid: () -> String @@ -11580,8 +11646,12 @@ module OpenSSL # + # Returns the signature algorithm used to sign this request. + # + # Returns the long name of the signature algorithm, or the dotted decimal + # notation if OpenSSL does not define a long name for it. # def signature_algorithm: () -> String diff --git a/stdlib/psych/0/psych.rbs b/stdlib/psych/0/psych.rbs index d71303d1c..5adf06e53 100644 --- a/stdlib/psych/0/psych.rbs +++ b/stdlib/psych/0/psych.rbs @@ -265,7 +265,7 @@ module Psych # # Load `yaml` in to a Ruby data structure. If multiple documents are provided, # the object contained in the first document will be returned. `filename` will @@ -312,7 +312,7 @@ module Psych # # Safely load the yaml string in `yaml`. By default, only the following classes # are allowed to be deserialized: @@ -363,7 +363,7 @@ module Psych # # Load `yaml` in to a Ruby data structure. If multiple documents are provided, # the object contained in the first document will be returned. `filename` will diff --git a/stdlib/stringio/0/stringio.rbs b/stdlib/stringio/0/stringio.rbs index 8a65ef3da..f09a2e1cb 100644 --- a/stdlib/stringio/0/stringio.rbs +++ b/stdlib/stringio/0/stringio.rbs @@ -1,12 +1,33 @@ # -# IO streams for strings, with access similar to -# [IO](rdoc-ref:IO); -# see [IO](rdoc-ref:IO). -# ### About the Examples +# Class StringIO supports accessing a string as a stream, +# similar in some ways to [class +# IO](https://docs.ruby-lang.org/en/master/IO.html). +# You can create a StringIO instance using: +# * StringIO.new: returns a new StringIO object containing the given string. +# * StringIO.open: passes a new StringIO object to the given block. +# Like an IO stream, a StringIO stream has certain properties: +# * **Read/write mode**: whether the stream may be read, written, appended to, +# etc.; +# see [Read/Write Mode](rdoc-ref:StringIO@Read-2FWrite+Mode). +# * **Data mode**: text-only or binary; +# see [Data Mode](rdoc-ref:StringIO@Data+Mode). +# * **Encodings**: internal and external encodings; +# see [Encodings](rdoc-ref:StringIO@Encodings). +# * **Position**: where in the stream the next read or write is to occur; +# see [Position](rdoc-ref:StringIO@Position). +# * **Line number**: a special, line-oriented, "position" (different from the +# position mentioned above); +# see [Line Number](rdoc-ref:StringIO@Line+Number). +# * **Open/closed**: whether the stream is open or closed, for reading or +# writing. +# see [Open/Closed Streams](rdoc-ref:StringIO@Open-2FClosed+Streams). +# * **BOM**: byte mark order; +# see [Byte Order Mark](rdoc-ref:StringIO@BOM+-28Byte+Order+Mark-29). +# ## About the Examples # Examples on this page assume that StringIO has been required: # require 'stringio' # -# And that these constants have been defined: +# And that this constant has been defined: # TEXT = < 0 # Beginning-of-stream. +# strio.string # => "foobarbaz" # Not cleared. +# +# May be read anywhere: +# strio.gets(3) # => "foo" +# strio.gets(3) # => "bar" +# strio.pos = 9 +# strio.gets(3) # => nil +# +# May not be written: +# strio.write('foo') # Raises IOError: not opened for writing +# +# #### `'w'`: Write-Only +# Mode specified as one of: +# * String: `'w'`. +# * Constant: `File::WRONLY`. +# Initial state: +# strio = StringIO.new('foo', 'w') +# strio.pos # => 0 # Beginning of stream. +# strio.string # => "" # Initially cleared. +# +# May be written anywhere (even past end-of-stream): +# strio.write('foobar') +# strio.string # => "foobar" +# strio.rewind +# strio.write('FOO') +# strio.string # => "FOObar" +# strio.pos = 3 +# strio.write('BAR') +# strio.string # => "FOOBAR" +# strio.pos = 9 +# strio.write('baz') +# strio.string # => "FOOBAR\u0000\u0000\u0000baz" # Null-padded. +# +# May not be read: +# strio.read # Raises IOError: not opened for reading +# +# #### `'a'`: Append-Only +# Mode specified as one of: +# * String: `'a'`. +# * Constant: `File::WRONLY | File::APPEND`. +# Initial state: +# strio = StringIO.new('foo', 'a') +# strio.pos # => 0 # Beginning-of-stream. +# strio.string # => "foo" # Not cleared. +# +# May be written only at the end; position does not affect writing: +# strio.write('bar') +# strio.string # => "foobar" +# strio.write('baz') +# strio.string # => "foobarbaz" +# strio.pos = 400 +# strio.write('bat') +# strio.string # => "foobarbazbat" +# +# May not be read: +# strio.gets # Raises IOError: not opened for reading +# +# #### `'r+'`: Read/Write +# Mode specified as one of: +# * String: `'r+'`. +# * Constant: `File::RDRW`. +# Initial state: +# strio = StringIO.new('foobar', 'r+') +# strio.pos # => 0 # Beginning-of-stream. +# strio.string # => "foobar" # Not cleared. +# +# May be written anywhere (even past end-of-stream): +# strio.write('FOO') +# strio.string # => "FOObar" +# strio.write('BAR') +# strio.string # => "FOOBAR" +# strio.write('BAZ') +# strio.string # => "FOOBARBAZ" +# strio.pos = 12 +# strio.write('BAT') +# strio.string # => "FOOBARBAZ\u0000\u0000\u0000BAT" # Null padded. +# +# May be read anywhere: +# strio.pos = 0 +# strio.gets(3) # => "FOO" +# strio.pos = 6 +# strio.gets(3) # => "BAZ" +# strio.pos = 400 +# strio.gets(3) # => nil +# +# #### `'w+'`: Read/Write (Initially Clear) +# Mode specified as one of: +# * String: `'w+'`. +# * Constant: `File::RDWR | File::TRUNC`. +# Initial state: +# strio = StringIO.new('foo', 'w+') +# strio.pos # => 0 # Beginning-of-stream. +# strio.string # => "" # Truncated. +# +# May be written anywhere (even past end-of-stream): +# strio.write('foobar') +# strio.string # => "foobar" +# strio.rewind +# strio.write('FOO') +# strio.string # => "FOObar" +# strio.write('BAR') +# strio.string # => "FOOBAR" +# strio.write('BAZ') +# strio.string # => "FOOBARBAZ" +# strio.pos = 12 +# strio.write('BAT') +# strio.string # => "FOOBARBAZ\u0000\u0000\u0000BAT" # Null-padded. +# +# May be read anywhere: +# strio.rewind +# strio.gets(3) # => "FOO" +# strio.gets(3) # => "BAR" +# strio.pos = 12 +# strio.gets(3) # => "BAT" +# strio.pos = 400 +# strio.gets(3) # => nil +# +# #### `'a+'`: Read/Append +# Mode specified as one of: +# * String: `'a+'`. +# * Constant: `File::RDWR | File::APPEND`. +# Initial state: +# strio = StringIO.new('foo', 'a+') +# strio.pos # => 0 # Beginning-of-stream. +# strio.string # => "foo" # Not cleared. +# +# May be written only at the end; #rewind; position does not affect writing: +# strio.write('bar') +# strio.string # => "foobar" +# strio.write('baz') +# strio.string # => "foobarbaz" +# strio.pos = 400 +# strio.write('bat') +# strio.string # => "foobarbazbat" +# +# May be read anywhere: +# strio.rewind +# strio.gets(3) # => "foo" +# strio.gets(3) # => "bar" +# strio.pos = 9 +# strio.gets(3) # => "bat" +# strio.pos = 400 +# strio.gets(3) # => nil +# +# ### Data Mode +# To specify whether the stream is to be treated as text or as binary data, +# either of the following may be suffixed to any of the string read/write modes +# above: +# * `'t'`: Text; +# initializes the encoding as Encoding::UTF_8. +# * `'b'`: Binary; +# initializes the encoding as Encoding::ASCII_8BIT. +# If neither is given, the stream defaults to text data. +# Examples: +# strio = StringIO.new('foo', 'rt') +# strio.external_encoding # => # +# data = "\u9990\u9991\u9992\u9993\u9994" +# strio = StringIO.new(data, 'rb') +# strio.external_encoding # => # +# +# When the data mode is specified, the read/write mode may not be omitted: +# StringIO.new(data, 'b') # Raises ArgumentError: invalid access mode b +# +# A text stream may be changed to binary by calling instance method #binmode; +# a binary stream may not be changed to text. +# ### Encodings +# A stream has an encoding; see +# [Encodings](https://docs.ruby-lang.org/en/master/language/encodings_rdoc.html) +# . +# The initial encoding for a new or re-opened stream depends on its [data +# mode](rdoc-ref:StringIO@Data+Mode): +# * Text: `Encoding::UTF_8`. +# * Binary: `Encoding::ASCII_8BIT`. +# These instance methods are relevant: +# * #external_encoding: returns the current encoding of the stream as an +# `Encoding` object. +# * #internal_encoding: returns `nil`; a stream does not have an internal +# encoding. +# * #set_encoding: sets the encoding for the stream. +# * #set_encoding_by_bom: sets the encoding for the stream to the stream's BOM +# (byte order mark). +# Examples: +# strio = StringIO.new('foo', 'rt') # Text mode. +# strio.external_encoding # => # +# data = "\u9990\u9991\u9992\u9993\u9994" +# strio = StringIO.new(data, 'rb') # Binary mode. +# strio.external_encoding # => # +# strio = StringIO.new('foo') +# strio.external_encoding # => # +# strio.set_encoding('US-ASCII') +# strio.external_encoding # => # +# +# ### Position +# A stream has a *position*, and integer offset (in bytes) into the stream. +# The initial position of a stream is zero. +# #### Getting and Setting the Position +# Each of these methods initializes (to zero) the position of a new or re-opened +# stream: +# * ::new: returns a new stream. +# * ::open: passes a new stream to the block. +# * #reopen: re-initializes the stream. +# Each of these methods queries, gets, or sets the position, without otherwise +# changing the stream: +# * #eof?: returns whether the position is at end-of-stream. +# * #pos: returns the position. +# * #pos=: sets the position. +# * #rewind: sets the position to zero. +# * #seek: sets the position. +# Examples: +# strio = StringIO.new('foobar') +# strio.pos # => 0 +# strio.pos = 3 +# strio.pos # => 3 +# strio.eof? # => false +# strio.rewind +# strio.pos # => 0 +# strio.seek(0, IO::SEEK_END) +# strio.pos # => 6 +# strio.eof? # => true +# +# #### Position Before and After Reading +# Except for #pread, a stream reading method (see [Basic +# Reading](rdoc-ref:StringIO@Basic+Reading)) +# begins reading at the current position. +# Except for #pread, a read method advances the position past the read +# substring. +# Examples: +# strio = StringIO.new(TEXT) +# strio.string # => "First line\nSecond line\n\nFourth line\nFifth line\n" +# strio.pos # => 0 +# strio.getc # => "F" +# strio.pos # => 1 +# strio.gets # => "irst line\n" +# strio.pos # => 11 +# strio.pos = 24 +# strio.gets # => "Fourth line\n" +# strio.pos # => 36 +# +# strio = StringIO.new('тест') # Four 2-byte characters. +# strio.pos = 0 # At first byte of first character. +# strio.read # => "тест" +# strio.pos = 1 # At second byte of first character. +# strio.read # => "\x82ест" +# strio.pos = 2 # At first of second character. +# strio.read # => "ест" +# +# strio = StringIO.new(TEXT) +# strio.pos = 15 +# a = [] +# strio.each_line {|line| a.push(line) } +# a # => ["nd line\n", "\n", "Fourth line\n", "Fifth line\n"] +# strio.pos # => 47 ## End-of-stream. +# +# #### Position Before and After Writing +# Each of these methods begins writing at the current position, +# and advances the position to the end of the written substring: +# * #putc: writes the given character. +# * #write: writes the given objects as strings. +# * [Kernel#puts](https://docs.ruby-lang.org/en/master/Kernel.html#method-i-pu +# ts): writes given objects as strings, each followed by newline. +# Examples: +# strio = StringIO.new('foo') +# strio.pos # => 0 +# strio.putc('b') +# strio.string # => "boo" +# strio.pos # => 1 +# strio.write('r') +# strio.string # => "bro" +# strio.pos # => 2 +# strio.puts('ew') +# strio.string # => "brew\n" +# strio.pos # => 5 +# strio.pos = 8 +# strio.write('foo') +# strio.string # => "brew\n\u0000\u0000\u0000foo" +# strio.pos # => 11 +# +# Each of these methods writes *before* the current position, and decrements the +# position +# so that the written data is next to be read: +# * #ungetbyte: unshifts the given byte. +# * #ungetc: unshifts the given character. +# Examples: +# strio = StringIO.new('foo') +# strio.pos = 2 +# strio.ungetc('x') +# strio.pos # => 1 +# strio.string # => "fxo" +# strio.ungetc('x') +# strio.pos # => 0 +# strio.string # => "xxo" +# +# This method does not affect the position: +# * #truncate: truncates the stream's string to the given size. +# Examples: +# strio = StringIO.new('foobar') +# strio.pos # => 0 +# strio.truncate(3) +# strio.string # => "foo" +# strio.pos # => 0 +# strio.pos = 500 +# strio.truncate(0) +# strio.string # => "" +# strio.pos # => 500 +# +# ### Line Number +# A stream has a line number, which initially is zero: +# * Method #lineno returns the line number. +# * Method #lineno= sets the line number. +# The line number can be affected by reading (but never by writing); +# in general, the line number is incremented each time the record separator +# (default: `"\n"`) is read. +# Examples: +# strio = StringIO.new(TEXT) +# strio.string # => "First line\nSecond line\n\nFourth line\nFifth line\n" +# strio.lineno # => 0 +# strio.gets # => "First line\n" +# strio.lineno # => 1 +# strio.getc # => "S" +# strio.lineno # => 1 +# strio.gets # => "econd line\n" +# strio.lineno # => 2 +# strio.gets # => "\n" +# strio.lineno # => 3 +# strio.gets # => "Fourth line\n" +# strio.lineno # => 4 +# +# Setting the position does not affect the line number: +# strio.pos = 0 +# strio.lineno # => 4 +# strio.gets # => "First line\n" +# strio.pos # => 11 +# strio.lineno # => 5 +# +# And setting the line number does not affect the position: +# strio.lineno = 10 +# strio.pos # => 11 +# strio.gets # => "Second line\n" +# strio.lineno # => 11 +# strio.pos # => 23 +# +# ### Open/Closed Streams +# A new stream is open for either reading or writing, and may be open for both; +# see [Read/Write Mode](rdoc-ref:StringIO@Read-2FWrite+Mode). +# Each of these methods initializes the read/write mode for a new or re-opened +# stream: +# * ::new: returns a new stream. +# * ::open: passes a new stream to the block. +# * #reopen: re-initializes the stream. +# Other relevant methods: +# * #close: closes the stream for both reading and writing. +# * #close_read: closes the stream for reading. +# * #close_write: closes the stream for writing. +# * #closed?: returns whether the stream is closed for both reading and +# writing. +# * #closed_read?: returns whether the stream is closed for reading. +# * #closed_write?: returns whether the stream is closed for writing. +# ### BOM (Byte Order Mark) +# The string provided for ::new, ::open, or #reopen +# may contain an optional [BOM](https://en.wikipedia.org/wiki/Byte_order_mark) +# (byte order mark) at the beginning of the string; +# the BOM can affect the stream's encoding. +# The BOM (if provided): +# * Is stored as part of the stream's string. +# * Does *not* immediately affect the encoding. +# * Is *initially* considered part of the stream. +# utf8_bom = "\xEF\xBB\xBF" +# string = utf8_bom + 'foo' +# string.bytes # => [239, 187, 191, 102, 111, 111] +# strio.string.bytes.take(3) # => [239, 187, 191] # The BOM. +# strio = StringIO.new(string, 'rb') +# strio.string.bytes # => [239, 187, 191, 102, 111, 111] # BOM is part of the stored string. +# strio.external_encoding # => # # Default for a binary stream. +# strio.gets # => "\xEF\xBB\xBFfoo" # BOM is part of the stream. +# +# You can call instance method #set_encoding_by_bom to "activate" the stored +# BOM; +# after doing so the BOM: +# * Is *still* stored as part of the stream's string. +# * *Determines* (and may have changed) the stream's encoding. +# * Is *no longer* considered part of the stream. +# strio.set_encoding_by_bom +# strio.string.bytes # => [239, 187, 191, 102, 111, 111] # BOM is still part of the stored string. +# strio.external_encoding # => # # The new encoding. +# strio.rewind # => 0 +# strio.gets # => "foo" # BOM is not part of the stream. +# +# ## Basic Stream IO +# ### Basic Reading +# You can read from the stream using these instance methods: +# * #getbyte: reads and returns the next byte. +# * #getc: reads and returns the next character. +# * #gets: reads and returns all or part of the next line. +# * #read: reads and returns all or part of the remaining data in the stream. +# * #readlines: reads the remaining data the stream and returns an array of +# its lines. +# * [Kernel#readline](https://docs.ruby-lang.org/en/master/Kernel.html#method- +# i-readline): like #gets, but raises an exception if at end-of-stream. +# You can iterate over the stream using these instance methods: +# * #each_byte: reads each remaining byte, passing it to the block. +# * #each_char: reads each remaining character, passing it to the block. +# * #each_codepoint: reads each remaining codepoint, passing it to the block. +# * #each_line: reads all or part of each remaining line, passing the read +# string to the block +# This instance method is useful in a multi-threaded application: +# * #pread: reads and returns all or part of the stream. +# ### Basic Writing +# You can write to the stream, advancing the position, using these instance +# methods: +# * #putc: writes a given character. +# * #write: writes the given objects as strings. +# * [Kernel#puts](https://docs.ruby-lang.org/en/master/Kernel.html#method-i-pu +# ts) writes given objects as strings, each followed by newline. +# You can "unshift" to the stream using these instance methods; +# each writes *before* the current position, and decrements the position +# so that the written data is next to be read. +# * #ungetbyte: unshifts the given byte. +# * #ungetc: unshifts the given character. +# One more writing method: +# * #truncate: truncates the stream's string to the given size. +# ## Line IO +# Reading: +# * #gets: reads and returns the next line. +# * [Kernel#readline](https://docs.ruby-lang.org/en/master/Kernel.html#method- +# i-readline): like #gets, but raises an exception if at end-of-stream. +# * #readlines: reads the remaining data the stream and returns an array of +# its lines. +# * #each_line: reads each remaining line, passing it to the block +# Writing: +# * [Kernel#puts](https://docs.ruby-lang.org/en/master/Kernel.html#method-i-pu +# ts): writes given objects, each followed by newline. +# ## Character IO +# Reading: +# * #each_char: reads each remaining character, passing it to the block. +# * #getc: reads and returns the next character. +# Writing: +# * #putc: writes the given character. +# * #ungetc.: unshifts the given character. +# ## Byte IO +# Reading: +# * #each_byte: reads each remaining byte, passing it to the block. +# * #getbyte: reads and returns the next byte. +# Writing: +# * #ungetbyte: unshifts the given byte. +# ## Codepoint IO +# Reading: +# * #each_codepoint: reads each remaining codepoint, passing it to the block. # class StringIO # # Sets the data mode in `self` to binary mode; see [Data - # Mode](rdoc-ref:File@Data+Mode). + # Mode](rdoc-ref:StringIO@Data+Mode). # def binmode: () -> self @@ -188,6 +678,137 @@ class StringIO # - each_line(limit, chomp: false) {|line| ... } -> self # - each_line(sep, limit, chomp: false) {|line| ... } -> self # --> + # With a block given calls the block with each remaining line (see "Position" + # below) in the stream; + # returns `self`. + # Leaves stream position at end-of-stream. + # **No Arguments** + # With no arguments given, + # reads lines using the default record separator + # (global variable `$/`, whose initial value is `"\n"`). + # strio = StringIO.new(TEXT) + # strio.each_line {|line| p line } + # strio.eof? # => true + # + # Output: + # "First line\n" + # "Second line\n" + # "\n" + # "Fourth line\n" + # "Fifth line\n" + # + # **Argument `sep`** + # With only string argument `sep` given, + # reads lines using that string as the record separator: + # strio = StringIO.new(TEXT) + # strio.each_line(' ') {|line| p line } + # + # Output: + # "First " + # "line\nSecond " + # "line\n\nFourth " + # "line\nFifth " + # "line\n" + # + # **Argument `limit`** + # With only integer argument `limit` given, + # reads lines using the default record separator; + # also limits the size (in characters) of each line to the given limit: + # strio = StringIO.new(TEXT) + # strio.each_line(10) {|line| p line } + # + # Output: + # "First line" + # "\n" + # "Second lin" + # "e\n" + # "\n" + # "Fourth lin" + # "e\n" + # "Fifth line" + # "\n" + # + # **Arguments `sep` and `limit`** + # With arguments `sep` and `limit` both given, + # honors both: + # strio = StringIO.new(TEXT) + # strio.each_line(' ', 10) {|line| p line } + # + # Output: + # "First " + # "line\nSecon" + # "d " + # "line\n\nFour" + # "th " + # "line\nFifth" + # " " + # "line\n" + # + # **Position** + # As stated above, method `each` *remaining* line in the stream. + # In the examples above each `strio` object starts with its position at + # beginning-of-stream; + # but in other cases the position may be anywhere (see StringIO#pos): + # strio = StringIO.new(TEXT) + # strio.pos = 30 # Set stream position to character 30. + # strio.each_line {|line| p line } + # + # Output: + # " line\n" + # "Fifth line\n" + # + # In all the examples above, the stream position is at the beginning of a + # character; + # in other cases, that need not be so: + # s = 'こんにちは' # Five 3-byte characters. + # strio = StringIO.new(s) + # strio.pos = 3 # At beginning of second character. + # strio.each_line {|line| p line } + # strio.pos = 4 # At second byte of second character. + # strio.each_line {|line| p line } + # strio.pos = 5 # At third byte of second character. + # strio.each_line {|line| p line } + # + # Output: + # "んにちは" + # "\x82\x93にちは" + # "\x93にちは" + # + # **Special Record Separators** + # Like some methods in class `IO`, StringIO.each honors two special record + # separators; + # see [Special Line + # Separators](https://docs.ruby-lang.org/en/master/IO.html#class-IO-label-Specia + # l+Line+Separator+Values). + # strio = StringIO.new(TEXT) + # strio.each_line('') {|line| p line } # Read as paragraphs (separated by blank lines). + # + # Output: + # "First line\nSecond line\n\n" + # "Fourth line\nFifth line\n" + # + # strio = StringIO.new(TEXT) + # strio.each_line(nil) {|line| p line } # "Slurp"; read it all. + # + # Output: + # "First line\nSecond line\n\nFourth line\nFifth line\n" + # + # **Keyword Argument `chomp`** + # With keyword argument `chomp` given as `true` (the default is `false`), + # removes trailing newline (if any) from each line: + # strio = StringIO.new(TEXT) + # strio.each_line(chomp: true) {|line| p line } + # + # Output: + # "First line" + # "Second line" + # "" + # "Fourth line" + # "Fifth line" + # + # With no block given, returns a new + # [Enumerator](https://docs.ruby-lang.org/en/master/Enumerator.html). + # Related: StringIO.each_byte, StringIO.each_char, StringIO.each_codepoint. # def each: (?String sep, ?Integer limit, ?chomp: boolish) { (String) -> untyped } -> self | (?String sep, ?Integer limit, ?chomp: boolish) -> ::Enumerator[String, self] @@ -394,19 +1015,21 @@ class StringIO # # Returns a byte, not a character: # - # s = 'тест' - # s.bytes # => [209, 130, 208, 181, 209, 129, 209, 130] + # s = 'Привет' + # s.bytes + # # => [208, 159, 209, 128, 208, 184, 208, 178, 208, 181, 209, 130] # strio = StringIO.new(s) - # strio.getbyte # => 209 - # strio.getbyte # => 130 + # strio.getbyte # => 208 + # strio.getbyte # => 159 # # s = 'こんにちは' - # s.bytes # => [227, 129, 147, 227, 130, 147, 227, 129, 171, 227, 129, 161, 227, 129, 175] + # s.bytes + # # => [227, 129, 147, 227, 130, 147, 227, 129, 171, 227, 129, 161, 227, 129, 175] # strio = StringIO.new(s) # strio.getbyte # => 227 # strio.getbyte # => 129 # - # Related: StringIO.getc. + # Related: #each_byte, #ungetbyte, #getc. # def getbyte: () -> Integer? @@ -428,9 +1051,9 @@ class StringIO # # Returns characters, not bytes: # - # strio = StringIO.new('тест') - # strio.getc # => "т" - # strio.getc # => "е" + # strio = StringIO.new('Привет') + # strio.getc # => "П" + # strio.getc # => "р" # # strio = StringIO.new('こんにちは') # strio.getc # => "こ" @@ -447,7 +1070,7 @@ class StringIO # strio.pos = 5 # => 5 # At third byte of second character; returns byte. # strio.getc # => "\x93" # - # Related: StringIO.getbyte. + # Related: #getbyte, #putc, #ungetc. # def getc: () -> String? @@ -477,10 +1100,10 @@ class StringIO # strio.eof? # => true # strio.gets # => nil # - # strio = StringIO.new('тест') # Four 2-byte characters. + # strio = StringIO.new('Привет') # Six 2-byte characters # strio.pos # => 0 - # strio.gets # => "тест" - # strio.pos # => 8 + # strio.gets # => "Привет" + # strio.pos # => 12 # # **Argument `sep`** # @@ -526,11 +1149,11 @@ class StringIO # # The position need not be at a character boundary: # - # strio = StringIO.new('тест') # Four 2-byte characters. - # strio.pos = 2 # At beginning of second character. - # strio.gets # => "ест" - # strio.pos = 3 # In middle of second character. - # strio.gets # => "\xB5ст" + # strio = StringIO.new('Привет') # Six 2-byte characters. + # strio.pos = 2 # At beginning of second character. + # strio.gets # => "ривет" + # strio.pos = 3 # In middle of second character. + # strio.gets # => "\x80ивет" # # **Special Record Separators** # @@ -556,7 +1179,7 @@ class StringIO # strio.gets # => "First line\n" # strio.gets(chomp: true) # => "Second line" # - # Related: StringIO.each_line. + # Related: #each_line, #readlines, [Kernel#puts](rdoc-ref:Kernel#puts). # def gets: (?String sep, ?Integer limit, ?chomp: boolish) -> String? @@ -573,7 +1196,7 @@ class StringIO # - external_encoding -> encoding or nil # --> # Returns an Encoding object that represents the encoding of the string; see - # [Encoding](rdoc-ref:Encoding): + # [Encodings](rdoc-ref:StringIO@Encodings): # # strio = StringIO.new('foo') # strio.external_encoding # => # @@ -598,7 +1221,7 @@ class StringIO # - lineno -> current_line_number # --> # Returns the current line number in `self`; see [Line - # Number](rdoc-ref:IO@Line+Number). + # Number](rdoc-ref:StringIO@Line+Number). # def lineno: () -> Integer @@ -607,7 +1230,7 @@ class StringIO # - lineno = new_line_number -> new_line_number # --> # Sets the current line number in `self` to the given `new_line_number`; see - # [Line Number](rdoc-ref:IO@Line+Number). + # [Line Number](rdoc-ref:StringIO@Line+Number). # def lineno=: (Integer arg0) -> Integer @@ -623,7 +1246,8 @@ class StringIO # rdoc-file=ext/stringio/stringio.c # - pos -> stream_position # --> - # Returns the current position (in bytes); see [Position](rdoc-ref:IO@Position). + # Returns the current position (in bytes); see + # [Position](rdoc-ref:StringIO@Position). # def pos: () -> Integer @@ -631,7 +1255,8 @@ class StringIO # rdoc-file=ext/stringio/stringio.c # - pos = new_position -> new_position # --> - # Sets the current position (in bytes); see [Position](rdoc-ref:IO@Position). + # Sets the current position (in bytes); see + # [Position](rdoc-ref:StringIO@Position). # def pos=: (Integer arg0) -> Integer @@ -779,6 +1404,11 @@ class StringIO # rdoc-file=ext/stringio/stringio.c # - size -> integer # --> + # Returns the number of bytes in the string in `self`: + # + # StringIO.new('hello').size # => 5 # Five 1-byte characters. + # StringIO.new('тест').size # => 8 # Four 2-byte characters. + # StringIO.new('こんにちは').size # => 15 # Five 3-byte characters. # def size: () -> Integer @@ -806,7 +1436,8 @@ class StringIO # rdoc-file=ext/stringio/stringio.c # - pos -> stream_position # --> - # Returns the current position (in bytes); see [Position](rdoc-ref:IO@Position). + # Returns the current position (in bytes); see + # [Position](rdoc-ref:StringIO@Position). # def tell: () -> Integer @@ -868,10 +1499,138 @@ class StringIO def codepoints: () { (Integer arg0) -> untyped } -> self | () -> ::Enumerator[Integer, self] - # + # + # With a block given calls the block with each remaining line (see "Position" + # below) in the stream; + # returns `self`. + # Leaves stream position at end-of-stream. + # **No Arguments** + # With no arguments given, + # reads lines using the default record separator + # (global variable `$/`, whose initial value is `"\n"`). + # strio = StringIO.new(TEXT) + # strio.each_line {|line| p line } + # strio.eof? # => true + # + # Output: + # "First line\n" + # "Second line\n" + # "\n" + # "Fourth line\n" + # "Fifth line\n" + # + # **Argument `sep`** + # With only string argument `sep` given, + # reads lines using that string as the record separator: + # strio = StringIO.new(TEXT) + # strio.each_line(' ') {|line| p line } + # + # Output: + # "First " + # "line\nSecond " + # "line\n\nFourth " + # "line\nFifth " + # "line\n" + # + # **Argument `limit`** + # With only integer argument `limit` given, + # reads lines using the default record separator; + # also limits the size (in characters) of each line to the given limit: + # strio = StringIO.new(TEXT) + # strio.each_line(10) {|line| p line } + # + # Output: + # "First line" + # "\n" + # "Second lin" + # "e\n" + # "\n" + # "Fourth lin" + # "e\n" + # "Fifth line" + # "\n" + # + # **Arguments `sep` and `limit`** + # With arguments `sep` and `limit` both given, + # honors both: + # strio = StringIO.new(TEXT) + # strio.each_line(' ', 10) {|line| p line } + # + # Output: + # "First " + # "line\nSecon" + # "d " + # "line\n\nFour" + # "th " + # "line\nFifth" + # " " + # "line\n" + # + # **Position** + # As stated above, method `each` *remaining* line in the stream. + # In the examples above each `strio` object starts with its position at + # beginning-of-stream; + # but in other cases the position may be anywhere (see StringIO#pos): + # strio = StringIO.new(TEXT) + # strio.pos = 30 # Set stream position to character 30. + # strio.each_line {|line| p line } + # + # Output: + # " line\n" + # "Fifth line\n" + # + # In all the examples above, the stream position is at the beginning of a + # character; + # in other cases, that need not be so: + # s = 'こんにちは' # Five 3-byte characters. + # strio = StringIO.new(s) + # strio.pos = 3 # At beginning of second character. + # strio.each_line {|line| p line } + # strio.pos = 4 # At second byte of second character. + # strio.each_line {|line| p line } + # strio.pos = 5 # At third byte of second character. + # strio.each_line {|line| p line } + # + # Output: + # "んにちは" + # "\x82\x93にちは" + # "\x93にちは" + # + # **Special Record Separators** + # Like some methods in class `IO`, StringIO.each honors two special record + # separators; + # see [Special Line + # Separators](https://docs.ruby-lang.org/en/master/IO.html#class-IO-label-Specia + # l+Line+Separator+Values). + # strio = StringIO.new(TEXT) + # strio.each_line('') {|line| p line } # Read as paragraphs (separated by blank lines). + # + # Output: + # "First line\nSecond line\n\n" + # "Fourth line\nFifth line\n" + # + # strio = StringIO.new(TEXT) + # strio.each_line(nil) {|line| p line } # "Slurp"; read it all. + # + # Output: + # "First line\nSecond line\n\nFourth line\nFifth line\n" + # + # **Keyword Argument `chomp`** + # With keyword argument `chomp` given as `true` (the default is `false`), + # removes trailing newline (if any) from each line: + # strio = StringIO.new(TEXT) + # strio.each_line(chomp: true) {|line| p line } + # + # Output: + # "First line" + # "Second line" + # "" + # "Fourth line" + # "Fifth line" + # + # With no block given, returns a new + # [Enumerator](https://docs.ruby-lang.org/en/master/Enumerator.html). + # Related: StringIO.each_byte, StringIO.each_char, StringIO.each_codepoint. # def each_line: (?String sep, ?Integer limit, ?chomp: boolish) { (String) -> untyped } -> self | (?String sep, ?Integer limit, ?chomp: boolish) -> ::Enumerator[String, self] diff --git a/stdlib/strscan/0/string_scanner.rbs b/stdlib/strscan/0/string_scanner.rbs index 73e490bab..a8e18cf38 100644 --- a/stdlib/strscan/0/string_scanner.rbs +++ b/stdlib/strscan/0/string_scanner.rbs @@ -28,7 +28,7 @@ # * `match_values_cleared?(scanner)`: # Returns whether the scanner's [match # values](rdoc-ref:StringScanner@Match+Values) are cleared. -# See examples at [helper methods](doc/strscan/helper_methods.md). +# See examples at [helper methods](helper_methods.md). # ## The `StringScanner` Object # This code creates a `StringScanner` object # (we'll call it simply a *scanner*), diff --git a/stdlib/tempfile/0/tempfile.rbs b/stdlib/tempfile/0/tempfile.rbs index 10751677b..bb481a425 100644 --- a/stdlib/tempfile/0/tempfile.rbs +++ b/stdlib/tempfile/0/tempfile.rbs @@ -248,8 +248,8 @@ class Tempfile < File # # Implementation note: # - # The keyword argument +anonymous=true+ is implemented using FILE_SHARE_DELETE - # on Windows. O_TMPFILE is used on Linux. + # The keyword argument `anonymous=true` is implemented using `FILE_SHARE_DELETE` + # on Windows. `O_TMPFILE` is used on Linux. # # Related: Tempfile.new. # diff --git a/stdlib/time/0/time.rbs b/stdlib/time/0/time.rbs index c18599fa5..9c30929f9 100644 --- a/stdlib/time/0/time.rbs +++ b/stdlib/time/0/time.rbs @@ -10,7 +10,7 @@ class Time # # Return the number of seconds the specified time zone differs from UTC. # diff --git a/stdlib/timeout/0/timeout.rbs b/stdlib/timeout/0/timeout.rbs index 997fad2bd..190d48fb5 100644 --- a/stdlib/timeout/0/timeout.rbs +++ b/stdlib/timeout/0/timeout.rbs @@ -26,7 +26,7 @@ module Timeout # rdoc-file=lib/timeout.rb # - timeout(sec, klass = nil, message = nil) { |sec| ... } # --> - # Perform an operation in a block, raising an error if it takes longer than + # Perform an operation in a block, raising an exception if it takes longer than # `sec` seconds to complete. # # `sec` @@ -45,12 +45,20 @@ module Timeout # # # Returns the result of the block **if** the block completed before `sec` - # seconds, otherwise throws an exception, based on the value of `klass`. + # seconds, otherwise raises an exception, based on the value of `klass`. # - # The exception thrown to terminate the given block cannot be rescued inside the - # block unless `klass` is given explicitly. However, the block can use ensure to - # prevent the handling of the exception. For that reason, this method cannot be - # relied on to enforce timeouts for untrusted blocks. + # The exception raised to terminate the given block is the given `klass`, or + # Timeout::ExitException if `klass` is not given. The reason for that behavior + # is that Timeout::Error inherits from RuntimeError and might be caught + # unexpectedly by `rescue`. Timeout::ExitException inherits from Exception so it + # will only be rescued by `rescue Exception`. Note that the + # Timeout::ExitException is translated to a Timeout::Error once it reaches the + # Timeout.timeout call, so outside that call it will be a Timeout::Error. + # + # In general, be aware that the code block may rescue the exception, and in such + # a case not respect the timeout. Also, the block can use `ensure` to prevent + # the handling of the exception. For those reasons, this method cannot be relied + # on to enforce timeouts for untrusted blocks. # # If a scheduler is defined, it will be used to handle the timeout by invoking # Scheduler#timeout_after. @@ -59,11 +67,59 @@ module Timeout # Timeout` into your classes so they have a #timeout method, as well as a module # method, so you can call it directly as Timeout.timeout(). # + # #### Ensuring the exception does not fire inside ensure blocks + # + # When using Timeout.timeout it can be desirable to ensure the timeout exception + # does not fire inside an `ensure` block. The simplest and best way to do so it + # to put the Timeout.timeout call inside the body of the begin/ensure/end: + # + # begin + # Timeout.timeout(sec) { some_long_operation } + # ensure + # cleanup # safe, cannot be interrupt by timeout + # end + # + # If that is not feasible, e.g. if there are `ensure` blocks inside + # `some_long_operation`, they need to not be interrupted by timeout, and it's + # not possible to move these ensure blocks outside, one can use + # Thread.handle_interrupt to delay the timeout exception like so: + # + # Thread.handle_interrupt(Timeout::Error => :never) { + # Timeout.timeout(sec, Timeout::Error) do + # setup # timeout cannot happen here, no matter how long it takes + # Thread.handle_interrupt(Timeout::Error => :immediate) { + # some_long_operation # timeout can happen here + # } + # ensure + # cleanup # timeout cannot happen here, no matter how long it takes + # end + # } + # + # An important thing to note is the need to pass an exception klass to + # Timeout.timeout, otherwise it does not work. Specifically, using + # +Thread.handle_interrupt(Timeout::ExitException => ...)+ is unsupported and + # causes subtle errors like raising the wrong exception outside the block, do + # not use that. + # + # Note that Thread.handle_interrupt is somewhat dangerous because if setup or + # cleanup hangs then the current thread will hang too and the timeout will never + # fire. Also note the block might run for longer than `sec` seconds: e.g. + # some_long_operation executes for `sec` seconds + whatever time cleanup takes. + # + # If you want the timeout to only happen on blocking operations one can use + # :on_blocking instead of :immediate. However, that means if the block uses no + # blocking operations after `sec` seconds, the block will not be interrupted. + # ---- + # + # def self?.timeout: [T] (Numeric? sec, ?singleton(Exception) klass, ?String message) { (Numeric sec) -> T } -> T end # -# Internal error raised to when a timeout is triggered. +# Internal exception raised to when a timeout is triggered. # class Timeout::ExitException < Exception end diff --git a/stdlib/uri/0/generic.rbs b/stdlib/uri/0/generic.rbs index 328f4e4dc..77d88d0a2 100644 --- a/stdlib/uri/0/generic.rbs +++ b/stdlib/uri/0/generic.rbs @@ -424,7 +424,7 @@ module URI # # uri = URI.parse("http://john:S3nsit1ve@my.example.com") # uri.user = "sam" - # uri.to_s #=> "http://sam:V3ry_S3nsit1ve@my.example.com" + # uri.to_s #=> "http://sam@my.example.com" # def user=: (String? user) -> String?