From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: Paul Eggert Newsgroups: gmane.emacs.bugs Subject: bug#39557: 27.0.60; Elisp manual, doc about bignums Date: Mon, 17 Feb 2020 14:05:38 -0800 Organization: UCLA Computer Science Department Message-ID: <8c6ed478-db97-8abc-de79-f5c10498ad0c@cs.ucla.edu> References: <3d420026-bb32-413f-9a9c-304240aa82e2@default> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="------------3CC4C11A0F12FEA602E14350" Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="52491"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.4.1 Cc: Noam Postavsky , 39557@debbugs.gnu.org To: Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Mon Feb 17 23:06:17 2020 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1j3oWu-000DXX-0N for geb-bug-gnu-emacs@m.gmane-mx.org; Mon, 17 Feb 2020 23:06:16 +0100 Original-Received: from localhost ([::1]:53632 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j3oWt-00078C-2u for geb-bug-gnu-emacs@m.gmane-mx.org; Mon, 17 Feb 2020 17:06:15 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:50209) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j3oWh-00077w-Th for bug-gnu-emacs@gnu.org; Mon, 17 Feb 2020 17:06:05 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1j3oWg-0007QM-8o for bug-gnu-emacs@gnu.org; Mon, 17 Feb 2020 17:06:03 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:33355) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1j3oWg-0007QG-51 for bug-gnu-emacs@gnu.org; Mon, 17 Feb 2020 17:06:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1j3oWf-0006KP-Ul for bug-gnu-emacs@gnu.org; Mon, 17 Feb 2020 17:06:01 -0500 X-Loop: help-debbugs@gnu.org In-Reply-To: <3d420026-bb32-413f-9a9c-304240aa82e2@default> Resent-From: Paul Eggert Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 17 Feb 2020 22:06:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 39557 X-GNU-PR-Package: emacs Original-Received: via spool by 39557-submit@debbugs.gnu.org id=B39557.158197714924304 (code B ref 39557); Mon, 17 Feb 2020 22:06:01 +0000 Original-Received: (at 39557) by debbugs.gnu.org; 17 Feb 2020 22:05:49 +0000 Original-Received: from localhost ([127.0.0.1]:39328 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1j3oWS-0006Jw-Gi for submit@debbugs.gnu.org; Mon, 17 Feb 2020 17:05:48 -0500 Original-Received: from zimbra.cs.ucla.edu ([131.179.128.68]:48066) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1j3oWQ-0006Ji-2o for 39557@debbugs.gnu.org; Mon, 17 Feb 2020 17:05:47 -0500 Original-Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id 6A07B16008E; Mon, 17 Feb 2020 14:05:40 -0800 (PST) Original-Received: from zimbra.cs.ucla.edu ([127.0.0.1]) by localhost (zimbra.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10032) with ESMTP id GpiN4xN8H5vU; Mon, 17 Feb 2020 14:05:39 -0800 (PST) Original-Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id C901C160093; Mon, 17 Feb 2020 14:05:38 -0800 (PST) X-Virus-Scanned: amavisd-new at zimbra.cs.ucla.edu Original-Received: from zimbra.cs.ucla.edu ([127.0.0.1]) by localhost (zimbra.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10026) with ESMTP id OZIJ3cq3tQkQ; Mon, 17 Feb 2020 14:05:38 -0800 (PST) Original-Received: from [192.168.1.9] (cpe-23-242-74-103.socal.res.rr.com [23.242.74.103]) by zimbra.cs.ucla.edu (Postfix) with ESMTPSA id 718FC16008E; Mon, 17 Feb 2020 14:05:38 -0800 (PST) Content-Language: en-US X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:176166 Archived-At: This is a multi-part message in MIME format. --------------3CC4C11A0F12FEA602E14350 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit > 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. --------------3CC4C11A0F12FEA602E14350 Content-Type: text/x-patch; charset=UTF-8; name="0001-Reorder-discussion-of-integer-basics.patch" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="0001-Reorder-discussion-of-integer-basics.patch" >From 290cfbedd75764ab863677f63f66db13ceb70598 Mon Sep 17 00:00:00 2001 From: Paul Eggert 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 --------------3CC4C11A0F12FEA602E14350 Content-Type: text/x-patch; charset=UTF-8; name="0002-Clarify-when-fixnums-are-used.patch" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="0002-Clarify-when-fixnums-are-used.patch" >From 8593d449972ad2bac850c03839653223d402a682 Mon Sep 17 00:00:00 2001 From: Paul Eggert 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 --------------3CC4C11A0F12FEA602E14350--