unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
* bug#39557: 27.0.60; Elisp manual, doc about bignums
@ 2020-02-10 23:55 Drew Adams
  2020-02-11 17:01 ` Eli Zaretskii
  2020-02-17 22:05 ` Paul Eggert
  0 siblings, 2 replies; 18+ messages in thread
From: Drew Adams @ 2020-02-10 23:55 UTC (permalink / raw)
  To: 39557

The Elisp manual's presentation of fixnums and bignums could be
improved.  It should say something similar to what the Common Lisp
manual says:

  Common Lisp is designed to hide this distinction as much as possible;
  the distinction between fixnums and bignums is visible to the user in
  only a few places where the efficiency of representation is important.
  Exactly which integers are fixnums is implementation-dependent;
  typically they will be those integers in the range -2**n to 2**(n-1),
  inclusive, for some n not less than 15.  See most-positive-fixnum and
  most-negative-fixnum.

IOW, don't worry about whether an integer is a fixnum or a bignum, in
general.

Instead, right off the bat the Elisp doc tells users:

  Some functions in Emacs accept only fixnums.  Also, while fixnums can
  always be compared for numeric equality with 'eq', bignums require
  more-heavyweight equality predicates like 'eql'."

That's really the _last_ thing we should tell users, not the first.

And even if we tell them something like that we should NOT emphasize
using `eq' ("bignums _require_...").  We should NOT give users the
impression that they should want to avoid the "more-heavyweight"
comparison function `eql'.

We should instead tell users, right away, that they can (and typically
should) use `eql' for comparing any integers, regardless of whether they
happen, on this or that platform/machine, to be fixnums or bignums.

I'm really surprised this doc got inserted as it is.

Using `eq' is only an optimisation; it's platform/machine-specific; and
it makes users worry about whether the numbers being compared are both
fixnums.  (Sure, they can always test first with `fixnump' or `bignump',
but still...)

And I don't see where the doc tells you how the Lisp reader treats an
integer numeral - when it gives you a fixnum and when it gives you a
bignum.  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)?  I mean, if
you're going to be comparing against a literal value, and the doc slants
you toward using `eq' as it does, you'll at least want to know whether
some numeral ends up as a fixnum or a bignum.  (Sure, you can always
test it...)

(BTW, this doc should probably also mention that the numerical value of
a marker is an integer.  Sure, if they follow the link to node Markers
they'll find that out, but still.)



In GNU Emacs 27.0.60 (build 1, x86_64-w64-mingw32)
 of 2019-12-28
Repository revision: 21c3020fcec0a32122d2680a391864a75393031b
Windowing system distributor `Microsoft Corp.', version 10.0.18362
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install -C 'CFLAGS=-O2 -static -g3''





^ permalink raw reply	[flat|nested] 18+ messages in thread

end of thread, other threads:[~2020-09-25 11:18 UTC | newest]

Thread overview: 18+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
     [not found] <<3d420026-bb32-413f-9a9c-304240aa82e2@default>
     [not found] ` <<8336bhrrb4.fsf@gnu.org>
2020-02-11 18:26   ` bug#39557: 27.0.60; Elisp manual, doc about bignums Drew Adams
2020-02-11 19:14     ` Eli Zaretskii
2020-02-10 23:55 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
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

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).