rbs 3.7.0 → 3.8.0.pre.1

data/core/integer.rbs

@@ -5,12 +5,10 @@
 #
 # *   An [integer literal](rdoc-ref:syntax/literals.rdoc@Integer+Literals).
 #
-#
 # You can convert certain objects to Integers with:
 #
 # *   Method #Integer.
 #
-#
 # An attempt to add a singleton method to an instance of this class causes an
 # exception to be raised.
 #
@@ -18,8 +16,9 @@
 #
 # First, what's elsewhere. Class Integer:
 #
-# *   Inherits from [class Numeric](rdoc-ref:Numeric@What-27s+Here).
-#
+# *   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 Integer provides methods for:
 #
@@ -28,14 +27,12 @@
 # *   [Converting](rdoc-ref:Integer@Converting)
 # *   [Other](rdoc-ref:Integer@Other)
 #
-#
 # ### Querying
 #
 # *   #allbits?: Returns whether all bits in `self` are set.
 # *   #anybits?: Returns whether any bits in `self` are set.
 # *   #nobits?: Returns whether no bits in `self` are set.
 #
-#
 # ### Comparing
 #
 # *   #<: Returns whether `self` is less than the given value.
@@ -48,7 +45,6 @@
 # *   #>: Returns whether `self` is greater than the given value.
 # *   #>=: Returns whether `self` is greater than or equal to the given value.
 #
-#
 # ### Converting
 #
 # *   ::sqrt: Returns the integer square root of the given value.
@@ -64,6 +60,7 @@
 # *   #>>: Returns the value of `self` after a rightward bit-shift.
 # *   #[]: Returns a slice of bits from `self`.
 # *   #^: Returns the bitwise EXCLUSIVE OR of `self` and the given value.
+# *   #|: Returns the bitwise OR of `self` and the given value.
 # *   #ceil: Returns the smallest number greater than or equal to `self`.
 # *   #chr: Returns a 1-character string containing the character represented by
 #     the value of `self`.
@@ -85,8 +82,6 @@
 # *   #to_s (aliased as #inspect): Returns a string containing the place-value
 #     representation of `self` in the given radix.
 # *   #truncate: Returns `self` truncated to the given precision.
-# *   #|: Returns the bitwise OR of `self` and the given value.
-#
 #
 # ### Other
 #
@@ -362,7 +357,6 @@ class Integer < Numeric
   # *   1, if `self` is greater then `other`.
   # *   `nil`, if `self` and `other` are incomparable.
   #
-  #
   # Examples:
   #
   #     1 <=> 2              # => -1
@@ -620,22 +614,40 @@ class Integer < Numeric
   #   rdoc-file=numeric.c
   #   - ceil(ndigits = 0) -> integer
   # -->
-  # Returns the smallest number greater than or equal to `self` with a precision
-  # of `ndigits` decimal digits.
-  #
-  # When the precision is negative, the returned value is an integer with at least
-  # `ndigits.abs` trailing zeros:
-  #
-  #     555.ceil(-1)  # => 560
-  #     555.ceil(-2)  # => 600
-  #     -555.ceil(-2) # => -500
-  #     555.ceil(-3)  # => 1000
-  #
-  # Returns `self` when `ndigits` is zero or positive.
-  #
-  #     555.ceil     # => 555
-  #     555.ceil(50) # => 555
-  #
+  # Returns an integer that is a "ceiling" value for `self`,
+  # as specified by the given `ndigits`,
+  # which must be an
+  # [integer-convertible
+  # object](rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects).
+  # *   When `self` is zero, returns zero (regardless of the value of `ndigits`):
+  #         0.ceil(2)  # => 0
+  # 0.ceil(-2) # => 0
+  #
+  # *   When `self` is non-zero and `ndigits` is non-negative, returns `self`:
+  #         555.ceil     # => 555
+  # 555.ceil(50) # => 555
+  #
+  # *   When `self` is non-zero and `ndigits` is negative,
+  #      returns a value based on a computed granularity:
+  #     *   The granularity is `10 ** ndigits.abs`.
+  #     *   The returned value is the smallest multiple of the granularity
+  #          that is greater than or equal to `self`.
+  #     Examples with positive `self`:
+  # ndigits|Granularity|1234.ceil(ndigits)
+  # -------|-----------|------------------
+  #      -1|         10|              1240
+  #      -2|        100|              1300
+  #      -3|       1000|              2000
+  #      -4|      10000|             10000
+  #      -5|     100000|            100000
+  #     Examples with negative `self`:
+  # ndigits|Granularity|-1234.ceil(ndigits)
+  # -------|-----------|-------------------
+  #      -1|         10|              -1230
+  #      -2|        100|              -1200
+  #      -3|       1000|              -1000
+  #      -4|      10000|                  0
+  #      -5|     100000|                  0
   # Related: Integer#floor.
   #
   def ceil: () -> Integer
@@ -728,14 +740,14 @@ class Integer < Numeric
   # Performs integer division; returns the integer result of dividing `self` by
   # `numeric`:
   #
-  #       4.div(3)      # => 1
-  #       4.div(-3)      # => -2
-  #       -4.div(3)      # => -2
-  #       -4.div(-3)      # => 1
-  #       4.div(3.0)      # => 1
-  #       4.div(Rational(3, 1))      # => 1
+  #     4.div(3)              # => 1
+  #     4.div(-3)             # => -2
+  #     -4.div(3)             # => -2
+  #     -4.div(-3)            # => 1
+  #     4.div(3.0)            # => 1
+  #     4.div(Rational(3, 1)) # => 1
   #
-  #     Raises an exception if +numeric+ does not have method +div+.
+  # Raises an exception if `numeric` does not have method `div`.
   #
   def div: (Numeric) -> Integer
 
@@ -823,22 +835,40 @@ class Integer < Numeric
   #   rdoc-file=numeric.c
   #   - floor(ndigits = 0) -> integer
   # -->
-  # Returns the largest number less than or equal to `self` with a precision of
-  # `ndigits` decimal digits.
-  #
-  # When `ndigits` is negative, the returned value has at least `ndigits.abs`
-  # trailing zeros:
-  #
-  #     555.floor(-1)  # => 550
-  #     555.floor(-2)  # => 500
-  #     -555.floor(-2) # => -600
-  #     555.floor(-3)  # => 0
-  #
-  # Returns `self` when `ndigits` is zero or positive.
-  #
-  #     555.floor     # => 555
-  #     555.floor(50) # => 555
-  #
+  # Returns an integer that is a "floor" value for `self`,
+  # as specified by the given `ndigits`,
+  # which must be an
+  # [integer-convertible
+  # object](rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects).
+  # *   When `self` is zero, returns zero (regardless of the value of `ndigits`):
+  #         0.floor(2)  # => 0
+  # 0.floor(-2) # => 0
+  #
+  # *   When `self` is non-zero and `ndigits` is non-negative, returns `self`:
+  #         555.floor     # => 555
+  # 555.floor(50) # => 555
+  #
+  # *   When `self` is non-zero and `ndigits` is negative,
+  #      returns a value based on a computed granularity:
+  #     *   The granularity is `10 ** ndigits.abs`.
+  #     *   The returned value is the largest multiple of the granularity
+  #          that is less than or equal to `self`.
+  #     Examples with positive `self`:
+  # ndigits|Granularity|1234.floor(ndigits)
+  # -------|-----------|-------------------
+  #      -1|         10|               1230
+  #      -2|        100|               1200
+  #      -3|       1000|               1000
+  #      -4|      10000|                  0
+  #      -5|     100000|                  0
+  #     Examples with negative `self`:
+  # ndigits|Granularity|-1234.floor(ndigits)
+  # -------|-----------|--------------------
+  #      -1|         10|               -1240
+  #      -2|        100|               -1300
+  #      -3|       1000|               -2000
+  #      -4|      10000|              -10000
+  #      -5|     100000|             -100000
   # Related: Integer#ceil.
   #
   def floor: (?int digits) -> Integer
@@ -1136,7 +1166,6 @@ class Integer < Numeric
   #         15.round(-1, half: :even)    # => 20
   #         (-25).round(-1, half: :even) # => -20
   #
-  #
   # Raises and exception if the value for `half` is invalid.
   #
   # Related: Integer#truncate.

data/core/io/buffer.rbs

@@ -15,7 +15,6 @@ class IO
   # *   Create a string of a fixed size with ::string, then #read into it, or
   #     modify it using #set_value.
   #
-  #
   # Interaction with string and file memory is performed by efficient low-level C
   # mechanisms like `memcpy`.
   #
@@ -42,30 +41,28 @@ class IO
   #
   # Buffer from string:
   #
-  #     string = 'buffer'
-  #     buffer = IO::Buffer.for(string)
-  #     # =>
-  #     # #<IO::Buffer 0x00007f3f02be9b18+4 SLICE>
-  #     # ...
-  #     buffer
-  #     # =>
-  #     # #<IO::Buffer 0x00007f3f02be9b18+4 SLICE>
-  #     # 0x00000000  64 61 74 61                                     buffer
+  #     string = 'data'
+  #     IO::Buffer.for(string) do |buffer|
+  #       buffer
+  #       # =>
+  #       # #<IO::Buffer 0x00007f3f02be9b18+4 SLICE>
+  #       # 0x00000000  64 61 74 61                                     data
   #
-  #     buffer.get_string(2)  # read content starting from offset 2
-  #     # => "ta"
-  #     buffer.set_string('---', 1) # write content, starting from offset 1
-  #     # => 3
-  #     buffer
-  #     # =>
-  #     # #<IO::Buffer 0x00007f3f02be9b18+4 SLICE>
-  #     # 0x00000000  64 2d 2d 2d                                     d---
-  #     string  # original string changed, too
-  #     # => "d---"
+  #       buffer.get_string(2)  # read content starting from offset 2
+  #       # => "ta"
+  #       buffer.set_string('---', 1) # write content, starting from offset 1
+  #       # => 3
+  #       buffer
+  #       # =>
+  #       # #<IO::Buffer 0x00007f3f02be9b18+4 SLICE>
+  #       # 0x00000000  64 2d 2d 2d                                     d---
+  #       string  # original string changed, too
+  #       # => "d---"
+  #     end
   #
   # Buffer from file:
   #
-  #     File.write('test.txt', 'test buffer')
+  #     File.write('test.txt', 'test data')
   #     # => 9
   #     buffer = IO::Buffer.map(File.open('test.txt'))
   #     # =>
@@ -82,7 +79,7 @@ class IO
   #     buffer.set_string('---', 1)
   #     # => 3 -- bytes written
   #     File.read('test.txt')
-  #     # => "t--- buffer"
+  #     # => "t--- data"
   #
   # **The class is experimental and the interface is subject to change, this is
   # especially true of file mappings which may be removed entirely in the
@@ -199,29 +196,29 @@ class IO
     # -->
     # Fill buffer with `value`, starting with `offset` and going for `length` bytes.
     #
-    #     buffer = IO::Buffer.for('test')
+    #     buffer = IO::Buffer.for('test').dup
     #     # =>
-    #     #   <IO::Buffer 0x00007fca40087c38+4 SLICE>
+    #     #   <IO::Buffer 0x00007fca40087c38+4 INTERNAL>
     #     #   0x00000000  74 65 73 74         test
     #
     #     buffer.clear
     #     # =>
-    #     #   <IO::Buffer 0x00007fca40087c38+4 SLICE>
+    #     #   <IO::Buffer 0x00007fca40087c38+4 INTERNAL>
     #     #   0x00000000  00 00 00 00         ....
     #
     #     buf.clear(1) # fill with 1
     #     # =>
-    #     #   <IO::Buffer 0x00007fca40087c38+4 SLICE>
+    #     #   <IO::Buffer 0x00007fca40087c38+4 INTERNAL>
     #     #   0x00000000  01 01 01 01         ....
     #
     #     buffer.clear(2, 1, 2) # fill with 2, starting from offset 1, for 2 bytes
     #     # =>
-    #     #   <IO::Buffer 0x00007fca40087c38+4 SLICE>
+    #     #   <IO::Buffer 0x00007fca40087c38+4 INTERNAL>
     #     #   0x00000000  01 02 02 01         ....
     #
     #     buffer.clear(2, 1) # fill with 2, starting from offset 1
     #     # =>
-    #     #   <IO::Buffer 0x00007fca40087c38+4 SLICE>
+    #     #   <IO::Buffer 0x00007fca40087c38+4 INTERNAL>
     #     #   0x00000000  01 02 02 02         ....
     #
     def clear: (?Integer value, ?Integer offset, ?Integer length) -> self
@@ -231,7 +228,7 @@ class IO
     #   - copy(source, [offset, [length, [source_offset]]]) -> size
     # -->
     # Efficiently copy from a source IO::Buffer into the buffer, at `offset` using
-    # `memcpy`. For copying String instances, see #set_string.
+    # `memmove`. For copying String instances, see #set_string.
     #
     #     buffer = IO::Buffer.new(32)
     #     # =>
@@ -249,13 +246,14 @@ class IO
     #
     # #copy can be used to put buffer into strings associated with buffer:
     #
-    #     string= "buffer:    "
-    #     # => "buffer:    "
-    #     buffer = IO::Buffer.for(string)
-    #     buffer.copy(IO::Buffer.for("test"), 5)
+    #     string = "data:    "
+    #     # => "data:    "
+    #     buffer = IO::Buffer.for(string) do |buffer|
+    #       buffer.copy(IO::Buffer.for("test"), 5)
+    #     end
     #     # => 4
     #     string
-    #     # => "buffer:test"
+    #     # => "data:test"
     #
     # Attempt to copy into a read-only buffer will fail:
     #
@@ -279,6 +277,20 @@ class IO
     #     buffer.copy(IO::Buffer.for('test'), 0)
     #     # in `copy': Specified offset+length is bigger than the buffer size! (ArgumentError)
     #
+    # It is safe to copy between memory regions that overlaps each other. In such
+    # case, the data is copied as if the data was first copied from the source
+    # buffer to a temporary buffer, and then copied from the temporary buffer to the
+    # destination buffer.
+    #
+    #     buffer = IO::Buffer.new(10)
+    #     buffer.set_string("0123456789")
+    #     buffer.copy(buffer, 3, 7)
+    #     # => 7
+    #     buffer
+    #     # =>
+    #     # #<IO::Buffer 0x000056494f8ce440+10 INTERNAL>
+    #     # 0x00000000  30 31 32 30 31 32 33 34 35 36                   0120123456
+    #
     def copy: (Buffer source, ?Integer offset, ?Integer length, ?Integer source_offset) -> Integer
 
     # <!--
@@ -313,7 +325,6 @@ class IO
     # *   for a buffer created from scratch: free memory.
     # *   for a buffer created from string: undo the association.
     #
-    #
     # After the buffer is freed, no further operations can't be performed on it.
     #
     # You can resize a freed buffer to re-allocate it.
@@ -376,7 +387,6 @@ class IO
     # *   `:f64`: double, 8 bytes, little-endian
     # *   `:F64`: double, 8 bytes, big-endian
     #
-    #
     # A buffer type refers specifically to the type of binary buffer that is stored
     # in the buffer. For example, a `:u32` buffer type is a 32-bit unsigned integer
     # in little-endian format.
@@ -654,7 +664,7 @@ class IO
     #   - set_string(string, [offset, [length, [source_offset]]]) -> size
     # -->
     # Efficiently copy from a source String into the buffer, at `offset` using
-    # `memcpy`.
+    # `memmove`.
     #
     #     buf = IO::Buffer.new(8)
     #     # =>
@@ -739,7 +749,7 @@ class IO
     # bounds.
     #
     #     string = 'test'
-    #     buffer = IO::Buffer.for(string)
+    #     buffer = IO::Buffer.for(string).dup
     #
     #     slice = buffer.slice
     #     # =>
@@ -766,13 +776,9 @@ class IO
     #     # it is also visible at position 1 of the original buffer
     #     buffer
     #     # =>
-    #     # #<IO::Buffer 0x00007fc3d31e2d80+4 SLICE>
+    #     # #<IO::Buffer 0x00007fc3d31e2d80+4 INTERNAL>
     #     # 0x00000000  74 6f 73 74                                     tost
     #
-    #     # ...and original string
-    #     string
-    #     # => tost
-    #
     def slice: (Integer offset, Integer length) -> Buffer
 
     # <!--