[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
scratch/sort-key 3a3568784ea 03/11: Add manual entry for value< (bug#697
From: |
Mattias Engdegård |
Subject: |
scratch/sort-key 3a3568784ea 03/11: Add manual entry for value< (bug#69709) |
Date: |
Sat, 23 Mar 2024 09:19:34 -0400 (EDT) |
branch: scratch/sort-key
commit 3a3568784eab9eb7889d23e40f498f3cf89beea0
Author: Mattias Engdegård <mattiase@acm.org>
Commit: Mattias Engdegård <mattiase@acm.org>
Add manual entry for value< (bug#69709)
* doc/lispref/sequences.texi (Sequence Functions):
* doc/lispref/numbers.texi (Comparison of Numbers):
* doc/lispref/strings.texi (Text Comparison):
Document the new value< function.
---
doc/lispref/numbers.texi | 1 +
doc/lispref/sequences.texi | 35 +++++++++++++++++++++++++++++++++++
doc/lispref/strings.texi | 1 +
3 files changed, 37 insertions(+)
diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi
index 99b456043b9..2c093ccd6bd 100644
--- a/doc/lispref/numbers.texi
+++ b/doc/lispref/numbers.texi
@@ -476,6 +476,7 @@ This function tests whether its arguments are numerically
equal, and
returns @code{t} if they are not, and @code{nil} if they are.
@end defun
+@anchor{definition of <}
@defun < number-or-marker &rest number-or-markers
This function tests whether each argument is strictly less than the
following argument. It returns @code{t} if so, @code{nil} otherwise.
diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi
index 74719d4779f..5bdf71fe02e 100644
--- a/doc/lispref/sequences.texi
+++ b/doc/lispref/sequences.texi
@@ -436,6 +436,41 @@ but their relative order is also preserved:
@end example
@end defun
+@cindex comparing values
+@cindex standard sorting order
+@defun value< a b
+This function returns non-@code{nil} if @var{a} comes before @var{b} in
+the standard sorting order; this means that it returns @code{nil} when
+@var{b} comes before @var{a}, or if they are equal or unordered.
+
+@var{a} and @var{b} must have the same type. Specifically:
+
+@itemize @bullet
+@item
+Numbers are compared using @code{<} (@pxref{definition of <}).
+@item
+Strings and symbols are compared using @code{string<}
+(@pxref{definition of string<}).
+@item
+Conses, lists, vectors and records are compared lexicographically.
+@item
+Markers are compared first by buffer, then by position.
+@item
+Buffers and processes are compared by name.
+@item
+Other types are considered unordered and the return value will be @code{nil}.
+@end itemize
+
+Examples:
+@example
+(value< -4 3.5) @result{} t
+(value< "dog" "cat") @result{} nil
+(value< 'yip 'yip) @result{} nil
+(value< '(3 2) '(3 2 0)) @result{} t
+(value< [3 2 1] [3 2 0]) @result{} nil
+@end example
+@end defun
+
Sometimes, computation of sort keys of list or vector elements is
expensive, and therefore it is important to perform it the minimum
number of times. By contrast, computing the sort keys of elements
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 4fe94f78cba..130e82f6f9b 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -612,6 +612,7 @@ that collation implements.
@end defun
@cindex lexical comparison of strings
+@anchor{definition of string<}
@defun string< string1 string2
@c (findex string< causes problems for permuted index!!)
This function compares two strings a character at a time. It
- branch scratch/sort-key created (now ed59a2639a9), Mattias Engdegård, 2024/03/23
- scratch/sort-key 2dc07013ef2 02/11: Add NEWS entry for value< (bug#69709), Mattias Engdegård, 2024/03/23
- scratch/sort-key 72d4e3a9d26 01/11: Add value< (bug#69709), Mattias Engdegård, 2024/03/23
- scratch/sort-key 01e5337293c 04/11: Add back timsort key function handling (bug#69709), Mattias Engdegård, 2024/03/23
- scratch/sort-key 24bfd3e89d3 06/11: Speed up `sort` by special-casing the value< ordering, Mattias Engdegård, 2024/03/23
- scratch/sort-key 5fe92f3c33a 07/11: Faster non-destructive list sorting, Mattias Engdegård, 2024/03/23
- scratch/sort-key 7250e610f51 08/11: Add NEWS entry for new `sort` arguments and features, Mattias Engdegård, 2024/03/23
- scratch/sort-key 4de45937313 09/11: Update manual entry for `sort` (bug#69709), Mattias Engdegård, 2024/03/23
- scratch/sort-key 2cef2a91c13 05/11: New `sort` keyword arguments (bug#69709), Mattias Engdegård, 2024/03/23
- scratch/sort-key 3a3568784ea 03/11: Add manual entry for value< (bug#69709),
Mattias Engdegård <=
- scratch/sort-key 592ca5070e2 10/11: Use new-style sort signature in Lisp manual examples, Mattias Engdegård, 2024/03/23
- scratch/sort-key ed59a2639a9 11/11: Remove sort-on, Mattias Engdegård, 2024/03/23