Changeset 40453 in project


Ignore:
Timestamp:
09/08/21 16:21:58 (2 weeks ago)
Author:
Kon Lovett
Message:

rel 4.3.0

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/5/message-digest-utils

    r40444 r40453  
    1515something easily treated as a {{bytevector}}.
    1616
     17=== Common Argument Definitions
     18
     19{{RESULT-FORM}} is a {{message-digest-result-form}}, one of:
     20
     21; {{'blob}} : the result bytes as a blob.
     22; {{'u8vector}} : the result bytes as a u8vector.
     23; {{'hex-string}} {{'hex}} {{'hexstring}} : the result bytes encoded as a string of lower-case hexadecimal digits.
     24; {{'string}} {{'byte-string}} : DEPRECATED - the result bytes as a string; these are raw bytes, not necessarily characters!
     25
     26{{DIGEST}} is a {{message-digest}}.
     27
     28{{PRIM/DIGEST}} is a {{message-digest-primitive}} or a {{message-digest}}.
     29
     30{{ENDIAN}} is one of {{'big-endian}}, {{'little-endian}}.
     31
     32{{SOURCE}} is a Scheme object.
     33
     34The {{buffer}} argument for the update phase is translated as:
     35
     36; {{string}} : {{buffer}} is {{SOURCE}}.
     37; {{blob}} : {{buffer}} is {{SOURCE}}.
     38; {{srfi-4-vector}} : {{buffer}} from {{(...vector->blob/shared SOURCE)}}.
     39; {{procedure}} : updates with {{buffer}} from {{(procedure)}} until {{#f}}.
     40; {{input-port}} : like {{procedure}} above but from {{((message-digest-chunk-read-maker) SOURCE)}}.
     41; {{pointer}} : {{buffer}} is {{SOURCE}}, thru the digest primitive ''raw-update'' usually.
     42; {{*}} : {{buffer}} from {{(message-digest-chunk-converter SOURCE)}}.
     43
     44Should none of the above interpretations be available then an error is
     45signaled.
     46
     47A {{byte-source}} is one of {{string}}, {{blob}}, or {{srfi-4-vector}}.
     48
     49A {{message-digest-result-type}} is {{(or blob string u8vector)}}
     50
     51''Initialized'' here means the intialization phase is completed.
    1752
    1853=== Message Digest Byte Vector
     
    4075==== message-digest-string
    4176
    42 <procedure>(message-digest-string PRIM STRING [RESULT-FORM [START [END]]]) -> message-digest-result-type</procedure>
    43 
    44 Returns the {{RESULT}} for the digest algorithm {{PRIM}} applied to
     77<procedure>(message-digest-string PRIM/DIGEST STRING [RESULT-FORM [START [END]]]) -> message-digest-result-type</procedure>
     78
     79Returns the {{RESULT}} for the digest algorithm {{PRIM/DIGEST}} applied to
    4580{{STRING}}, optionally sliced by {{START END}}, in the {{RESULT-FORM}}.
    4681
     
    4984==== message-digest-blob
    5085
    51 <procedure>(message-digest-blob PRIM BLOB [RESULT-FORM [START [END]]]) -> message-digest-result-type</procedure>
    52 
    53 Returns the {{result}} for the digest algorithm {{PRIM}} applied to
     86<procedure>(message-digest-blob PRIM/DIGEST BLOB [RESULT-FORM [START [END]]]) -> message-digest-result-type</procedure>
     87
     88Returns the {{result}} for the digest algorithm {{PRIM/DIGEST}} applied to
    5489{{BLOB}}, optionally sliced by {{START END}}, in the {{RESULT-FORM}}.
    5590
     
    5893==== message-digest-string!
    5994
    60 <procedure>(message-digest-string! PRIM STRING BUFFER [START [END]]) -> message-digest-result-type</procedure>
    61 
    62 Returns the {{RESULT}} for the digest algorithm {{PRIM}} applied to
     95<procedure>(message-digest-string! PRIM/DIGEST STRING BUFFER [START [END]]) -> message-digest-result-type</procedure>
     96
     97Returns the {{RESULT}} for the digest algorithm {{PRIM/DIGEST}} applied to
    6398{{STRING}}, optionally sliced by {{START END}}, in the {{BUFFER}}.
    6499
    65100==== message-digest-blob!
    66101
    67 <procedure>(message-digest-blob! PRIM BLOB BUFFER [START [END]]) -> message-digest-result-type</procedure>
    68 
    69 Returns the {{result}} for the digest algorithm {{PRIM}} applied to
     102<procedure>(message-digest-blob! PRIM/DIGEST BLOB BUFFER [START [END]]) -> message-digest-result-type</procedure>
     103
     104Returns the {{result}} for the digest algorithm {{PRIM/DIGEST}} applied to
    70105{{BLOB}}, optionally sliced by {{START END}}, in the {{{BUFFER}}}.
    71106
     
    201236; {{THUNK}} : {{(-> (or BYTE-SOURCE false))}}
    202237; {{BYTE-SOURCE}} : {{(or string blob srfi-4-vector )}}
    203 
    204 <enscript highlight=scheme>
    205 ;simple example (from test suite)
    206 (import message-digest-item)
    207 (: just-once (-> (or string false)))
    208 (define just-once
    209   ;override most specific inferred type, true, w/ what is needed, boolean
    210   (let ((flag (the boolean #t)))
    211     (lambda ()
    212       (and flag (begin (set! flag #f) "ab cd")))))
    213 </enscript>
    214238
    215239==== message-digest-update-port
     
    252276==== message-digest-object
    253277
    254 <procedure>(message-digest-object PRIM SOURCE [RESULT-FORM [START [END]]]) -> message-digest-result-type</procedure>
    255 
    256 Returns the result for the digest algorithm {{PRIM}} applied to
     278<procedure>(message-digest-object PRIM/DIGEST SOURCE [RESULT-FORM [START [END]]]) -> message-digest-result-type</procedure>
     279
     280Returns the result for the digest algorithm {{PRIM/DIGEST}} applied to
    257281{{SOURCE}}, optionally sliced by {{START END}}, in the {{RESULT-FORM}}.
    258282
     
    261285==== message-digest-file
    262286
    263 <procedure>(message-digest-file PRIM FILENAME [RESULT-FORM]) -> message-digest-result-type</procedure>
    264 
    265 Returns the result for the digest algorithm {{PRIM}} applied to the file
     287<procedure>(message-digest-file PRIM/DIGEST FILENAME [RESULT-FORM]) -> message-digest-result-type</procedure>
     288
     289Returns the result for the digest algorithm {{PRIM/DIGEST}} applied to the file
    266290{{FILENAME}} in the {{RESULT-FORM}}. Reads until {{#!eof}} encountered.
    267291
     
    270294==== message-digest-port
    271295
    272 <procedure>(message-digest-port PRIM INPUT-PORT [RESULT-FORM]) -> message-digest-result-type</procedure>
    273 
    274 Returns the result for the digest algorithm {{PRIM}} applied to
     296<procedure>(message-digest-port PRIM/DIGEST INPUT-PORT [RESULT-FORM]) -> message-digest-result-type</procedure>
     297
     298Returns the result for the digest algorithm {{PRIM/DIGEST}} applied to
    275299{{INPUT-PORT}} in the {{RESULT-FORM}}. Reads until {{#!eof}} encountered.
    276300
     
    279303==== message-digest-object!
    280304
    281 <procedure>(message-digest-object! PRIM SOURCE BUFFER [START [END]]) -> message-digest-result-type</procedure>
    282 
    283 Returns the result for the digest algorithm {{PRIM}} applied to
     305<procedure>(message-digest-object! PRIM/DIGEST SOURCE BUFFER [START [END]]) -> message-digest-result-type</procedure>
     306
     307Returns the result for the digest algorithm {{PRIM/DIGEST}} applied to
    284308{{SOURCE}}, optionally sliced by {{START END}}, in the {{BUFFER}}.
    285309
    286310==== message-digest-file!
    287311
    288 <procedure>(message-digest-file! PRIM FILENAME BUFFER) -> message-digest-result-type</procedure>
    289 
    290 Returns the result for the digest algorithm {{PRIM}} applied to the file
     312<procedure>(message-digest-file! PRIM/DIGEST FILENAME BUFFER) -> message-digest-result-type</procedure>
     313
     314Returns the result for the digest algorithm {{PRIM/DIGEST}} applied to the file
    291315{{FILENAME}} in the {{BUFFER}}. Reads until {{#!eof}} encountered.
    292316
    293317==== message-digest-port!
    294318
    295 <procedure>(message-digest-port! PRIM INPUT-PORT BUFFER) -> message-digest-result-type</procedure>
    296 
    297 Returns the result for the digest algorithm {{PRIM}} applied to
     319<procedure>(message-digest-port! PRIM/DIGEST INPUT-PORT BUFFER) -> message-digest-result-type</procedure>
     320
     321Returns the result for the digest algorithm {{PRIM/DIGEST}} applied to
    298322{{INPUT-PORT}} in the {{BUFFER}}. Reads until {{#!eof}} encountered.
    299323
     
    317341==== message-digest-u8vector
    318342
    319 <procedure>(message-digest-u8vector PRIM U8VECTOR [RESULT-FORM [START [END]]]) -> message-digest-result-type</procedure>
    320 
    321 Returns the result for the digest algorithm {{PRIM}} applied to
     343<procedure>(message-digest-u8vector PRIM/DIGEST U8VECTOR [RESULT-FORM [START [END]]]) -> message-digest-result-type</procedure>
     344
     345Returns the result for the digest algorithm {{PRIM/DIGEST}} applied to
    322346{{U8VECTOR}}, optionally sliced by {{START END}}, in the {{RESULT-FORM}}.
    323347
     
    326350==== message-digest-u8vector!
    327351
    328 <procedure>(message-digest-u8vector! PRIM U8VECTOR BUFFER [START [END]]) -> message-digest-result-type</procedure>
    329 
    330 Returns the result for the digest algorithm {{PRIM}} applied to
     352<procedure>(message-digest-u8vector! PRIM/DIGEST U8VECTOR BUFFER [START [END]]) -> message-digest-result-type</procedure>
     353
     354Returns the result for the digest algorithm {{PRIM/DIGEST}} applied to
    331355{{U8VECTOR}}, optionally sliced by {{START END}}, in the {{BUFFER}}.
    332356
     
    355379==== open-output-digest
    356380
    357 <procedure>(open-output-digest PRIM) -> digest-output-port</procedure>
    358 
    359 Returns a message digest output port for the supplied algorithm {{PRIM}}.
     381<procedure>(open-output-digest PRIM/DIGEST) -> digest-output-port</procedure>
     382
     383Returns a message digest output port for the supplied algorithm {{PRIM/DIGEST}}.
    360384
    361385The initialization phase.
     
    373397==== call-with-output-digest
    374398
    375 <procedure>(call-with-output-digest PRIM PROC [RESULT-FORM]) -> message-digest-result-type</procedure>
     399<procedure>(call-with-output-digest PRIM/DIGEST PROC [RESULT-FORM]) -> message-digest-result-type</procedure>
    376400
    377401Returns the result of the call of {{PROC}} with an {{open-output-digest}} for
    378 {{PRIM}} in the {{RESULT-FORM}}.
     402{{PRIM/DIGEST}} in the {{RESULT-FORM}}.
    379403
    380404{{RESULT-FORM}} default is {{(message-digest-result-form)}}.
     
    382406==== with-output-to-digest
    383407
    384 <procedure>(with-output-to-digest PRIM THUNK [RESULT-FORM]) -> message-digest-result-type</procedure>
     408<procedure>(with-output-to-digest PRIM/DIGEST THUNK [RESULT-FORM]) -> message-digest-result-type</procedure>
    385409
    386410Invoke the procedure {{THUNK}} with {{(current-output-port)}} bound to a
     
    450474== Examples
    451475
    452 Uses the message-digest port abstraction to get an MD5 digest of a string:
    453 
    454 <enscript highlight=scheme>
    455 (import message-digest-port md5) ; Or sha1, or sha2, ...
     476<enscript highlight=scheme>
     477(import message-digest-port md5)
    456478
    457479(call-with-output-digest (md5-primitive) (cut display "foo" <>))
    458480;=> "acbd18db4cc2f85cedef654fccc4a4d8"
     481
     482(import miscmacros message-digest-type message-digest-byte-vector)
     483
     484(define (next-string) "generate another string")
     485
     486;for repeated digest operations, re-use the digest object
     487;lowers allocation & gc
     488(let ((md (setup-message-digest (md5-primitive))))
     489  (repeat 666 (message-digest-string md (next-string))) )
    459490</enscript>
    460491
     
    486517the existing public API.
    487518
    488 * Abstraction overhead (YMMV)
    489 
    490 <enscript highlight=scheme>
    491 ;macOS 10.15.6 w/ 3.2 GHz 6-Core Intel Core i7
    492 
    493 ;csc md-v-simple.scm -Dfile -Dsimple -o simple-file
    494 ;csc md-v-simple.scm -Dstring -Dsimple -o simple-string
    495 ;csc md-v-simple.scm -Dfile -Dmd -o md-file
    496 ;csc md-v-simple.scm -Dstring -Dmd -o md-string
    497 
    498 ;./simple-file
    499 ;=> Simple = 90bbbcbab37cde02d31e2955f1ab9e17becab506
    500 ;=> 2.207s CPU time, 4316/17 mutations (total/tracked), 0/2 GCs (major/minor), maximum live heap: 328.82 KiB
    501 
    502 ;./md-file
    503 ;=> MD = 90bbbcbab37cde02d31e2955f1ab9e17becab506
    504 ;=> 2.189s CPU time, 223/208 mutations (total/tracked), 0/1 GCs (major/minor), maximum live heap: 391.99 KiB
    505 
    506 ;./simple-string
    507 ;=> Simple = c62af4d8bd70d82bca1081f59f5372628f4742f5
    508 ;=> 0.053s CPU time, 431200/1688 mutations (total/tracked), 1/165 GCs (major/minor), maximum live heap: 330.45 KiB
    509 
    510 ;./md-string
    511 ;=> MD = c62af4d8bd70d82bca1081f59f5372628f4742f5
    512 ;=> 0.051s CPU time, 0.001s GC time (major), 37529/27733 mutations (total/tracked), 13/133 GCs (major/minor), maximum live heap: 414.04 KiB
    513 
    514 (import scheme (chicken base) (chicken time) miscmacros)
    515 
    516 (cond-expand
    517   (simple
    518     (import simple-sha1)
    519     (define *source* "Simple")
    520     (define-syntax digest-string (syntax-rules () ((digest-string ?str) (string->sha1sum ?str))))
    521     (define-syntax digest-file (syntax-rules () ((digest-file ?fl) (sha1sum ?fl)))))
    522   (md
    523     (import sha1 message-digest-byte-vector message-digest-item)
    524     (define *source* "MD")
    525     (define *sha1* (sha1-primitive))
    526     (define-syntax digest-string (syntax-rules () ((digest-string ?str) (message-digest-string *sha1* ?str))))
    527     (define-syntax digest-file (syntax-rules () ((digest-file ?fl) (message-digest-file *sha1* ?fl))))))
    528 
    529 (cond-expand
    530   (string
    531     (define *test-data* (make-string 1627 #\x))
    532     (define *reps* 10000)
    533     (define-syntax digest-data (syntax-rules () ((digest-data ?dat) (digest-string ?dat)))))
    534   (file
    535     ;11MB File
    536     (define *test-data* "The Periodic Table of Irrational Nonsense.jpg")
    537     (define *reps* 100)
    538     (define-syntax digest-data (syntax-rules () ((digest-data ?dat) (digest-file ?dat))))))
    539 
    540 (print *source* " = " (digest-data *test-data*))
    541 (time (repeat *reps* (digest-data *test-data*)))
    542 </enscript>
    543 
    544519
    545520== Requirements
     
    557532[[/users/kon-lovett|Kon Lovett]]
    558533
     534
    559535== Repository
    560536
     
    566542you are not familiar with Subversion, see [[/egg-svn-checkout|this page]].
    567543
     544
    568545== Version history
    569546
     547; 4.3.0 : Support {{message-digest}} re-use. Fix {{with-output-to-digest}}/{{call-with-output-digest}}.
    570548; 4.2.7 : Fix dependency versions.
    571549; 4.2.6 : Fewer heap operations for string digests.
Note: See TracChangeset for help on using the changeset viewer.