; basic Scheme function syntax

; (define (funct-name param-name ... param-name)
;    expr
;    ...
;    expr
; )

; ...and the value returned by a call to this function
;    is the value of the last expr evaluated before it
;    exits

; a list is either:
;    *   '()   <-- the empty list (sometimes this is called nil)
;    *   (cons element list)

; NOTE -- aside -- for convenience, there is a way
;   to take n lists and create a list containing the elements
;   of those n lists:  append

(append '(1 2 3) '(4 5 6))
(append '( 1 2) '(2 3) '(4 5))

'((1 2) (3 4) (5 6))
'((1 (2 3)) (4 5) 6)

(equal? '(1 2 3)
        (cons 1 (cons 2 (cons 3 '()))))
(equal? (list 1 2 3)
        (cons 1 (cons 2 (cons 3 '()))))
(equal? (list 1 2 3)
        (append (list 1) (cons 2 (list 3))))

; you build a list using a first element and a list --
; car and cdr are kind of selectors for those two pieces,
;    car: expects a non-empty list and returns its first element
;    cdr: expects a non-empty list and returns the list of all but
;         the first element

; (and null? is a predicate function that returns true if
; its argument is an empty list)

; display will simply display the value of its argument
;    expression to the screen (that is its side-effect!!)
;    (it does NOT return anything...!)
(display (+ 3 5))
(display "\n")

; this does NOT work...
; (+ 1 (display (+ 3 5)))

(cdr '(3))  ; cdr ALWAYS produces a list!

; and being able to pull a list apart is quite
;    necessary for many recursive functions on lists...

; say I want a function that expects a list of numbers
;    and produces a new list, adding 1 to each of those numbers

; add-1-to-list: list-of-number -> list-of-number
; expects a list of numbers, and 
; produces a new list, adding 1 to each of those numbers

(define (add-1-to-list num-list)
  (cond
     ; when given the empty list, simply return an empty list
    
     ((null? num-list) '())
     
     ; otherwise... 
     
     (else
          (cons (+ 1 (car num-list))
                (add-1-to-list (cdr num-list))))
   )
)

(display "testing add-1-to-list: #t's mean passed\n")
(equal? (add-1-to-list (list 1 3 5))
        (list 2 4 6))
(equal? (add-1-to-list '())
        '())
(equal? (add-1-to-list (list 47))
        (list 48))

; basic template for recursion on lists...

; (define (list-funct a-list ...)
;     (cond
;        ((null? a-list) ...)
;        ...
;        (else ... (car a-list) ...
;                  (list-funct (cdr a-list) ...) ...)
;     )
; )

; a convenience:

; how can you find the 2nd element in a list of 2-or-more elements

(car (cdr (list 1 2 3 4 5 6)))

; List/Scheme lets you abbreviate that as cadr

(cadr (list 1 2 3 4 5 6))

(cadddr (list 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15))

; (R5RS Scheme limits you to 4 levels between the c and r! Rats!
; that's NOT true of all Lisp/Scheme versions...)

(cadaar (list (list (list 1 2 3) 4)
              (list (list 5 6) (list 7 8))
              (list 9 10)))
(car (cdr (car (car (list (list (list 1 2 3) 4)
                          (list (list 5 6) (list 7 8))
                          (list 9 10))))))

; remember: ALWAYS use car, cdr with NON-empty lists!!!

; MacLennan, Ch. 9. p. 337
; car and cdr come from the IBM 704 that Lisp was first
;    implemented on --
; (car l) -> Contents of the Address part of Register l
; (cdr l) -> Contents of the Decrement part of Register l

; see figures -- how Lisp lists are built using cons cells,
;    very simple linked lists;
; *   it is a constant-time operation to take the car of
;     a list (grab what its car part is pointing to);
; *   it is a consant-time operation to take the cdr of
;     a list (grab what its cdr part is pointing to);
; *   and for a cons, allocate a new cons cell,
;     make its car part point to the desired first element,
;     make its cdr part point to the desired rest-of-the-list;
; ...turns out to be very practical and efficient!
; (but there is that aspect of how you free a cons cell when
;    you are done with it -- McCarthy wanted the system to
;    take care of that, leading to garbage collection;
;    ...more on that later!)