((section 2 "Outdated egg!" (p "This is an egg for CHICKEN 4, the unsupported old release.  You're almost certainly looking for " (int-link "/eggref/5/byte-blob" "the CHICKEN 5 version of this egg") ", if it exists.") (p "If it does not exist, there may be equivalent functionality provided by another egg; have a look at the " (link "https://wiki.call-cc.org/chicken-projects/egg-index-5.html" "egg index") ". Otherwise, please consider porting this egg to the current version of CHICKEN.") (tags "eggs") (toc)) (section 2 "byte-blob" (section 3 "Description" (p (tt "byte-blob") " aims to provide a SRFI-1-inspired API for manipulating byte vectors encoded as blobs. In addition it borrows inspiration from the Haskell " (link "http://hackage.haskell.org/package/bytestring-0.9.2.1/docs/Data-ByteString.html" "bytestring") " library.")) (section 3 "Library Procedures" (section 4 "Predicates" (def (sig (procedure "(byte-blob? X) => BOOL" (id byte-blob?))) (p "Returns " (tt "#t") " if the given object is a byte-blob, " (tt "#f") " otherwise.")) (def (sig (procedure "(byte-blob-empty? BYTE-BLOB) => BOOL" (id byte-blob-empty?))) (p "Returns " (tt "#t") " if the given byte-blob is empty, " (tt "#f") " otherwise."))) (section 4 "Constructors" (def (sig (procedure "(byte-blob-empty) => BYTE-BLOB" (id byte-blob-empty))) (p "Returns an empty byte-blob.")) (def (sig (procedure "(byte-blob-replicate N V) => BYTE-BLOB" (id byte-blob-replicate))) (p "Returns a byte-blob of length " (tt "N") ", where each element is " (tt "V") ".")) (def (sig (procedure "(byte-blob-cons X BYTE-BLOB) => BYTE-BLOB" (id byte-blob-cons))) (p "Analogous to list cons, but of complexity O(N), as it requires copying the elements of the byte-blob argument.")) (def (sig (procedure "(blob->byte-blob BLOB) => BYTE-BLOB" (id blob->byte-blob))) (p "Returns a byte-blob containing the elements of the given blob.")) (def (sig (procedure "(list->byte-blob LIST) => BYTE-BLOB" (id list->byte-blob))) (p "Returns a byte-blob containing the elements of " (tt "LIST") ".")) (def (sig (procedure "(string->byte-blob STRING) => BYTE-BLOB" (id string->byte-blob))) (p "Returns a byte-blob containing the elements of " (tt "STRING") "."))) (section 4 "Accessors" (def (sig (procedure "(byte-blob-length BYTE-BLOB) => INTEGER" (id byte-blob-length))) (p "Returns the number of elements contained in the given byte-blob.")) (def (sig (procedure "(byte-blob-car BYTE-BLOB) => X" (id byte-blob-car))) (p "Returns the first element of a byte-blob. The argument byte-blob must be non-empty, or an exception will be thrown.")) (def (sig (procedure "(byte-blob-cdr BYTE-BLOB) => BYTE-BLOB" (id byte-blob-cdr))) (p "Returns a byte-blob that contains the elements after the first element of the given byte-blob. The argument byte-blob must be non-empty, or an exception will be thrown.")) (def (sig (procedure "(byte-blob-ref BYTE-BLOB I) => BYTE" (id byte-blob-ref))) (p "Returns the i-th element of the given byte-blob as a signed byte.")) (def (sig (procedure "(byte-blob-uref BYTE-BLOB I) => BYTE" (id byte-blob-uref))) (p "Returns the i-th element of the given byte-blob as an unsigned byte."))) (section 4 "Transformers" (def (sig (procedure "(byte-blob-set! BYTE-BLOB I V) => VOID" (id byte-blob-set!))) (p "Sets the i-th element of the given byte-blob to the signed byte " (tt "V") ".")) (def (sig (procedure "(byte-blob-uset! BYTE-BLOB I V) => VOID" (id byte-blob-uset!))) (p "Sets the i-th element of the given byte-blob to the unsigned byte " (tt "V") ".")) (def (sig (procedure "(byte-blob-append BYTE-BLOB BYTE-BLOB) => BYTE-BLOB " (id byte-blob-append))) (p "Appends two byte-blobs together.")) (def (sig (procedure "(byte-blob-reverse BYTE-BLOB) => BYTE-BLOB" (id byte-blob-reverse))) (p "Returns a byte-blob that contains the elements of the given byte-blob in reverse order.")) (def (sig (procedure "(byte-blob-intersperse BYTE-BLOB BYTE) => BYTE-BLOB" (id byte-blob-intersperse))) (p "Returns a byte-blob with the given byte placed between the elements of the given byte-blob.")) (def (sig (procedure "(byte-blob-map F BYTE-BLOB) => BYTE-BLOB" (id byte-blob-map))) (p "Returns a byte-blob obtained by applying " (tt "F") " to each element of the given byte-blob.")) (def (sig (procedure "(byte-blob->blob BYTE-BLOB) => BLOB" (id byte-blob->blob))) (p "Returns the underlying Scheme blob object.")) (def (sig (procedure "(byte-blob->list BYTE-BLOB [F]) => LIST" (id byte-blob->list))) (p "Returns a list containing the elements of the given byte-blob. If procedure " (tt "F") " is provided as a second argument, it is applied to every element of the returned list.")) (def (sig (procedure "(byte-blob->string BYTE-BLOB) => STRING" (id byte-blob->string))) (p "Returns a string containing the elements of the given byte-blob."))) (section 4 "Subsequences" (def (sig (procedure "(byte-blob-take BYTE-BLOB N) => BYTE-BLOB" (id byte-blob-take))) (p "Returns the prefix of the given byte-blob of length " (tt "N") ".")) (def (sig (procedure "(byte-blob-drop BYTE-BLOB N) => BYTE-BLOB" (id byte-blob-drop))) (p "Returns the suffix of the given byte-blob after the first " (tt "N") " elements.")) (def (sig (procedure "(byte-blob-span BYTE-BLOB START END) => BYTE-BLOB" (id byte-blob-span))) (p "Returns the subsequence of the give byte-blob from position " (tt "START") " to position " (tt "END") "."))) (section 4 "Fold" (def (sig (procedure "(byte-blob-fold-left F INIT BYTE-BLOB) => VALUE" (id byte-blob-fold-left)) (procedure "(byte-blob-fold-right F INIT BYTE-BLOB) => VALUE" (id byte-blob-fold-right))) (p "Given a procedure of two arguments, a starting value, and a byte-blob, reduces the byte-blob using the supplied procedure, from left to right, or right to left, respectively."))) (section 4 "Find" (def (sig (procedure "(byte-blob-find NEEDLE HAYSTACK) => LIST" (id byte-blob-find))) (p "Finds all non-overlapping instances of the byte-blob " (tt "NEEDLE") " in the byte-blob " (tt "HAYSTACK") ". The first element of the returned list is the prefix of " (tt "HAYSTACK") " prior to any matches of " (tt "NEEDLE") ".  The second is a list of lists.") (p "The first element of each pair in the list is a span from the beginning of a match to the beginning of the next match, while the second is a span from the beginning of the match to the end of the input."))) (section 4 "I/O" (def (sig (procedure "(file->byte-blob FILENAME [MODE]) => BYTE-BLOB" (id file->byte-blob))) (p "Returns a byte-blob with the contents of the given file.") (p (tt "MODE") " is an optional argument that can be one of " (tt "#:text") " or " (tt "#:binary") " to specify text or binary mode on Windows.")) (def (sig (procedure "(byte-blob-read PORT N) => BYTE-BLOB" (id byte-blob-read))) (p "Reads a byte-blob of length " (tt "N") " from the given port.  Currently, the port must support the " (tt "port->fileno") " procedure, which means that string ports are not supported.")) (def (sig (procedure "(byte-blob-write PORT BYTE-BLOB) => UNDEFINED" (id byte-blob-write))) (p "Writes the given byte-blob to the given port.  Currently, the port must support the " (tt "port->fileno") " procedure, which means that string ports are not supported."))) (section 4 "SRFI-4 transformers" (def (sig (procedure "(u8vector->byte-blob   U8VECTOR) => BYTE-BLOB" (id u8vector->byte-blob)) (procedure "(s8vector->byte-blob   S8VECTOR) => BYTE-BLOB" (id s8vector->byte-blob)) (procedure "(u16vector->byte-blob  U16VECTOR) => BYTE-BLOB" (id u16vector->byte-blob)) (procedure "(s16vector->byte-blob  S16VECTOR) => BYTE-BLOB" (id s16vector->byte-blob)) (procedure "(u32vector->byte-blob  U32VECTOR) => BYTE-BLOB" (id u32vector->byte-blob)) (procedure "(s32vector->byte-blob  S32VECTOR) => BYTE-BLOB" (id s32vector->byte-blob)) (procedure "(f32vector->byte-blob  F32VECTOR) => BYTE-BLOB" (id f32vector->byte-blob)) (procedure "(f64vector->byte-blob  F64VECTOR) => BYTE-BLOB" (id f64vector->byte-blob)) (procedure "(byte-blob->u8vector  BYTE-BLOB) => U8VECTOR" (id byte-blob->u8vector)) (procedure "(byte-blob->s8vector  BYTE-BLOB) => S8VECTOR" (id byte-blob->s8vector)) (procedure "(byte-blob->u16vector BYTE-BLOB) => U16VECTOR" (id byte-blob->u16vector)) (procedure "(byte-blob->s16vector BYTE-BLOB) => S16VECTOR" (id byte-blob->s16vector)) (procedure "(byte-blob->u32vector BYTE-BLOB) => U32VECTOR" (id byte-blob->u32vector)) (procedure "(byte-blob->s32vector BYTE-BLOB) => S32VECTOR" (id byte-blob->s32vector)) (procedure "(byte-blob->f32vector BYTE-BLOB) => F32VECTOR" (id byte-blob->f32vector)) (procedure "(byte-blob->f64vector BYTE-BLOB) => F64VECTOR" (id byte-blob->f64vector)))))) (section 3 "Version History" (ul (li "1.18 Added optional mode argument to file->byte-blob (thanks to dthedens)") (li "1.17 Added documentation for byte-blob->blob procedure (reported by retroj)") (li "1.16 Remove files created by unit tests (thanks to mario)") (li "1.15 Fixes for issues #1037 and #1038 (thanks to dthedens)") (li "1.14 Bug fix in byte-blob-find") (li "1.13 Added byte-blob-uref and byte-blob-uset! (thanks to Panos Stergiotis)") (li "1.12 Fixed a bug in byte-blob-drop; added byte-blob-set! (thanks to Panos Stergiotis)") (li "1.11 Updated test script to return proper exit code") (li "1.9 Bug fix in byte-blob-find") (li "1.8 Changed (import posix) to (require-extension posix)") (li "1.7 Bug fix in byte-blob->string") (li "1.6 Added optional second argument to byte-blob->list") (li "1.5 Bug fixes in " (tt "byte-blob-read") " and " (tt "byte-blob-write")) (li "1.4 Added procedure " (tt "blob->byte-blob")) (li "1.3 Fix in invocation of chicken_Panic") (li "1.2 Added procedure " (tt "byte-blob-ref")) (li "1.0 Initial release"))) (section 3 "License" (p "Based on ideas from the Haskell " (link "http://hackage.haskell.org/package/bytestring-0.9.2.1/docs/Data-ByteString.html" "bytestring") " library.") (p "The code for " (tt "byte-blob-find") " is based on code from the Haskell Text library by Tom Harper and Bryan O'Sullivan.") (pre " Copyright 2009-2015 Ivan Raikov") (pre " This program is free software: you can redistribute it and/or modify\n it under the terms of the GNU Lesser General Public License as\n published by the Free Software Foundation, either version 3 of the\n License, or (at your option) any later version.") (pre " This program is distributed in the hope that it will be useful, but\n WITHOUT ANY WARRANTY; without even the implied warranty of\n MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU\n General Public License for more details.") (pre " A full copy of the GPL license can be found at\n <http://www.gnu.org/licenses/>."))))