doc/mem-vector.txt

   1
   2 # Block Memory Operations
   3
   4 Function: mem-fill ptr type count value &optional (offset 0)
   5
   6 Fill COUNT objects of TYPE, starting at PTR plus offset, with VALUE.
   7
   8 ;; Equivalent to (but possibly more efficient than):
   9 (loop for i below count
  10       for off from offset by (%foreign-type-size type)
  11       do (setf (%mem-ref ptr type off) value))
  12
  13 Function: mem-read-vector vector ptr type count &optional (offset 0)
  14
  15 Copy COUNT objects of TYPE from foreign memory at PTR plus OFFSET into
  16 VECTOR.  If VECTOR is not large enough to contain COUNT objects, it
  17 will copy as many objects as necessary to fill the vector.  The
  18 results are undefined if the foreign memory block is not large enough
  19 to supply the data to copy.
  20
  21 TYPE must be a built-in foreign type (integer, float, double, or
  22 pointer).
  23
  24 Returns the number of objects copied.
  25
  26 ;; Equivalent to (but possibly more efficient than):
  27 (loop for i below (min count (length vector))
  28       for off from offset by (%foreign-type-size type)
  29       do (setf (aref vector i) (%mem-ref ptr type off))
  30       finally (return i))
  31
  32
  33 Function: mem-read-c-string string ptr &optional (offset 0)
  34
  35 Copy a null-terminated C string from PTR plus OFFSET into STRING, a
  36 Lisp string.  If STRING is not large enough to contain the data at PTR
  37 it will be truncated.
  38
  39 Returns the number of characters copied into STRING.
  40
  41 ;; Equivalent to (but possibly more efficient than):
  42 (loop for i below (length string)
  43       for off from offset
  44       for char = (%mem-ref ptr :char off)
  45       until (zerop char)
  46       do (setf (char string i) char)
  47       finally (return i))
  48
  49 Function: mem-write-vector vector ptr type &optional
  50                            (count (length vector)) (offset 0)
  51
  52 Copy COUNT objects from VECTOR into objects of TYPE in foreign memory,
  53 starting at PTR plus OFFSET.  The results are undefined if PTR does
  54 not point to a memory block large enough to hold the data copied.
  55
  56 TYPE must be a built-in type (integer, float, double, or pointer).
  57
  58 Returns the number of objects copied from VECTOR to PTR.
  59
  60 ;; Equivalent to (but possibly more efficient than):
  61 (loop for i below count
  62       for off from offset by (%foreign-type-size type)
  63       do (setf (%mem-ref ptr type off) (aref vector i))
  64       finally (return i))
  65
  66
  67 Function: mem-write-c-string string ptr &optional (offset 0)
  68
  69 Copy the characters from a Lisp STRING to PTR plus OFFSET, adding a
  70 final null terminator at the end.  The results are undefined if the
  71 memory at PTR is not large enough to accomodate the data.
  72
  73 This interface is currently equivalent to MEM-WRITE-VECTOR with a TYPE
  74 of :CHAR, but will be useful when proper support for Unicode strings
  75 is implemented.