org: Lookup functions
3.5.7 Lookup functions
----------------------
Org has three predefined Emacs Lisp functions for lookups in tables.
‘(org-lookup-first VAL S-LIST R-LIST &optional PREDICATE)’
Searches for the first element ‘S’ in list ‘S-LIST’ for which
(PREDICATE VAL S)
is ‘t’; returns the value from the corresponding position in list
‘R-LIST’. The default ‘PREDICATE’ is ‘equal’. Note that the
parameters ‘VAL’ and ‘S’ are passed to ‘PREDICATE’ in the same
order as the corresponding parameters are in the call to
‘org-lookup-first’, where ‘VAL’ precedes ‘S-LIST’. If ‘R-LIST’ is
‘nil’, the matching element ‘S’ of ‘S-LIST’ is returned.
‘(org-lookup-last VAL S-LIST R-LIST &optional PREDICATE)’
Similar to ‘org-lookup-first’ above, but searches for the last
element for which ‘PREDICATE’ is ‘t’.
‘(org-lookup-all VAL S-LIST R-LIST &optional PREDICATE)’
Similar to ‘org-lookup-first’, but searches for all elements for
which ‘PREDICATE’ is ‘t’, and returns all corresponding values.
This function can not be used by itself in a formula, because it
returns a list of values. However, powerful lookups can be built
when this function is combined with other Emacs Lisp functions.
If the ranges used in these functions contain empty fields, the ‘E’
mode for the formula should usually be specified: otherwise empty fields
will not be included in ‘S-LIST’ and/or ‘R-LIST’ which can, for example,
result in an incorrect mapping from an element of ‘S-LIST’ to the
corresponding element of ‘R-LIST’.
These three functions can be used to implement associative arrays,
count matching cells, rank results, group data etc. For practical
examples see this tutorial on Worg
(http://orgmode.org/worg/org-tutorials/org-lookups.html).