[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#17623: 24.4.50; incorrect example for `apply-partially' in (elisp) `
From: |
Drew Adams |
Subject: |
bug#17623: 24.4.50; incorrect example for `apply-partially' in (elisp) `Calling Functions' |
Date: |
Fri, 27 Jun 2014 18:36:04 -0700 (PDT) |
> should we try to find a different example? Maybe something like
> (defalias 'string-empty-p (apply-partially #'string= "")) ?
Yes, we should. But forget about giving an example that (re)defines
a function that is a built-in or is otherwise predefined.
And again, it is better to have an example that illustrates and
takes advantage of the fact that the function returned accepts any
number of args.
`string=' accepts only two args. The signature of `string-empty-p'
shows that it accepts any number of arguments, and it says nothing
about their type, but `string-empty-p' raises an error if it is
passed anything other than 2 strings. Nothing wrong with that, but
it is not so clear as an illustration of `apply-partially'.
And it is better to have an example where the function passed does
not have _only_ an &rest parameter (in which case it could be applied
to just the first argument anyway). This example uses a function (+)
that accepts any number of args, but its only parameter is an &rest
parameter, so it is not a great way to show `apply-partially':
(defalias '3+ (apply-partially '+ 3)
"Return 3 plus the sum of the arguments.")
(3+ 2 5 1)
=> 11
That is better than an example that uses a function that accepts
only a fixed number of arguments, but it is not as informative as
examples like these, which accept a first arg that is a string
and other args of any type.
(defun present-list (frmt &rest things)
"Use format string FRMT to present a list of THINGS."
(format frmt things))
(defalias 'list-en (apply-partially #'present-list "The list: `%S'")
"Return a string that presents a list of arguments.")
(defalias 'list-fr (apply-partially #'present-list "La liste : `%S'")
"Renvoyer une chaine qui presente use liste d'arguments.")
(list-en 1 2 3)
=> "The list: `(1 2 3)'"
(list-fr '(x 42) '(y alpha))
=> "La liste : `((x 42) (y alpha))'"
However, instead of (or in addition to) showing such an example,
we could show the simple equivalence of these two (for all FUN,
ARG1, and ARGS):
(apply (apply-partially FUN ARG1) ARGS) = (apply FUN ARG1 ARGS)
That alone tells users what `apply-partially' is all about.
- bug#17623: 24.4.50; incorrect example for `apply-partially' in (elisp) `Calling Functions', Michael Heerdegen, 2014/06/27
- bug#17623: 24.4.50; incorrect example for `apply-partially' in (elisp) `Calling Functions',
Drew Adams <=
- bug#17623: 24.4.50; incorrect example for `apply-partially' in (elisp) `Calling Functions', Michael Heerdegen, 2014/06/28
- bug#17623: 24.4.50; incorrect example for `apply-partially' in (elisp) `Calling Functions', Eli Zaretskii, 2014/06/28
- bug#17623: 24.4.50; incorrect example for `apply-partially' in (elisp) `Calling Functions', Michael Heerdegen, 2014/06/28
- bug#17623: 24.4.50; incorrect example for `apply-partially' in (elisp) `Calling Functions', Eli Zaretskii, 2014/06/28
- bug#17623: 24.4.50; incorrect example for `apply-partially' in (elisp) `Calling Functions', Drew Adams, 2014/06/28
- bug#17623: 24.4.50; incorrect example for `apply-partially' in (elisp) `Calling Functions', Michael Heerdegen, 2014/06/28
- bug#17623: 24.4.50; incorrect example for `apply-partially' in (elisp) `Calling Functions', Eli Zaretskii, 2014/06/29
- bug#17623: 24.4.50; incorrect example for `apply-partially' in (elisp) `Calling Functions', Stefan Monnier, 2014/06/29