;;; vector-utils.el --- Vector-manipulation utility functions ;; ;; Copyright (c) 2012 Roland Walker ;; ;; Author: Roland Walker ;; Homepage: http://github.com/rolandwalker/vector-utils ;; URL: http://raw.github.com/rolandwalker/vector-utils/master/vector-utils.el ;; Package-Version: 0.1.2 ;; Version: 0.1.2 ;; Last-Updated: 24 Oct 2013 ;; EmacsWiki: VectorUtils ;; Keywords: extensions ;; ;; Simplified BSD License ;; ;;; Commentary: ;; ;; Quickstart ;; ;; (require 'vector-utils) ;; ;; (vector-utils-flatten '[1 2 [3 4 [5 6 7]]]) ;; ;; '[1 2 3 4 5 6 7] ;; ;; (vector-utils-depth '[1 2 [3 4 [5 6 7]]]) ;; ;; 3 ;; ;; Explanation ;; ;; Vector-utils is a collection of functions for vector manipulation. ;; This library has no user-level interface; it is only useful for ;; programming in Emacs Lisp. ;; ;; Furthermore (when programming in Emacs Lisp), be aware that the ;; modification of a vector is not permitted: only vector *elements* ;; may be changed. All "modification" operations herein can only ;; work by making copies, which is not efficient. ;; ;; The following functions are provided: ;; ;; `vector-utils-depth' ;; `vector-utils-flatten' ;; `vector-utils-insert-before' ;; `vector-utils-insert-after' ;; `vector-utils-insert-before-pos' ;; `vector-utils-insert-after-pos' ;; ;; To use vector-utils, place the vector-utils.el library somewhere ;; Emacs can find it, and add the following to your ~/.emacs file: ;; ;; (require 'vector-utils) ;; ;; Notes ;; ;; Compatibility and Requirements ;; ;; GNU Emacs version 24.4-devel : yes, at the time of writing ;; GNU Emacs version 24.3 : yes ;; GNU Emacs version 23.3 : yes ;; GNU Emacs version 22.2 : yes ;; GNU Emacs version 21.x and lower : unknown ;; ;; No external dependencies ;; ;; See Also ;; ;; Why you should not modify vectors ;; http://emacswiki.org/emacs/VectorUsage ;; ;; Bugs ;; ;; TODO ;; ;;; License ;; ;; Simplified BSD License: ;; ;; Redistribution and use in source and binary forms, with or ;; without modification, are permitted provided that the following ;; conditions are met: ;; ;; 1. Redistributions of source code must retain the above ;; copyright notice, this list of conditions and the following ;; disclaimer. ;; ;; 2. Redistributions in binary form must reproduce the above ;; copyright notice, this list of conditions and the following ;; disclaimer in the documentation and/or other materials ;; provided with the distribution. ;; ;; This software is provided by Roland Walker "AS IS" and any express ;; or implied warranties, including, but not limited to, the implied ;; warranties of merchantability and fitness for a particular ;; purpose are disclaimed. In no event shall Roland Walker or ;; contributors be liable for any direct, indirect, incidental, ;; special, exemplary, or consequential damages (including, but not ;; limited to, procurement of substitute goods or services; loss of ;; use, data, or profits; or business interruption) however caused ;; and on any theory of liability, whether in contract, strict ;; liability, or tort (including negligence or otherwise) arising in ;; any way out of the use of this software, even if advised of the ;; possibility of such damage. ;; ;; The views and conclusions contained in the software and ;; documentation are those of the authors and should not be ;; interpreted as representing official policies, either expressed ;; or implied, of Roland Walker. ;; ;;; Code: ;; ;;; requirements ;; for assert, subseq (require 'cl) ;;; customizable variables ;;;###autoload (defgroup vector-utils nil "Vector-manipulation utility functions." :version "0.1.2" :link '(emacs-commentary-link :tag "Commentary" "vector-utils") :link '(url-link :tag "GitHub" "http://github.com/rolandwalker/vector-utils") :link '(url-link :tag "EmacsWiki" "http://emacswiki.org/emacs/VectorUtils") :prefix "vector-utils-" :group 'extensions) ;;;###autoload (defun vector-utils-depth (vec) "Find the depth of vector VEC, which may contain other vectors. If VEC is not a vector or is an empty vector, returns a depth of 0. If VEC is vector which does not contain other vectors, returns a depth of 1." (cond ((or (not (vectorp vec)) (= 0 (length vec))) 0) (t (+ 1 (apply 'max (mapcar 'vector-utils-depth vec)))))) (defun vector-utils--flatten-1 (vec) "Driver for `vector-utils-flatten'. VEC is as documented at `vector-utils-flatten'." (cond ((and (vectorp vec) (= 0 (length vec))) vec) ((vectorp vec) (vconcat (vector-utils--flatten-1 (aref vec 0)) (vector-utils--flatten-1 (subseq vec 1 (length vec))))) (t (vector vec)))) ;;;###autoload (defun vector-utils-flatten (vec) "Flatten vector VEC, which may contain other vectors." (assert (vectorp vec) nil "VEC must be a vector") (vector-utils--flatten-1 vec)) ;;;###autoload (defun vector-utils-insert-before-pos (vec pos new-element) "Look in VEC for position POS, and insert NEW-ELEMENT before. POS is zero-indexed. A modified copy of VEC is returned." (assert (vectorp vec) nil "VEC must be a vector") (assert (and (integerp pos) (>= pos 0) (< pos (length vec))) nil "No such position %s" pos) (vconcat (subseq vec 0 pos) (vector new-element) (subseq vec pos (length vec)))) ;;;###autoload (defun vector-utils-insert-after-pos (vec pos new-element) "Look in VEC for position POS, and insert NEW-ELEMENT after. POS is zero-indexed. A modified copy of VEC is returned." (assert (vectorp vec) nil "VEC must be a vector") (assert (and (integerp pos) (>= pos 0) (< pos (length vec))) nil "No such position %s" pos) (vconcat (subseq vec 0 (1+ pos)) (vector new-element) (subseq vec (1+ pos) (length vec)))) ;;;###autoload (defun vector-utils-insert-before (vec element new-element) "Look in VEC for ELEMENT and insert NEW-ELEMENT before it. A modified copy of VEC is returned." (let ((pos (position element vec))) (assert pos nil "Element not found: %s" element) (vector-utils-insert-before-pos vec pos new-element))) ;;;###autoload (defun vector-utils-insert-after (vec element new-element) "Look in VEC for ELEMENT and insert NEW-ELEMENT after it. A modified copy of VEC is returned." (let ((pos (position element vec))) (assert pos nil "Element not found: %s" element) (vector-utils-insert-after-pos vec pos new-element))) (provide 'vector-utils) ;; ;; Emacs ;; ;; Local Variables: ;; indent-tabs-mode: nil ;; mangle-whitespace: t ;; require-final-newline: t ;; coding: utf-8 ;; byte-compile-warnings: (not cl-functions redefine) ;; End: ;; ;; LocalWords: VectorUtils devel utils subseq ;; ;;; vector-utils.el ends here