Streams 0.2 - beta testing started. Good replacement for NewBinary and System.IO?

[Bulat Ziganshin]

Hello all

i'm going to beta testing of Streams 0.2 library. compared to
previous version, it works several times faster, supports
memory-mapped files, has more orthogonal API and numerous internal
changes. moreover, it can be a great replacement for NewBinary and
System.IO modules (more on this below)


=== For users of Streams 0.1 library ===

new version is not yet documented, and that is not big problem, because
at this moment i'm mostly interested in testing it as replacement of
previous library version. if you already use Streams, please check
that with new version everything is still ok

comparing to Streams 0.1, there a few API changes:

- with* stream transformers renamed to add*:
    withEncoding should be changed to addEncoding
    withLocking        -> addLocking
    bufferBlockStream  -> "addBuffering >>= addInlining"
    bufferMemoryStream -> addInlining

- with* functions now has more regular names:
    withEncoding'      -> withEncoding
    withLocking'       -> withLocking
    withBuffering      -> "withBuffering $ \h -> withInlining h"
    withMemBuffering   -> withBuffering

- in binary i/o, upper-case LE/BE suffixes now used in all functions:
    putWord16be -> putWord16BE
    getWord64le -> getWord64LE
    and so on

- custom serialization routines for arrays, lists and strings now has
    more regular names, look at comment titled "Serialization for arrays
    of different types" in Data.AltBinary.Custom.Array module

- Stream class now split into the Stream, BlockStream, MemoryStream,
ByteStream and TextStream classes; MemoryStream interface is slightly changed

if i missed something that breaks backward compatibility - please let
me know. and please, find the time and try new library version with
your code before the library will be released



=== As replacement for NewBinary library and various Binary modules ===

Streams 0.2 includes full emulation of NewBinary library API. If you
already use one of these modules in your program, just replace
"import NewBinary.Binary" with "import Data.AltBinary" and enjoy! all
the differences i know is:

- argument order in "putBits" are different, my order is more
convenient for partial application

- format of written data is incompatible between libraries. on the
other side, data format used in my lib is CPU-independent, so you can
write data on 32-bit CPU and then read them back on 64-bit one

One of most pleasing features of this emulation is that it works
from several to several tens times faster than original :)



=== As (particular) replacement for System.IO module ===

If you are interested in getting several times speed improvement, you
can try to replace "import System.IO" in your program with
"import System.Stream.IO"

depending on how you are lucky, this may or may not work. Currently
this emulation don't supports LineBuffering and NoBuffering, and
several functions (hLookAhead, hTellPos...). Support for
stdin/stdout/stderr and appropriate functions are also disabled due to
lack of LineBuffering support. if you really need to use them, do it
through the regular Streams interface (read Example/wc.hs for details)



=== Downloading and installation ===

To install the library, you first need to install ArrayRef library:

Download: http://www.haskell.org/library/ArrayRef.tar.gz
Installation: run "make install"

- Optionally, you can also add support for ByteStrings:
- Download FPS 0.7 from repository (it's not yet released):
-   darcs get --partial http://www.cse.unsw.edu.au/~dons/code/fps
- Compile and install it:
-   runhaskell Setup.hs configure
-   runhaskell Setup.hs make
-   runhaskell Setup.hs install

Download: http://www.haskell.org/library/StreamsBeta.tar.gz
- If you installed FPS library, rename Streams.cabal.fps into the Streams.cabal
Installation: run "make install"


OLD version docs: http://haskell.org/haskellwiki/Library/Streams


-- 
Best regards,
 Bulat                          mailto:Bulat.Ziganshin at gmail.com