From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: documentation of integers, fixnums and bignums Date: Sat, 08 Sep 2018 19:27:24 +0300 Message-ID: <83pnxorm37.fsf@gnu.org> References: <0f632217-27ad-4f54-8ce0-480301fa2a86@cs.ucla.edu> NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1536424264 3543 195.159.176.226 (8 Sep 2018 16:31:04 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sat, 8 Sep 2018 16:31:04 +0000 (UTC) Cc: Emacs-devel@gnu.org To: Paul Eggert Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Sep 08 18:31:00 2018 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fyg8S-0000nD-Lc for ged-emacs-devel@m.gmane.org; Sat, 08 Sep 2018 18:31:00 +0200 Original-Received: from localhost ([::1]:43595 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fygAZ-0005Uu-6N for ged-emacs-devel@m.gmane.org; Sat, 08 Sep 2018 12:33:11 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:45358) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fygAF-00052F-BJ for Emacs-devel@gnu.org; Sat, 08 Sep 2018 12:32:54 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fyg4w-0002aV-5q for Emacs-devel@gnu.org; Sat, 08 Sep 2018 12:27:25 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:50682) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fyg4w-0002a7-1u; Sat, 08 Sep 2018 12:27:22 -0400 Original-Received: from [176.228.60.248] (port=4317 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1fyg4v-0002uv-LI; Sat, 08 Sep 2018 12:27:21 -0400 In-reply-to: <0f632217-27ad-4f54-8ce0-480301fa2a86@cs.ucla.edu> (message from Paul Eggert on Sat, 8 Sep 2018 09:09:03 -0700) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:229500 Archived-At: > From: Paul Eggert > Cc: Emacs Development > Date: Sat, 8 Sep 2018 09:09:03 -0700 > > > DEFUN ("encode-char", Fencode_char, Sencode_char, 2, 2, 0, > > doc: /* Encode the character CH into a code-point of CHARSET. > > -Return nil if CHARSET doesn't include CH. */) > > +Return the encoded code-point, a fixnum if its value is small enough, > > +otherwise a bignum. > > +Return nil if CHARSET doesn't support CH. */) > > As the intent is that Emacs should treat integers transparently, so that > ordinary code needn't worry about the difference between bignums and fixnums, it > would be better if documentation like this simply says something like "Return > the encoded code-point, an integer", as this is more concise. Sorry, I disagree. I think it's important for the Lisp programmers to know what kind of objects they could get as return values. Maybe in some distant future we will no longer care about the difference between fixnums and bignums, but as of now, we still do. I've left the ELisp manual documentation which says "number" without these details, but I think at least the doc strings should spell out these details, for now. > It's true that the current integer implementation is a bit different, in that eq > and = now treat integers differently; but this is a global property that is best > documented in the integer section of the Emacs manual. We shouldn't need to add > a comment in each function returning an integer in effect saying "watch out! eq > and = might act differently on these integers!" as the cost to users of this > documentation complication will exceed its benefit in the long run. I think we should call out the functions that can return bignums because of this and other peculiarities of bignums. Otherwise, people will have hard time writing robust programs that use these APIs. E.g., it would take an expert in obscure character sets to know that encode-char could potentially return a value that cannot be represented as a fixnum.