A tiny utility to change array size ensuring it is simple.

trivial-adjust-simple-array

* trivial-adjust-simple-array

=trivial-adjust-simple-array= is a tiny simple Common Lisp utility library providing ~ADJUST-SIMPLE-ARRAY~ macro to change given ~SIMPLE-ARRAY~ size in a manner regular [[http://clhs.lisp.se/Body/f_adjust.htm][ADJUST-ARRAY]] does, while ensuring that the resulting array is still simple array. In other words, the following assertions are always correct:
#+begin_src lisp
  (let ((adjusted-array (trivial-adjust-simple-array:adjust-simple-array
                         some-array some-new-size
                         :element-type 'some-array-element-type)))
    (assert (null (array-displacement       adjusted-array)))
    (assert (null (array-has-fill-pointer-p adjusted-array)))
    (assert (null (adjustable-array-p       adjusted-array))))
#+end_src

=trivial-adjust-simple-array= also provides ~ADJUST-SIMPLE-ARRAYF~ modify macro akin to ~INCF~ and similar which can save you some typing:

#+begin_src lisp
  (trivial-adjust-simple-array:adjust-simple-arrayf
   my-array new-size
   :element-type 'some-element-type :initial-element 0)
  ;; replaces my-array with its enlarged or shrunk version, keeping contents in place
  ;; and setting uninitialized elements to 0
#+end_src

** Installation
For now, you'll have to install [[http://dist.luckylambda.technology/releases/lucky-lambda/][LuckyLambda]] Quicklisp distribution (assuming you have [[https://quicklisp.org][Quicklisp]] installed) by executing the following in your Lisp :
#+begin_src lisp
  (ql-dist:install-dist "http://dist.luckylambda.technology/releases/lucky-lambda.txt")
#+end_src

Alternatively, just clone this repository to your [[http://blog.quicklisp.org/2018/01/the-quicklisp-local-projects-mechanism.html][Quicklisp's local-projects]] directory.

After that, just execute ~(ql:quickload :trivial-adjust-simple-array)~ in your Lisp.

** Supported implementations
This library is extremely portable and currently has been tested to work in following Common Lisp distributions:
- [[https://sbcl.org][SBCL]]
- [[https://cmucl.org][CMUCL]]
- [[https://ccl.clozure.com][CCL]]
- [[https://common-lisp.net/project/ecl][ECL]]
- [[https://mkcl.common-lisp.dev][MKCL]]
- [[https://abcl.org][ABCL]]
- [[https://clasp-developers.github.io][Clasp]]
- [[https://gitlab.com/gnu-clisp/clisp][CLISP]]
- [[https://franz.com/products/allegro-common-lisp][ACL]]
- [[https://lispworks.com][LispWorks]]

** Why?
Since its conception, Common Lisp had pretty advanced array types, which allowed:
- sharing data with other arrays (essentially providing /shallow copies/), called [[http://clhs.lisp.se/Body/26_glo_d.htm#displaced_array][displaced arrays]];
- changing number of elements without touching underlying storage, by using [[http://clhs.lisp.se/Body/26_glo_f.htm#fill_pointer][fill pointer]] feature;
- changing storage size on the fly without shuffling element data around with the help of [[http://clhs.lisp.se/Body/26_glo_e.htm#expressly_adjustable][expressed adjustability]] feature.

The problem is that on many Common Lisp implementations, even accessing elements of such fancy shmancy arrays is much slower compared to regular ~SIMPLE-ARRAY~ with no advanced features, which is demonstrated by the following benchmark program:

#+begin_src lisp
  (ql:quickload :trivial-benchmark)

  (defun sum-simple-array (array)
    (declare (type (simple-array (unsigned-byte 32)) array)
             (optimize (speed 3) (safety 0)))
    (loop :with s :of-type (unsigned-byte 32) := 0
          :for x :of-type (unsigned-byte 32) :across array
          :do (incf s x)
          :finally (return s)))

  (defun sum-advanced-array (array)
    (declare (type (array (unsigned-byte 32)) array)
             (optimize (speed 3) (safety 0)))
    (loop :with s :of-type (unsigned-byte 32) := 0
          :for x :of-type (unsigned-byte 32) :across array
          :do (incf s x)
          :finally (return s)))

  (let* ((size 5000)
         (simple-array (make-array size :element-type '(unsigned-byte 32)
                                        :initial-element 42))
         (advanced-array (make-array size :element-type '(unsigned-byte 32)
                                          :initial-element 42
                                          :fill-pointer size
                                          :adjustable t)))
    (trivial-benchmark:with-timing (10000)
      (sum-simple-array simple-array))
    (trivial-benchmark:with-timing (10000)
      (sum-advanced-array advanced-array)))
#+end_src

Here are some results of that benchmark (higher is worse):
| Lisp implementation | sum-simple-array total | sum-advanced-array total |
|---------------------+------------------------+--------------------------|
| SBCL 2.4.5          |                  0.034 |                    0.221 |
| Clozure CL 1.12.2   |                  0.207 |                    0.565 |
| ABCL 1.9.2          |                  0.111 |                    0.323 |
| Allegro CL 10.1     |                  0.337 |                    0.496 |
| LispWorks 8.0.1     |                  0.214 |                    0.362 |

As we can see, acessing simple arrays is in some cases almost order of magnitude faster. So it would've been nice to have the array with performance characteristics of ~SIMPLE-ARRAY~, yet sometimes occasionally reallocate it (for instance, to accomodate for more elements). Unfortunately, not all implementations keep arrays simple after call to [[http://clhs.lisp.se/Body/f_adjust.htm#adjust-array][ADJUST-ARRAY]], which can be demonstrated by the following bit of code:

#+begin_src lisp
  (print (type-of (adjust-array
                   (make-array 1 :element-type '(unsigned-byte 32)) 2
                   :element-type '(unsigned-byte 32))))
#+end_src

Not pointing fingers, but those implementations are ECL, MKCL, Clasp and Allegro CL. This is where this tiny library shines: it provides ~ADJUST-SIMPLE-ARRAY~ macro (to be used instead of ~ADJUST-ARRAY~) which is guaranteed to return simple array with old data. Besides, it provides super convenient ~ADJUST-SIMPLE-ARRAYF~ modify macro that can be used to reallocate simple array in-place.

** Copyright
Copyright (C) 2024 Andrew Kravchuk (awkravchuk@gmail.com)

** License
[[https://choosealicense.com/licenses/mit][MIT]]


alexandria

parachute

Test system for trivial-adjust-simple-array

trivial-adjust-simple-array

Upstream URL

Author

License

trivial-adjust-simple-array

Version:

License:

Authors:

Dependencies:

trivial-adjust-simple-array/tests

License:

Authors:

Dependencies:

Dependencies (2)

Dependents (1)