README.md

   1 # cl-tuples - A set of macros for auto-generating optimised vector math routines
   2
   3 ## A tuple type declaration auto-generates a number of useful functions, macros, and types.
   4
   5 It is best to give an example.
   6
   7         (def-tuple-type vector2d
   8                 :tuple-element-type short-float
   9                 :initial-element 0.0f0
  10                 :elements (x y))
  11
  12 Will declare a tuple of short-floats, arrays of which are initialised
  13 with the element 0.0f0 and which has two elements, named x and y.
  14
  15 There will be a struct to represent this type, declared as follows:
  16
  17         (defstruct vector2d
  18                 :type vector
  19                 :constructor nil
  20                 (x 0.0f0 :type short-float)
  21                 (y 0.0f0 :type short-float))
  22
  23 i.e. a struct, stored as a vector with elements representing the
  24 elements of the tuple, initialised to the initial-element value of the
  25 tuple.
  26
  27 Literals can be written via the modified read syntax
  28
  29                 #[ vector2d 0.2 1.2 ] => #( 0.2 1.2 )
  30                 #[ vector2d* 0.2 1.2 ] => (values 0.2 1.2)
  31
  32 It is reccomended literals are written with the above syntax as their
  33 expansion will also incorportate type definitions that will be
  34 compatible with the following routines that will be generated to be
  35 able to manipulate them.
  36
  37         (vector2d-values* x y) => (values x y)          ;; convert from args to values
  38         (vector2d* v) => (values (aref v 0) (aref v 1)) ;; covert from array to values
  39         (new-vector2d)                                  ;; returns an empty tuple vector- i.e. #( 0 0 )
  40         (make-vector2d x y)                             ;; returns a vector (struct) as #( x y )
  41         (make-vector2d* (values x y))                   ;; same as the above only with multiple value arguments
  42         (setf (vector2d* v) (values x y) )              ;; generalised set that takes multiple values
  43         (with-vector2d v (i j) ...)                     ;; binds x and y of tuple vector v to i and j in the body
  44         (with-vector2d* (values x y) (i j) ..)          ;; same as the above, only it expects a values form
  45
  46         ;; arrays -- this can create an array  of n vector2ds (eg 4 vector2ds == 8 element array)
  47         (make-vector2d-array dimensons &key adjustable fill-pointer)
  48
  49         (vector2d-aref v  n)                                                ;; treats v as an array of n vector2d's and
  50                                                                                                     ;; returns the nth vector2d as a vector (ie
  51                                                                                                     ;; struct)
  52         (vector2d-aref* v n)                                                    ;; treats v as an array of n vector2d's and returns the
  53                                                                                                     ;; nth vector2 as multiple values
  54
  55         (setf (vector2d-aref v n) #( x y ))             ;; sets the n'tn vector2d in the array v
  56
  57         (setf (vector2d-aref v n) (values x y ))        ;; sets the n'tn vector2d in the array v, expects multiple
  58                                                                                                         ;; value argument
  59
  60      (vector2d-push #( x y ) v)                     ;; push an vector2d into an array of vector2d
  61          (vector2d-push*  (values x y) v)               ;; same as above but with multiple values
  62          (vector2d-push-extend #( x y ) v)              ;; as vector2d-push but admits the possiblity of extension
  63          (vector2d-push-extend* (values x y) v)         ;; same as above but takes multiple value arguments
  64
  65         (vector2d-fill-pointer v)                       ;; returns fill pointer
  66         (setf (vector2d-fill-pointer v) x)              ;; sets fill pointer
  67         (vector2d-array-dimensions v)                   ;; returns number of vector2d's array can hold
  68
  69 In addition a small convienince reader syntax is implemented - #{ x y
  70 z } is equivalent to (values x y z) as client code of this library is
  71 likely to manipulate many multiple values.
  72
  73 Note that the code cl-tuples generates is implementation agnostic: it
  74 is heavily predicated on the assumption that your implementation does
  75 a good job of optimising multiple value calls. If this is not the
  76 case, then the convienence of the array - related functions are
  77 probably the only good reason to use this library.