Major Section: ARRAYS
Example Form: (flush-compress 'my-array) General Form: (flush-compress name)where
name is a symbol.Recall that (compress1 nm alist) associates an under-the-hood raw Lisp
one-dimensional array of name nm with the given association list,
alist, while (compress2 nm alist) is the analogous function for
two-dimensional arrays; see compress1 and see compress2.  The only purpose
of flush-compress, which always returns nil, is to remove the
association of any under-the-hood array with the given name, thus eliminating
slow array accesses (see slow-array-warning).  It is not necessary if the
return values of compress1 and compress2 are always used as the
``current'' copy of the named array, and thus flush-compress should
rarely, if ever, be needed in user applications.
Nevertheless, we provide the following contrived example to show how
flush-compress can be used to good effect.  Comments have been added to
this log to provide explanation.
ACL2 !>(assign a (compress1 'demo
                            '((:header :dimensions (5)
                                       :maximum-length 15
                                       :default uninitialized
                                       :name demo)
                              (0 . zero)
                              (1 . one))))
 ((:HEADER :DIMENSIONS (5)
           :MAXIMUM-LENGTH
           15 :DEFAULT UNINITIALIZED :NAME DEMO)
  (0 . ZERO)
  (1 . ONE))
ACL2 !>(aref1 'demo (@ a) 0)
ZERO
; As expected, the above evaluation did not cause a slow array warning.  Now
; we associate a different under-the-hood array with the name 'demo.
ACL2 !>(compress1 'demo
                  '((:header :dimensions (5)
                             :maximum-length 15
                             :default uninitialized
                             :name demo)
                    (0 . zero)))
((:HEADER :DIMENSIONS (5)
          :MAXIMUM-LENGTH
          15 :DEFAULT UNINITIALIZED :NAME DEMO)
 (0 . ZERO))
; The following array access produces a slow array warning because (@ a) is
; no longer associated under-the-hood with the array name 'demo.
ACL2 !>(aref1 'demo (@ a) 0)
**********************************************************
Slow Array Access!  A call of AREF1 on an array named
DEMO is being executed slowly.  See :DOC slow-array-warning
**********************************************************
ZERO
; Now we associate under-the-hood, with array name 'demo, an alist equal to
; (@ a).
ACL2 !>(compress1 'demo
                  '((:header :dimensions (5)
                             :maximum-length 15
                             :default uninitialized
                             :name demo)
                    (0 . zero)
                    (1 . one)))
((:HEADER :DIMENSIONS (5)
          :MAXIMUM-LENGTH
          15 :DEFAULT UNINITIALIZED :NAME DEMO)
 (0 . ZERO)
 (1 . ONE))
; The following array access is still slow, because the under-the-hood array
; is merely associated with a copy of (@ a), not with the actual object
; (@ a).
ACL2 !>(aref1 'demo (@ a) 0)
**********************************************************
Slow Array Access!  A call of AREF1 on an array named
DEMO is being executed slowly.  See :DOC slow-array-warning
**********************************************************
ZERO
; So we might try to fix the problem by recompressing. But this doesn't
; work.  It would work, by the way, if we re-assign a:
; (assign a (compress1 'demo (@ a))).  That is why we usually will not need
; flush-compress.
ACL2 !>(compress1 'demo (@ a))
((:HEADER :DIMENSIONS (5)
          :MAXIMUM-LENGTH
          15 :DEFAULT UNINITIALIZED :NAME DEMO)
 (0 . ZERO)
 (1 . ONE))
ACL2 !>(aref1 'demo (@ a) 0)
**********************************************************
Slow Array Access!  A call of AREF1 on an array named
DEMO is being executed slowly.  See :DOC slow-array-warning
**********************************************************
ZERO
; Finally, we eliminate the warning by calling flush-compress before we call
; compress1.  The call of flush-compress removes any under-the-hood
; association of an array with the name 'demo.  Then the subsequent call of
; compress1 associates the object (@ a) with that name.  (Technical point:
; compress1 always associates the indicated name with the value that it
; returns.  in this case, what compress1 returns is (@ a), because (@ a) is
; already, logically speaking, a compressed array1p (starts with a :header
; and the natural number keys are ordered).
ACL2 !>(flush-compress 'demo)
NIL
ACL2 !>(compress1 'demo (@ a))
((:HEADER :DIMENSIONS (5)
          :MAXIMUM-LENGTH
          15 :DEFAULT UNINITIALIZED :NAME DEMO)
 (0 . ZERO)
 (1 . ONE))
ACL2 !>(aref1 'demo (@ a) 0)
ZERO
ACL2 !>
 
 