OSCL/md5
2
0
Fork 0
mirror of https://github.com/pmai/md5.git synced 2025-12-22 06:54:30 +01:00
Code Issues Packages Projects Releases Wiki Activity

Change docstrings to match suggested usage, regularize formatting.

Browse Source
This commit is contained in:
Pierre R. Mai
2012-10-23 11:07:05 +02:00
parent 072add4c26
commit 56bc82ba0d
1 changed files with 34 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
md5.lisp
View File

@ -348,7 +348,7 @@ accordingly."
(declaim (inline fill-block fill-block-ub8 fill-block-char)) (declaim (inline fill-block fill-block-ub8 fill-block-char))
(defun fill-block-ub8 (block buffer offset) (defun fill-block-ub8 (block buffer offset)
"Convert a complete 64 (unsigned-byte 8) input vector segment "Convert a complete 64 (unsigned-byte 8) input vector segment
starting from offset into the given 16 word MD5 block." starting from `offset' into the given 16 word MD5 block."
(declare (type (integer 0 #.(- most-positive-fixnum 64)) offset) (declare (type (integer 0 #.(- most-positive-fixnum 64)) offset)
(type md5-block block) (type md5-block block)
(type (simple-array (unsigned-byte 8) (*)) buffer) (type (simple-array (unsigned-byte 8) (*)) buffer)
@ -373,8 +373,8 @@ starting from offset into the given 16 word MD5 block."
(aref buffer (+ j 3)))))) (aref buffer (+ j 3))))))
(defun fill-block-char (block buffer offset) (defun fill-block-char (block buffer offset)
"Convert a complete 64 character input string segment starting from "DEPRECATED: Convert a complete 64 character input string segment
offset into the given 16 word MD5 block." starting from `offset' into the given 16 word MD5 block."
(declare (type (integer 0 #.(- most-positive-fixnum 64)) offset) (declare (type (integer 0 #.(- most-positive-fixnum 64)) offset)
(type md5-block block) (type md5-block block)
(type simple-string buffer) (type simple-string buffer)
@ -402,7 +402,8 @@ offset into the given 16 word MD5 block."
"Convert a complete 64 byte input vector segment into the given 16 "Convert a complete 64 byte input vector segment into the given 16
word MD5 block. This currently works on (unsigned-byte 8) and word MD5 block. This currently works on (unsigned-byte 8) and
character simple-arrays, via the functions `fill-block-ub8' and character simple-arrays, via the functions `fill-block-ub8' and
`fill-block-char' respectively." `fill-block-char' respectively. Note that it will not work correctly
on character simple-arrays if `char-code-limit' is greater than 256."
(declare (type (integer 0 #.(- most-positive-fixnum 64)) offset) (declare (type (integer 0 #.(- most-positive-fixnum 64)) offset)
(type md5-block block) (type md5-block block)
(type (simple-array * (*)) buffer) (type (simple-array * (*)) buffer)
@ -419,7 +420,7 @@ character simple-arrays, via the functions `fill-block-ub8' and
(declaim (inline md5regs-digest)) (declaim (inline md5regs-digest))
(defun md5regs-digest (regs) (defun md5regs-digest (regs)
"Create the final 16 byte message-digest from the MD5 working state "Create the final 16 byte message-digest from the MD5 working state
in regs. Returns a (simple-array (unsigned-byte 8) (16))." in `regs'. Returns a (simple-array (unsigned-byte 8) (16))."
(declare (optimize (speed 3) (safety 0) (space 0) (debug 0) (declare (optimize (speed 3) (safety 0) (space 0) (debug 0)
#+lw-int32 (float 0) #+lw-int32 (hcl:fixnum-safety 0)) #+lw-int32 (float 0) #+lw-int32 (hcl:fixnum-safety 0))
(type md5-regs regs)) (type md5-regs regs))
@ -458,9 +459,9 @@ in regs. Returns a (simple-array (unsigned-byte 8) (16))."
(declaim (inline copy-to-buffer)) (declaim (inline copy-to-buffer))
(defun copy-to-buffer (from from-offset count buffer buffer-offset) (defun copy-to-buffer (from from-offset count buffer buffer-offset)
"Copy a partial segment from input vector from starting at "Copy a partial segment from input vector `from' starting at
from-offset and copying count elements into the 64 byte buffer `from-offset' and copying `count' elements into the 64 byte buffer
starting at buffer-offset." starting at `buffer-offset'."
(declare (optimize (speed 3) (safety 0) (space 0) (debug 0) (declare (optimize (speed 3) (safety 0) (space 0) (debug 0)
#+lw-int32 (float 0) #+lw-int32 (hcl:fixnum-safety 0)) #+lw-int32 (float 0) #+lw-int32 (hcl:fixnum-safety 0))
(type (unsigned-byte 29) from-offset) (type (unsigned-byte 29) from-offset)
@ -494,9 +495,13 @@ starting at buffer-offset."
from-index)))))) from-index))))))
(defun update-md5-state (state sequence &key (start 0) (end (length sequence))) (defun update-md5-state (state sequence &key (start 0) (end (length sequence)))
"Update the given md5-state from sequence, which is either a "Update the given md5-state from `sequence', which is either a
simple-string or a simple-array with element-type (unsigned-byte 8), simple-string or a simple-array with element-type (unsigned-byte 8),
bounded by start and end, which must be numeric bounding-indices." bounded by `start' and `end', which must be numeric bounding-indices.
Note that usage on simple-strings is DEPRECATED, since this will not
work correctly if `char-code-limit' is more than 256. String input
should be converted to (unsigned-byte 8) simple-arrays with
external-format conversion routines beforehand."
(declare (type md5-state state) (declare (type md5-state state)
(type (simple-array * (*)) sequence) (type (simple-array * (*)) sequence)
(type fixnum start end) (type fixnum start end)
@ -613,10 +618,13 @@ The resulting MD5 message-digest is returned as an array of sixteen
;;; High-Level Drivers ;;; High-Level Drivers
(defun md5sum-sequence (sequence &key (start 0) end) (defun md5sum-sequence (sequence &key (start 0) end)
"Calculate the MD5 message-digest of data in sequence. On CMU CL "Calculate the MD5 message-digest of data in `sequence', which should
this works for all sequences whose element-type is supported by the be a 1d simple-array with element type (unsigned-byte 8). On CMU CL
underlying MD5 routines, on other implementations it only works for 1d and SBCL non-simple and non-1d arrays with this element-type are also
simple-arrays with such element types." supported. Use with strings is DEPRECATED, since this will not work
correctly on implementations with `char-code-limit' > 256 and ignores
character-coding issues. Use md5sum-string instead, or convert to the
required (unsigned-byte 8) format through other means before-hand."
(declare (optimize (speed 3) (safety 3) (space 0) (debug 1)) (declare (optimize (speed 3) (safety 3) (space 0) (debug 1))
(type vector sequence) (type fixnum start)) (type vector sequence) (type fixnum start))
(locally (locally
@ -645,10 +653,12 @@ simple-arrays with such element types."
(finalize-md5-state state)))) (finalize-md5-state state))))
(defun md5sum-string (string &key (external-format :default) (start 0) end) (defun md5sum-string (string &key (external-format :default) (start 0) end)
"Calculate the MD5 message-digest of the binary representation "Calculate the MD5 message-digest of the binary representation of
of STRING (as octets) in EXTERNAL-FORMAT. The boundaries START `string' (as octets) in the external format specified by
and END refer to character positions in the string, not to octets `external-format'. The boundaries `start' and `end' refer to character
in the resulting binary representation." positions in the string, not to octets in the resulting binary
representation. The permissible external format specifiers are
determined by the underlying implementation."
(declare (optimize (speed 3) (safety 3) (space 0) (debug 1)) (declare (optimize (speed 3) (safety 3) (space 0) (debug 1))
(type string string) (type fixnum start)) (type string string) (type fixnum start))
(locally (locally
@ -688,14 +698,16 @@ in the resulting binary representation."
(eval-when (:compile-toplevel :load-toplevel :execute) (eval-when (:compile-toplevel :load-toplevel :execute)
(defconstant +buffer-size+ (* 128 1024) (defconstant +buffer-size+ (* 128 1024)
"Size of internal buffer to use for md5sum-stream and md5sum-file "Size of internal buffer to use for `md5sum-stream' and `md5sum-file'
operations. This should be a multiple of 64, the MD5 block size.")) operations. This should be a multiple of 64, the MD5 block size."))
(deftype buffer-index () `(integer 0 ,+buffer-size+)) (deftype buffer-index () `(integer 0 ,+buffer-size+))
(defun md5sum-stream (stream) (defun md5sum-stream (stream)
"Calculate an MD5 message-digest of the contents of stream. Its "Calculate an MD5 message-digest of the contents of `stream'. Its
element-type has to be either (unsigned-byte 8) or character." element-type has to be (unsigned-byte 8). Use on character streams is
DEPRECATED, as this will not work correctly on implementations with
`char-code-limit' > 256 and ignores character coding issues."
(declare (optimize (speed 3) (safety 3) (space 0) (debug 1))) (declare (optimize (speed 3) (safety 3) (space 0) (debug 1)))
(locally (locally
(declare (optimize (safety 1) (debug 0))) (declare (optimize (safety 1) (debug 0)))
@ -725,7 +737,7 @@ element-type has to be either (unsigned-byte 8) or character."
(stream-element-type stream) stream)))))) (stream-element-type stream) stream))))))
(defun md5sum-file (pathname) (defun md5sum-file (pathname)
"Calculate the MD5 message-digest of the file specified by pathname." "Calculate the MD5 message-digest of the file specified by `pathname'."
(declare (optimize (speed 3) (safety 3) (space 0) (debug 1))) (declare (optimize (speed 3) (safety 3) (space 0) (debug 1)))
(with-open-file (stream pathname :element-type '(unsigned-byte 8)) (with-open-file (stream pathname :element-type '(unsigned-byte 8))
(md5sum-stream stream))) (md5sum-stream stream)))