* lisp/emacs-lisp/assoc.el: Remove misleading `sort'.
[bpt/emacs.git] / lisp / emacs-lisp / assoc.el
CommitLineData
e573299d 1;;; assoc.el --- insert/delete functions on association lists
cdccfc0d 2
73b0cd50 3;; Copyright (C) 1996, 2001-2011 Free Software Foundation, Inc.
b578f267 4
cdccfc0d
ER
5;; Author: Barry A. Warsaw <bwarsaw@cen.com>
6;; Keywords: extensions
7
b578f267
EN
8;; This file is part of GNU Emacs.
9
d6cba7ae 10;; GNU Emacs is free software: you can redistribute it and/or modify
b578f267 11;; it under the terms of the GNU General Public License as published by
d6cba7ae
GM
12;; the Free Software Foundation, either version 3 of the License, or
13;; (at your option) any later version.
b578f267
EN
14
15;; GNU Emacs is distributed in the hope that it will be useful,
16;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18;; GNU General Public License for more details.
19
20;; You should have received a copy of the GNU General Public License
d6cba7ae 21;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
cdccfc0d
ER
22
23;;; Commentary:
24
25;; Association list utilities providing insertion, deletion, sorting
26;; fetching off key-value pairs in association lists.
27
28;;; Code:
064eee03 29(eval-when-compile (require 'cl))
cdccfc0d 30
6476a5fa 31(defun asort (alist-symbol key)
cdccfc0d 32 "Move a specified key-value pair to the head of an alist.
6cda144f 33The alist is referenced by ALIST-SYMBOL. Key-value pair to move to
cdccfc0d
ER
34head is one matching KEY. Returns the sorted list and doesn't affect
35the order of any other key-value pair. Side effect sets alist to new
36sorted list."
37 (set alist-symbol
e573299d 38 (sort (copy-alist (symbol-value alist-symbol))
cdccfc0d
ER
39 (function (lambda (a b) (equal (car a) key))))))
40
41
42(defun aelement (key value)
6cda144f 43 "Make a list of a cons cell containing car of KEY and cdr of VALUE.
ac59f99d 44The returned list is suitable for concatenating with an existing
245e0faf 45alist, via `nconc'."
cdccfc0d
ER
46 (list (cons key value)))
47
48
49(defun aheadsym (alist)
50 "Return the key symbol at the head of ALIST."
51 (car (car alist)))
52
53
54(defun anot-head-p (alist key)
55 "Find out if a specified key-value pair is not at the head of an alist.
56The alist to check is specified by ALIST and the key-value pair is the
57one matching the supplied KEY. Returns nil if ALIST is nil, or if
58key-value pair is at the head of the alist. Returns t if key-value
59pair is not at the head of alist. ALIST is not altered."
60 (not (equal (aheadsym alist) key)))
61
62
63(defun aput (alist-symbol key &optional value)
64 "Inserts a key-value pair into an alist.
6cda144f
JB
65The alist is referenced by ALIST-SYMBOL. The key-value pair is made
66from KEY and optionally, VALUE. Returns the altered alist or nil if
cdccfc0d
ER
67ALIST is nil.
68
69If the key-value pair referenced by KEY can be found in the alist, and
70VALUE is supplied non-nil, then the value of KEY will be set to VALUE.
71If VALUE is not supplied, or is nil, the key-value pair will not be
6cda144f 72modified, but will be moved to the head of the alist. If the key-value
cdccfc0d
ER
73pair cannot be found in the alist, it will be inserted into the head
74of the alist (with value nil if VALUE is nil or not supplied)."
064eee03
CY
75 (lexical-let ((elem (aelement key value))
76 alist)
cdccfc0d 77 (asort alist-symbol key)
e573299d 78 (setq alist (symbol-value alist-symbol))
cdccfc0d
ER
79 (cond ((null alist) (set alist-symbol elem))
80 ((anot-head-p alist key) (set alist-symbol (nconc elem alist)))
81 (value (setcar alist (car elem)))
82 (t alist))))
83
84
85(defun adelete (alist-symbol key)
86 "Delete a key-value pair from the alist.
87Alist is referenced by ALIST-SYMBOL and the key-value pair to remove
88is pair matching KEY. Returns the altered alist."
89 (asort alist-symbol key)
e573299d 90 (lexical-let ((alist (symbol-value alist-symbol)))
cdccfc0d
ER
91 (cond ((null alist) nil)
92 ((anot-head-p alist key) alist)
93 (t (set alist-symbol (cdr alist))))))
94
95
96(defun aget (alist key &optional keynil-p)
6cda144f 97 "Return the value in ALIST that is associated with KEY.
cdccfc0d
ER
98Optional KEYNIL-P describes what to do if the value associated with
99KEY is nil. If KEYNIL-P is not supplied or is nil, and the value is
100nil, then KEY is returned. If KEYNIL-P is non-nil, then nil would be
101returned.
102
103If no key-value pair matching KEY could be found in ALIST, or ALIST is
6cda144f 104nil then nil is returned. ALIST is not altered."
cdccfc0d
ER
105 (let ((copy (copy-alist alist)))
106 (cond ((null alist) nil)
107 ((progn (asort 'copy key)
108 (anot-head-p copy key)) nil)
109 ((cdr (car copy)))
110 (keynil-p nil)
111 ((car (car copy)))
112 (t nil))))
113
114
115(defun amake (alist-symbol keylist &optional valuelist)
116 "Make an association list.
117The association list is attached to the alist referenced by
6cda144f
JB
118ALIST-SYMBOL. Each element in the KEYLIST becomes a key and is
119associated with the value in VALUELIST with the same index. If
cdccfc0d
ER
120VALUELIST is not supplied or is nil, then each key in KEYLIST is
121associated with nil.
122
123KEYLIST and VALUELIST should have the same number of elements, but
124this isn't enforced. If VALUELIST is smaller than KEYLIST, remaining
125keys are associated with nil. If VALUELIST is larger than KEYLIST,
126extra values are ignored. Returns the created alist."
064eee03
CY
127 (lexical-let ((keycar (car keylist))
128 (keycdr (cdr keylist))
129 (valcar (car valuelist))
130 (valcdr (cdr valuelist)))
cdccfc0d
ER
131 (cond ((null keycdr)
132 (aput alist-symbol keycar valcar))
133 (t
134 (amake alist-symbol keycdr valcdr)
135 (aput alist-symbol keycar valcar))))
e573299d 136 (symbol-value alist-symbol))
cdccfc0d
ER
137
138(provide 'assoc)
139
140;;; assoc.el ends here