Bug #13251: [DOC] Add rdoc for Integer.sqrt

• Status: Closed
• Assignee: stomar (Marcus Stollsteimer)
• Target version: -
• ruby -v: ruby 2.5.0dev (2017-02-24 trunk 57707) [x86_64-linux]
• Backport: 2.2: DONTNEED, 2.3: DONTNEED, 2.4: DONTNEED

[stomar (Marcus Stollsteimer)]

Nobu, I would offer to add documentation for Integer.sqrt, feature #13219 (r57705).

I'd like to prepare a patch and eventually try to commit it myself.

I'm not sure yet when to open issues for documentation and when to simply commit; I would be glad about any feedback.

[nobu (Nobuyoshi Nakada)]

• Status changed from Open to Assigned
• Backport changed from 2.2: UNKNOWN, 2.3: UNKNOWN, 2.4: UNKNOWN to 2.2: DONTNEED, 2.3: DONTNEED, 2.4: DONTNEED

Thank you, feel free to add it.

I was writing it too, but you'll make better one.
This is my draft, FYI.

diff --git c/NEWS i/NEWS
index 2a0413f006..8647e5e2ce 100644
--- c/NEWS
+++ i/NEWS
@@ -21,4 +21,8 @@ with all sufficient information, see the ChangeLog file or Redmine
 === Core classes updates (outstanding ones only)
 
+* Integer
+
+  * Integer.sqrt  [Feature #13219]
+
 * Regexp
   * Update Onigmo 6.1.1.
	Modified   numeric.c
diff --git c/numeric.c i/numeric.c
index b34fb0a5f9..c827a8c7c9 100644
--- c/numeric.c
+++ i/numeric.c
@@ -5155,4 +5155,22 @@ DEFINE_INT_SQRT(BDIGIT, rb_bdigit_dbl, BDIGIT_DBL)
 VALUE rb_big_isqrt(VALUE);
 
+/*
+ *  call-seq:
+ *     Integer.sqrt(x)  ->  Integer
+ *
+ *  Returns the largest integer which does not exceed the non-negative
+ *  square root of _x_.  Equivalent to `Math.sqrt(x).floor`, except
+ *  for that the result of the latter code may be greater than the
+ *  true root when _x_ exceeds the Float precision.
+ *
+ *  If _x_ is not an Integer, it is converted to an Integer first.
+ *  If _x_ is negative, a Math::DomainError is raised, as well as
+ *  Math.sqrt.
+ *
+ *     Integer.sqrt(0)        #=> 0
+ *     Integer.sqrt(1)        #=> 1
+ *     Integer.sqrt(10)       #=> 3
+ *     Integer.sqrt(10**400)  #=> 10**200
+ */
 static VALUE
 rb_int_s_isqrt(VALUE self, VALUE num)

[stomar (Marcus Stollsteimer)]

Two clarifying questions:

Is it confirmed that using Floats will only give wrong results that are too large? Update: no, too small also occurs.

See e.g. the case of cube roots:

64 ** (1.0/3)         # => 3.9999999999999996
(64 ** (1.0/3)).to_i  # => 3

I didn't find (small) examples for sqrt similiar to this (yet?), but maybe they exist.

Does Float behave the same on all platforms and architectures?
Update: judging from the docs for Float constants (e.g. Float::DIG), there might be differences; typical formulation: "Usually defaults to ...".

[stomar (Marcus Stollsteimer)]

FYI, here my suggestion (will commit soon, but need to read some HowTo's on how exactly that works, first):

diff --git a/numeric.c b/numeric.c
index b34fb0a..2400a9c 100644
--- a/numeric.c
+++ b/numeric.c
@@ -5154,6 +5154,32 @@ DEFINE_INT_SQRT(BDIGIT, rb_bdigit_dbl, BDIGIT_DBL)
 
 VALUE rb_big_isqrt(VALUE);
 
+/*
+ *  Document-method: Integer::sqrt
+ *  call-seq:
+ *     Integer.sqrt(n)  ->  integer
+ *
+ *  Returns the integer square root of the non-negative integer +n+,
+ *  i.e. the largest non-negative integer less than or equal to the
+ *  square root of +n+.
+ *
+ *    Integer.sqrt(0)        #=> 0
+ *    Integer.sqrt(1)        #=> 1
+ *    Integer.sqrt(24)       #=> 4
+ *    Integer.sqrt(25)       #=> 5
+ *    Integer.sqrt(10**400)  #=> 10**200
+ *
+ *  Equivalent to <code>Math.sqrt(n).floor</code>, except that the
+ *  result of the latter code may differ from the true value
+ *  due to the limited precision of floating point arithmetic.
+ *
+ *    Integer.sqrt(10**46)    #=> 100000000000000000000000
+ *    Math.sqrt(10**46).to_i  #=>  99999999999999991611392 (!)
+ *
+ *  If +n+ is not an Integer, it is converted to an Integer first.
+ *  If +n+ is negative, a Math::DomainError is raised.
+ */
+
 static VALUE
 rb_int_s_isqrt(VALUE self, VALUE num)
 {

[nobu (Nobuyoshi Nakada)]

Argument names should be marked up using +arg+, or _arg_?
Although I've thought it would be _ and there are such usage, + seems major?

[stomar (Marcus Stollsteimer)]

For the specific patch I tried to follow the style in the current file. Generally, I see both, and it seems + is more common than _ (see e.g. Array).

Are there any agreed upon guidelines on documentation style? There are hints regarding coding style in the Wiki, but I couldn't find any for documentation.

[nobu (Nobuyoshi Nakada)]

I see, the usage is another issue in any rate.
The doc seems nice, thank you.

[stomar (Marcus Stollsteimer)]

• Status changed from Assigned to Closed

Applied in changeset r57719.

---

Add rdoc for Integer.sqrt

• numeric.c (rb_int_s_isqrt): [DOC] add rdoc for Integer.sqrt.
  [ruby-core:79762] [Bug #13251]

[stomar (Marcus Stollsteimer)]

Yay, first commit...!

nobu, thanks for your patience; please give feedback if I should have done anything differently.