core/checksums/checksums-docs.factor

   1 USING: help.markup help.syntax kernel math sequences quotations
   2 math.private byte-arrays strings ;
   3 IN: checksums
   4
   5 HELP: checksum
   6 { $class-description "The class of checksum algorithms." } ;
   7
   8 HELP: hex-string
   9 { $values { "seq" "a sequence" } { "str" "a string" } }
  10 { $description "Converts a sequence of values from 0-255 to a string of hex numbers from 0-ff." }
  11 { $examples
  12     { $example "USING: checksums io ;" "B{ 1 2 3 4 } hex-string print" "01020304" }
  13 }
  14 { $notes "Numbers are zero-padded on the left." } ;
  15
  16 HELP: checksum-stream
  17 { $values { "stream" "an input stream" } { "checksum" "a checksum specifier" } { "value" byte-array } }
  18 { $contract "Computes the checksum of all data read from the stream." }
  19 { $side-effects "stream" } ;
  20
  21 HELP: checksum-bytes
  22 { $values { "bytes" "a sequence of bytes" } { "checksum" "a checksum specifier" } { "value" byte-array } }
  23 { $contract "Computes the checksum of all data in a sequence." } ;
  24
  25 HELP: checksum-lines
  26 { $values { "lines" "a sequence of sequences of bytes" } { "checksum" "a checksum specifier" } { "value" byte-array } }
  27 { $contract "Computes the checksum of all data in a sequence." } ;
  28
  29 HELP: checksum-file
  30 { $values { "path" "a pathname specifier" } { "checksum" "a checksum specifier" } { "value" byte-array } }
  31 { $contract "Computes the checksum of all data in a file." } ;
  32
  33 ARTICLE: "checksums" "Checksums"
  34 "A " { $emphasis "checksum" } " is a function mapping sequences of bytes to fixed-length strings. While checksums are not one-to-one, a good checksum should have a low probability of collision. Additionally, some checksum algorithms are designed to be hard to reverse, in the sense that finding an input string which hashes to a given checksum string requires a brute-force search."
  35 $nl
  36 "Checksums are instances of a class:"
  37 { $subsection checksum }
  38 "Operations on checksums:"
  39 { $subsection checksum-bytes }
  40 { $subsection checksum-stream }
  41 { $subsection checksum-lines }
  42 "Checksums should implement at least one of " { $link checksum-bytes } " and " { $link checksum-stream } ". Implementing " { $link checksum-lines } " is optional."
  43 $nl
  44 "Utilities:"
  45 { $subsection checksum-file }
  46 { $subsection hex-string }
  47 "Checksum implementations:"
  48 { $subsection "checksums.crc32" }
  49 { $vocab-subsection "MD5 checksum" "checksums.md5" }
  50 { $vocab-subsection "SHA checksums" "checksums.sha" }
  51 { $vocab-subsection "Adler-32 checksum" "checksums.adler-32" }
  52 { $vocab-subsection "OpenSSL checksums" "checksums.openssl" } ;
  53
  54 ABOUT: "checksums"