From: Paul Eggert <eggert@cs.ucla.edu>
To: Drew Adams <drew.adams@oracle.com>
Cc: Noam Postavsky <npostavs@gmail.com>, 39557@debbugs.gnu.org
Subject: bug#39557: 27.0.60; Elisp manual, doc about bignums
Date: Mon, 17 Feb 2020 14:05:38 -0800 [thread overview]
Message-ID: <8c6ed478-db97-8abc-de79-f5c10498ad0c@cs.ucla.edu> (raw)
In-Reply-To: <3d420026-bb32-413f-9a9c-304240aa82e2@default>
[-- Attachment #1: Type: text/plain, Size: 1426 bytes --]
> That's really the _last_ thing we should tell users, not the first.
I installed the first attached patch to move the distinction between fixnums and
bignums to the end of the section.
> Shouldn't it tell you that you get a fixnum whenever the value
> is within the fixnum range (if that's in fact the case)?
It already said that, but apparently not clearly enough. I installed the second
attached patch to try to make things clearer.
> this doc should probably also mention that the numerical value of
> a marker is an integer
It already says "Many of the functions described in this chapter accept markers
for arguments in place of numbers.... When the argument value is a marker, its
position value is used and its buffer is ignored."
> if you compare an integer
> against an integer numeral then you had better use
> `eql', unless you know that both are fixnums
No, it suffices if *either* is a fixnum. For example, (eq 0 FOO) tests whether
FOO is the integer zero, and works regardless of whether FOO is a bignum.
> I'm really surprised this doc got inserted as it is.
I'm not surprised at all. The doc was an improvement over its predecessor, we're
all busy doing other things, and the issues raised in this bug report are low
priority.
If you're still dissatisfied with the manual, I suggest proposing specific
wording changes so that future fixes in this area can be accomplished more
efficiently.
[-- Attachment #2: 0001-Reorder-discussion-of-integer-basics.patch --]
[-- Type: text/x-patch, Size: 4341 bytes --]
From 290cfbedd75764ab863677f63f66db13ceb70598 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Mon, 17 Feb 2020 13:36:50 -0800
Subject: [PATCH 1/2] Reorder discussion of integer basics
* doc/lispref/numbers.texi (Integer Basics): Put the fixnum/bignum
discussion at the end of the section, not at the start (Bug#39557).
---
doc/lispref/numbers.texi | 77 +++++++++++++++++++++-------------------
1 file changed, 40 insertions(+), 37 deletions(-)
diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi
index c8941eab73..4b9fdf2420 100644
--- a/doc/lispref/numbers.texi
+++ b/doc/lispref/numbers.texi
@@ -34,39 +34,6 @@ Numbers
@node Integer Basics
@section Integer Basics
- Integers in Emacs Lisp are not limited to the machine word size.
-
- Under the hood, though, there are two kinds of integers: smaller
-ones, called @dfn{fixnums}, and larger ones, called @dfn{bignums}.
-Some functions in Emacs accept only fixnums. Also, while fixnums can
-be compared for numeric equality with @code{eq}, bignums require
-more-heavyweight equality predicates like @code{eql} and @code{=}.
-
- The range of values for bignums is limited by the amount of main
-memory, by machine characteristics such as the size of the word used
-to represent a bignum's exponent, and by the @code{integer-width}
-variable. These limits are typically much more generous than the
-limits for fixnums. A bignum is never numerically equal to a fixnum;
-if Emacs computes an integer in fixnum range, it represents the
-integer as a fixnum, not a bignum.
-
- The range of values for a fixnum depends on the machine. The
-minimum range is @minus{}536,870,912 to 536,870,911 (30 bits; i.e.,
-@ifnottex
-@minus{}2**29
-@end ifnottex
-@tex
-@math{-2^{29}}
-@end tex
-to
-@ifnottex
-2**29 @minus{} 1),
-@end ifnottex
-@tex
-@math{2^{29}-1}),
-@end tex
-but many machines provide a wider range.
-
The Lisp reader reads an integer as a nonempty sequence
of decimal digits with optional initial sign and optional
final period.
@@ -145,6 +112,46 @@ Integer Basics
give these arguments the name @var{number-or-marker}. When the argument
value is a marker, its position value is used and its buffer is ignored.
+ In Emacs Lisp, text characters are represented by integers. Any
+integer between zero and the value of @code{(max-char)}, inclusive, is
+considered to be valid as a character. @xref{Character Codes}.
+
+ Integers in Emacs Lisp are not limited to the machine word size.
+Under the hood, though, there are two kinds of integers: smaller ones,
+called @dfn{fixnums}, and larger ones, called @dfn{bignums}. Although
+Emacs Lisp code ordinarily should not depend on whether an integer is
+a fixnum or a bignum, older Emacs versions support only fixnums, some
+functions in Emacs still accept only fixnums, and older Emacs Lisp
+code may have trouble when given bignums. For example, while older
+Emacs Lisp code could safely compare integers for numeric equality
+with @code{eq}, the presence of bignums means that equality predicates
+like @code{eql} and @code{=} should now be used to compare integers.
+
+ The range of values for bignums is limited by the amount of main
+memory, by machine characteristics such as the size of the word used
+to represent a bignum's exponent, and by the @code{integer-width}
+variable. These limits are typically much more generous than the
+limits for fixnums. A bignum is never numerically equal to a fixnum;
+if Emacs computes an integer in fixnum range, it represents the
+integer as a fixnum, not a bignum.
+
+ The range of values for a fixnum depends on the machine. The
+minimum range is @minus{}536,870,912 to 536,870,911 (30 bits; i.e.,
+@ifnottex
+@minus{}2**29
+@end ifnottex
+@tex
+@math{-2^{29}}
+@end tex
+to
+@ifnottex
+2**29 @minus{} 1),
+@end ifnottex
+@tex
+@math{2^{29}-1}),
+@end tex
+but many machines provide a wider range.
+
@cindex largest fixnum
@cindex maximum fixnum
@defvar most-positive-fixnum
@@ -207,10 +214,6 @@ Integer Basics
creates huge integers.
@end defvar
- In Emacs Lisp, text characters are represented by integers. Any
-integer between zero and the value of @code{(max-char)}, inclusive, is
-considered to be valid as a character. @xref{Character Codes}.
-
@node Float Basics
@section Floating-Point Basics
--
2.17.1
[-- Attachment #3: 0002-Clarify-when-fixnums-are-used.patch --]
[-- Type: text/x-patch, Size: 1132 bytes --]
From 8593d449972ad2bac850c03839653223d402a682 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Mon, 17 Feb 2020 13:54:07 -0800
Subject: [PATCH 2/2] Clarify when fixnums are used.
* doc/lispref/numbers.texi (Integer Basics): Clarify.
Based on a suggestion by Noam Postavsky (Bug#39557#32).
---
doc/lispref/numbers.texi | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi
index 4b9fdf2420..4002b36ce5 100644
--- a/doc/lispref/numbers.texi
+++ b/doc/lispref/numbers.texi
@@ -132,8 +132,8 @@ Integer Basics
to represent a bignum's exponent, and by the @code{integer-width}
variable. These limits are typically much more generous than the
limits for fixnums. A bignum is never numerically equal to a fixnum;
-if Emacs computes an integer in fixnum range, it represents the
-integer as a fixnum, not a bignum.
+Emacs always represents an integer in fixnum range as a fixnum, not a
+bignum.
The range of values for a fixnum depends on the machine. The
minimum range is @minus{}536,870,912 to 536,870,911 (30 bits; i.e.,
--
2.17.1
next prev parent reply other threads:[~2020-02-17 22:05 UTC|newest]
Thread overview: 18+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-02-10 23:55 bug#39557: 27.0.60; Elisp manual, doc about bignums Drew Adams
2020-02-11 17:01 ` Eli Zaretskii
2020-02-11 21:46 ` Noam Postavsky
2020-02-11 22:34 ` Drew Adams
2020-02-12 15:53 ` Noam Postavsky
2020-02-12 21:36 ` Drew Adams
2020-02-13 18:23 ` Noam Postavsky
2020-02-13 21:03 ` Drew Adams
2020-02-12 20:06 ` Richard Stallman
2020-02-13 23:43 ` Richard Stallman
2020-02-17 22:05 ` Paul Eggert [this message]
2020-02-17 23:19 ` Drew Adams
2020-02-17 23:52 ` Paul Eggert
2020-02-18 1:52 ` Drew Adams
2020-02-18 3:13 ` Paul Eggert
2020-09-25 11:18 ` Lars Ingebrigtsen
[not found] <<3d420026-bb32-413f-9a9c-304240aa82e2@default>
[not found] ` <<8336bhrrb4.fsf@gnu.org>
2020-02-11 18:26 ` Drew Adams
2020-02-11 19:14 ` Eli Zaretskii
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=8c6ed478-db97-8abc-de79-f5c10498ad0c@cs.ucla.edu \
--to=eggert@cs.ucla.edu \
--cc=39557@debbugs.gnu.org \
--cc=drew.adams@oracle.com \
--cc=npostavs@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.