lisp/emacs-lisp/ring.el

   1 ;;; ring.el --- handle rings of items
   2
   3 ;; Copyright (C) 1992 Free Software Foundation, Inc.
   4
   5 ;; Maintainer: FSF
   6 ;; Keywords: extensions
   7
   8 ;; This file is part of GNU Emacs.
   9
  10 ;; GNU Emacs is free software; you can redistribute it and/or modify
  11 ;; it under the terms of the GNU General Public License as published by
  12 ;; the Free Software Foundation; either version 2, or (at your option)
  13 ;; any later version.
  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
  21 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
  22 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  23 ;; Boston, MA 02111-1307, USA.
  24
  25 ;;; Commentary:
  26
  27 ;; This code defines a ring data structure. A ring is a
  28 ;;     (hd-index length . vector)
  29 ;; list.  You can insert to, remove from, and rotate a ring.  When the ring
  30 ;; fills up, insertions cause the oldest elts to be quietly dropped.
  31 ;;
  32 ;; In ring-ref, 0 is the index of the newest element.  Higher indexes
  33 ;; correspond to older elements; when the index equals the ring length,
  34 ;; it wraps to the newest element again.
  35 ;;
  36 ;; hd-index = vector index of the oldest ring item.
  37 ;;         Newer items follow this item; at the end of the vector,
  38 ;;         they wrap around to the start of the vector.
  39 ;; length = number of items currently in the ring.
  40 ;;         This never exceeds the length of the vector itself.
  41 ;;
  42 ;; These functions are used by the input history mechanism, but they can
  43 ;; be used for other purposes as well.
  44
  45 ;;; Code:
  46
  47 ;;; User Functions:
  48
  49 ;;;###autoload
  50 (defun ring-p (x)
  51   "Returns t if X is a ring; nil otherwise."
  52   (and (consp x) (integerp (car x))
  53        (consp (cdr x)) (integerp (car (cdr x)))
  54        (vectorp (cdr (cdr x)))))
  55
  56 ;;;###autoload
  57 (defun make-ring (size)
  58   "Make a ring that can contain SIZE elements."
  59   (cons 0 (cons 0 (make-vector size nil))))
  60
  61 (defun ring-insert-at-beginning (ring item)
  62   "Add to RING the item ITEM.  Add it at the front, as the oldest item."
  63   (let* ((vec (cdr (cdr ring)))
  64          (veclen (length vec))
  65          (hd (car ring))
  66          (ln (car (cdr ring))))
  67     (setq ln (min veclen (1+ ln))
  68           hd (ring-minus1 hd veclen))
  69     (aset vec hd item)
  70     (setcar ring hd)
  71     (setcar (cdr ring) ln)))
  72
  73 (defun ring-plus1 (index veclen)
  74   "Returns INDEX+1, with wraparound."
  75   (let ((new-index (+ index 1)))
  76     (if (= new-index veclen) 0 new-index)))
  77
  78 (defun ring-minus1 (index veclen)
  79   "Returns INDEX-1, with wraparound."
  80   (- (if (= 0 index) veclen index) 1))
  81
  82 (defun ring-length (ring)
  83   "Returns the number of elements in the RING."
  84   (car (cdr ring)))
  85
  86 (defun ring-index (index head ringlen veclen)
  87   "Converts nominal ring index INDEX to an internal index.
  88 The internal index refers to the items ordered from newest to oldest.
  89 HEAD is the index of the oldest element in the ring.
  90 RINGLEN is the number of elements currently in the ring.
  91 VECLEN is the size of the vector in the ring."
  92   (setq index (mod index ringlen))
  93   (mod (1- (+ head (- ringlen index))) veclen))
  94
  95 (defun ring-empty-p (ring)
  96   "Returns t if RING is empty; nil otherwise."
  97   (= 0 (car (cdr ring))))
  98
  99 (defun ring-size (ring)
 100   "Returns the size of RING, the maximum number of elements it can contain."
 101   (length (cdr (cdr ring))))
 102
 103 (defun ring-copy (ring)
 104   "Returns a copy of RING."
 105   (let* ((vec (cdr (cdr ring)))
 106          (hd  (car ring))
 107          (ln  (car (cdr ring))))
 108     (cons hd (cons ln (copy-sequence vec)))))
 109
 110 (defun ring-insert (ring item)
 111   "Insert onto ring RING the item ITEM, as the newest (last) item.
 112 If the ring is full, dump the oldest item to make room."
 113   (let* ((vec (cdr (cdr ring)))
 114          (veclen (length vec))
 115          (hd (car ring))
 116          (ln (car (cdr ring))))
 117     (prog1
 118         (aset vec (mod (+ hd ln) veclen) item)
 119       (if (= ln veclen)
 120           (setcar ring (ring-plus1 hd veclen))
 121         (setcar (cdr ring) (1+ ln))))))
 122
 123 (defun ring-remove (ring &optional index)
 124   "Remove an item from the RING.  Return the removed item.
 125 If optional INDEX is nil, remove the oldest item.  If it's
 126 numeric, remove the element indexed."
 127   (if (ring-empty-p ring)
 128       (error "Ring empty")
 129     (let* ((hd (car ring))
 130            (ln (car (cdr ring)))
 131            (vec (cdr (cdr ring)))
 132            (veclen (length vec))
 133            (tl (mod (1- (+ hd ln)) veclen))
 134            oldelt)
 135       (if (null index)
 136           (setq index (1- ln)))
 137       (setq index (ring-index index hd ln veclen))
 138       (setq oldelt (aref vec index))
 139       (while (/= index tl)
 140         (aset vec index (aref vec (ring-plus1 index veclen)))
 141         (setq index (ring-plus1 index veclen)))
 142       (aset vec tl nil)
 143       (setcar (cdr ring) (1- ln))
 144       oldelt)))
 145
 146 (defun ring-ref (ring index)
 147   "Returns RING's INDEX element.
 148 INDEX = 0 is the most recently inserted; higher indices
 149 correspond to older elements.
 150 INDEX need not be <= the ring length; the appropriate modulo operation
 151 will be performed."
 152   (if (ring-empty-p ring)
 153       (error "Accessing an empty ring")
 154     (let* ((hd (car ring))  (ln (car (cdr ring)))  (vec (cdr (cdr ring))))
 155       (aref vec (ring-index index hd ln (length vec))))))
 156
 157 (defun ring-elements (ring)
 158   "Return a list of the lements of RING."
 159   (mapcar #'identity (cddr ring)))
 160
 161 ;;; provide ourself:
 162
 163 (provide 'ring)
 164
 165 ;;; ring.el ends here