extra/compression/bzip3/bzip3-docs.factor

   1 ! Copyright (C) 2022 Raghu Ranganathan.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: byte-arrays help.markup help.syntax kernel multiline strings ;
   4 IN: compression.bzip3
   5
   6 HELP: compress
   7 { $values byte-array: byte-array block-size/f: { $maybe "integer" } byte-array': byte-array }
   8 { $description "Takes a byte array and block size, and pushes a compressed byte array from bzip3." } ;
   9
  10 HELP: decompress
  11 { $values byte-array: byte-array byte-array': byte-array }
  12 { $description Takes a valid bzip3 compressed byte array, and pushes its decompressed form. } ;
  13
  14 HELP: internal-error
  15 { $values msg: object }
  16 { $description Throws an { $link internal-error } error. }
  17 { $error-description A bzip3 internal error. Error type is indicated in { $snippet "msg" } . } ;
  18
  19 HELP: invalid-block-size
  20 { $values size: object }
  21 { $description Throws an  { $link invalid-block-size }  error. }
  22 { $error-description Occurs if the given "block" size for compression is not in the range of 65 KiB and 511 MiB. } ;
  23
  24 HELP: version
  25 { $values c-string: string }
  26 { $description Pushes the version info of the bzip3 release installed on your system. } ;
  27
  28 ARTICLE: "compression.bzip3" "Compressing data with bzip3"
  29 The { $vocab-link "compression.bzip3" } vocabulary can compress and decompress binary data with the help of the
  30 { $url "https://github.com/kspalaiologos/bzip3" "bzip3" } library. All data is represented in the form of { $link "byte-arrays" } .
  31
  32 bzip3 is best used with text or code, and hence the { $vocab-link "io.encodings" } vocabularies, specifically the
  33 { $link "io.encodings.string" } , { $vocab-link "io.encodings.utf8" } and { $vocab-link "io.encodings.ascii" } will be of help.
  34
  35 If you are an experienced user and would like to use the low level API of bzip3, the { $link "compression.bzip3.ffi" } library
  36 exposes the C bindings that allows for better performance via threading and other customizations. In order to use the functions
  37 imported you will need to use the { $vocab-link "alien" } vocabulary. ;
  38
  39 ABOUT: "compression.bzip3"