slice.lsp
 Version 1.00  31 October 2004
 Author  Steven Jones

 Contact jones57@swbell.net include the word "nyquist" in subject line

 The contents of this file are released under the terms of the GNU General
 Public License. See the file LICENSE.txt

 Provides python style list slicing and circular list functions

function

 (slice:from-end n lst) 
 Return the nth item from end of list. 
 Indexing starts with 1, that is an index of 1 corresponds to the final list
 element, an index of 2 to the second to last element etc.... Non-positive 
 indexes are invalid.

 n       - INTEGER. Index from end of list, n > 0. 
           If n is non-positive a bad argument error is raised. 
           If n is greater then list length the result is nil.

 lst     - LIST. The source list

 return  - OBJECT.

function

 (slice:nth   n lst)
 The slice version of nth. 
 For n >= 0 slice:nth is equivalent to the standard lisp nth
 function. For n negative the indexing is from end of list as in python.
 see slice:from-end

 n       - INTEGER. The index n negative, zero or positive.

 lst     - LIST. The source list.

 return  - OBJECT.

function

 (slice:sublist   start end lst)
 Extract sublist consisting of the elements from index start through 
 index end.

 start  - INTEGER. The starting index,  0 <= start.

 end    - INTEGER. The ending index, start <= end.

 lst    - LIST. The source list.

 return - LIST.

function

 (slice  lst [start [end]])
 Return Python style slice.
 Both start and end index arguments are optional. The exact behavior of the
 function is dependent on which indexing arguments are provided.

 (1) Both start and end index specified. start >= 0.
     (a) end < 0. Return sublist, negative indexing used for end.
     (b) 0 < end and start <= end, return sublist (start...end)
     (c) 0 < end < start, return NIL
 
 (2) Start index only specified.
     (a) |start| > (length lst), return NIL
     (b) start < 0, return single element using negative indexing.
     (c) start >= 0, return single element using positive indexing.
 
 (3) Start not specified, return NIL

 lst    - LIST. The source list.

 start  - INTEGER. The starting index. default: 0

 end    - INTEGER. The ending index. default: -1

 return - OBJECT.  The return item is either an atom or a sublist of lst

function

 (circular  n lst)
 Return the nth element from list in a circular manner. 
 Index n may be negative, zero or positive.

 n      - INTEGER. The index.

 lst    - LIST. The source list.

 return - OBJECT.

;; slice.lsp
;; Version 1.00  31 October 2004
;; Author  Steven Jones
;;
;; Contact jones57@swbell.net include the word "nyquist" in subject line
;;
;; The contents of this file are released under the terms of the GNU General
;; Public License. See the file LICENSE.txt
;;
;; Provides python style list slicing and circular list functions
;; 

(provide 'slice)
(current-file "slice")


;; @doc function slice:from-end
;; (slice:from-end n lst) 
;; Return the nth item from end of list. 
;; Indexing starts with 1, that is an index of 1 corresponds to the final list
;; element, an index of 2 to the second to last element etc.... Non-positive 
;; indexes are invalid.
;;
;; n       - INTEGER. Index from end of list, n > 0. 
;;           If n is non-positive a bad argument error is raised. 
;;           If n is greater then list length the result is nil.
;;
;; lst     - LIST. The source list
;;
;; return  - OBJECT.
;;

(defun slice:from-end (n lst)
  (nth (- n 1)(reverse lst)))


;; @doc function slice:nth 
;; (slice:nth   n lst)
;; The slice version of nth. 
;; For n >= 0 slice:nth is equivalent to the standard lisp nth
;; function. For n negative the indexing is from end of list as in python.
;; see slice:from-end
;;
;; n       - INTEGER. The index n negative, zero or positive.
;;
;; lst     - LIST. The source list.
;;
;; return  - OBJECT.
;;

(defun slice:nth  (n lst)
  (if (minusp n)
      (slice:from-end (abs n) lst)
    (nth n lst)))


;; @doc function slice:sublist
;; (slice:sublist   start end lst)
;; Extract sublist consisting of the elements from index start through 
;; index end.
;;
;; start  - INTEGER. The starting index,  0 <= start.
;;
;; end    - INTEGER. The ending index, start <= end.
;;
;; lst    - LIST. The source list.
;;
;; return - LIST.
;;

(defun slice:sublist (start end lst)
  (do ((index start (+ index 1))(acc ()))
      ((> index (min end (- (length lst) 1)))(reverse acc))
    (push (nth index lst) acc)))


;; Used to convert negative index to positive for use by 
;; slice:from-end
;;

(defun slice:_convert-negative-index (n lst)
  (if (minusp n)
      (- (length lst)(abs n))
    n))


;; @doc function slice 
;; (slice  lst [start [end]])
;; Return Python style slice.
;; Both start and end index arguments are optional. The exact behavior of the
;; function is dependent on which indexing arguments are provided.
;;
;; (1) Both start and end index specified. start >= 0.
;;     (a) end < 0. Return sublist, negative indexing used for end.
;;     (b) 0 < end and start <= end, return sublist (start...end)
;;     (c) 0 < end < start, return NIL
;; 
;; (2) Start index only specified.
;;     (a) |start| > (length lst), return NIL
;;     (b) start < 0, return single element using negative indexing.
;;     (c) start >= 0, return single element using positive indexing.
;; 
;; (3) Start not specified, return NIL
;;
;; lst    - LIST. The source list.
;;
;; start  - INTEGER. The starting index. default: 0
;;
;; end    - INTEGER. The ending index. default: -1
;;
;; return - OBJECT.  The return item is either an atom or a sublist of lst
;;

(defun slice (lst &optional start end)
  (cond ((and start end)(slice:sublist start (slice:_convert-negative-index end lst) lst))
	(start (slice:nth start lst))
	(t nil)))


;; @doc function circular
;; (circular  n lst)
;; Return the nth element from list in a circular manner. 
;; Index n may be negative, zero or positive.
;;
;; n      - INTEGER. The index.
;;
;; lst    - LIST. The source list.
;;
;; return - OBJECT.
;;

(defun circular (n lst)
  (let ((mod (length lst)))
    (if (zerop mod)
	nil
      (slice:nth (rem n mod) lst))))