bug#714: directory-files: Doc string is irritatingly vague wrt sorting.

bug#714: directory-files: Doc string is irritatingly vague wrt sorting.

[Alan Mackenzie]

Hi, Emacs!

The doc string for directory files is:

    directory-files is a built-in function in `src/dired.c'.
    (directory-files DIRECTORY &optional FULL MATCH NOSORT)

    Return a list of names of files in DIRECTORY.
    There are three optional arguments:
    If FULL is non-nil, return absolute file names.  Otherwise return names
    that are relative to the specified directory.
    If MATCH is non-nil, mention only file names that match the regexp MATCH.
    If NOSORT is non-nil, the list is not sorted--its order is unpredictable.
     NOSORT is useful if you plan to sort the result yourself.

This sort of implies (but doesn't state) that if NOSORT is nil, the
returned list is sorted.

More importantly, it doesn't state the predicate used for the sorting.
"Obviously", this will be some sort of alphabetical sort, but this gets
complicated for mixed case filenames and (more importantly) for character
sets which aren't vanilla ASCII.

-- 
Alan Mackenzie (Nuremberg, Germany).

bug#714: directory-files: Doc string is irritatingly vague wrt sorting.

[Glenn Morris]

Alan Mackenzie wrote:

> More importantly, it doesn't state the predicate used for the sorting.
> "Obviously", this will be some sort of alphabetical sort, but this gets
> complicated for mixed case filenames and (more importantly) for character
> sets which aren't vanilla ASCII.

Will saying it uses `string-lessp' be good enough for you? The details
of said function are in the Elisp manual.

bug#714: marked as done (directory-files: Doc string is irritatingly vague wrt sorting.)

[Emacs bug Tracking System]

[-- Attachment #1: Type: text/plain, Size: 885 bytes --]


Your message dated Fri, 15 Aug 2008 16:19:06 -0400
with message-id <877iai8211.fsf@cyd.mit.edu>
and subject line Re: directory-files:  Doc string is irritatingly vague wrt sorting.
has caused the Emacs bug report #714,
regarding directory-files:  Doc string is irritatingly vague wrt sorting.
to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact don@donarmstrong.com
immediately.)


-- 
714: http://emacsbugs.donarmstrong.com/cgi-bin/bugreport.cgi?bug=714
Emacs Bug Tracking System
Contact don@donarmstrong.com with problems

[-- Attachment #2: Type: message/rfc822, Size: 3057 bytes --]

From: Alan Mackenzie <acm@muc.de>
To: bug-gnu-emacs@gnu.org
Subject: directory-files:  Doc string is irritatingly vague wrt sorting.
Date: Wed, 13 Aug 2008 19:11:41 +0000
Message-ID: <20080813191141.GA2825@muc.de>

Hi, Emacs!

The doc string for directory files is:

    directory-files is a built-in function in `src/dired.c'.
    (directory-files DIRECTORY &optional FULL MATCH NOSORT)

    Return a list of names of files in DIRECTORY.
    There are three optional arguments:
    If FULL is non-nil, return absolute file names.  Otherwise return names
    that are relative to the specified directory.
    If MATCH is non-nil, mention only file names that match the regexp MATCH.
    If NOSORT is non-nil, the list is not sorted--its order is unpredictable.
     NOSORT is useful if you plan to sort the result yourself.

This sort of implies (but doesn't state) that if NOSORT is nil, the
returned list is sorted.

More importantly, it doesn't state the predicate used for the sorting.
"Obviously", this will be some sort of alphabetical sort, but this gets
complicated for mixed case filenames and (more importantly) for character
sets which aren't vanilla ASCII.

-- 
Alan Mackenzie (Nuremberg, Germany).




[-- Attachment #3: Type: message/rfc822, Size: 1000 bytes --]

From: Chong Yidong <cyd@stupidchicken.com>
To: Alan Mackenzie <acm@muc.de>
Cc: 714-done@emacsbugs.donarmstrong.com
Subject: Re: directory-files:  Doc string is irritatingly vague wrt sorting.
Date: Fri, 15 Aug 2008 16:19:06 -0400
Message-ID: <877iai8211.fsf@cyd.mit.edu>

I've clarified the docstring.  Thanks.