;;; ring.el --- handle rings of items
-;; Copyright (C) 1992 Free Software Foundation, Inc.
+;; Copyright (C) 1992, 2002, 2003, 2004, 2005,
+;; 2006 Free Software Foundation, Inc.
;; Maintainer: FSF
;; Keywords: extensions
;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs; see the file COPYING. If not, write to the
-;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-;; Boston, MA 02111-1307, USA.
+;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+;; Boston, MA 02110-1301, USA.
;;; Commentary:
-;; This code defines a ring data structure. A ring is a
+;; This code defines a ring data structure. A ring is a
;; (hd-index length . vector)
;; list. You can insert to, remove from, and rotate a ring. When the ring
;; fills up, insertions cause the oldest elts to be quietly dropped.
;; These functions are used by the input history mechanism, but they can
;; be used for other purposes as well.
-;;; Change Log:
-
-;; Sun Aug 22 12:58:54 1999 Kevin Blake <kblake@ticnet.com>
-;; * Added the `ring-size' and `ring-copy' functions. Added documentation
-to
-;; the `ring-empty-p' and `ring-index' functions. Enhanced the
-documentation
-;; of several functions. Added comments to the layout of this module to
-;; make things more obvious.
-
;;; Code:
;;; User Functions:
;;;###autoload
(defun ring-p (x)
- "Returns t if X is a ring; nil otherwise."
+ "Return t if X is a ring; nil otherwise."
(and (consp x) (integerp (car x))
(consp (cdr x)) (integerp (car (cdr x)))
(vectorp (cdr (cdr x)))))
(setcar (cdr ring) ln)))
(defun ring-plus1 (index veclen)
- "Returns INDEX+1, with wraparound."
+ "Return INDEX+1, with wraparound."
(let ((new-index (+ index 1)))
(if (= new-index veclen) 0 new-index)))
(defun ring-minus1 (index veclen)
- "Returns INDEX-1, with wraparound."
+ "Return INDEX-1, with wraparound."
(- (if (= 0 index) veclen index) 1))
(defun ring-length (ring)
- "Returns the number of elements in the RING."
+ "Return the number of elements in the RING."
(car (cdr ring)))
(defun ring-index (index head ringlen veclen)
- "Converts nominal ring index INDEX to an internal index.
+ "Convert nominal ring index INDEX to an internal index.
The internal index refers to the items ordered from newest to oldest.
HEAD is the index of the oldest element in the ring.
RINGLEN is the number of elements currently in the ring.
(mod (1- (+ head (- ringlen index))) veclen))
(defun ring-empty-p (ring)
- "Returns t if RING is empty; nil otherwise."
- (= 0 (car (cdr ring))))
+ "Return t if RING is empty; nil otherwise."
+ (zerop (car (cdr ring))))
(defun ring-size (ring)
- "Returns the size of RING, the maximum number of elements it can contain."
+ "Return the size of RING, the maximum number of elements it can contain."
(length (cdr (cdr ring))))
(defun ring-copy (ring)
- "Returns a copy of RING."
- (let*
- ((vec (cdr (cdr ring)))
- (hd (car ring))
- (ln (car (cdr ring))))
+ "Return a copy of RING."
+ (let* ((vec (cdr (cdr ring)))
+ (hd (car ring))
+ (ln (car (cdr ring))))
(cons hd (cons ln (copy-sequence vec)))))
(defun ring-insert (ring item)
oldelt)))
(defun ring-ref (ring index)
- "Returns RING's INDEX element.
+ "Return RING's INDEX element.
INDEX = 0 is the most recently inserted; higher indices
correspond to older elements.
-INDEX need not be <= the ring length, the appropriate modulo operation
+INDEX need not be <= the ring length; the appropriate modulo operation
will be performed."
(if (ring-empty-p ring)
(error "Accessing an empty ring")
(let* ((hd (car ring)) (ln (car (cdr ring))) (vec (cdr (cdr ring))))
(aref vec (ring-index index hd ln (length vec))))))
+(defun ring-elements (ring)
+ "Return a list of the elements of RING, in order, newest first."
+ (let ((start (car ring))
+ (size (ring-size ring))
+ (vect (cddr ring))
+ lst)
+ (dotimes (var (cadr ring) lst)
+ (push (aref vect (mod (+ start var) size)) lst))))
+
;;; provide ourself:
(provide 'ring)
+;;; arch-tag: e707682b-ed69-47c9-b20f-cf2c68cc92d2
;;; ring.el ends here