UT/UT_IStream.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * Produced by:
 *      Side Effects Software Inc
 *      123 Front Street West, Suite 1401
 *      Toronto, Ontario
 *      Canada   M5J 2M2
 *      416-504-9876
 *
 * NAME:        UT_IStream.h ( UT Library, C++)
 *
 * COMMENTS:    Since the semantics of C++ streams leave a little bit to be
 *              desired, this class provides an efficient mechanism to read
 *              streams line by line.
 *
 *              However, since this class buffers the stream input itself, it's
 *              not safe to use the stream outside of the class.
 */

#ifndef __UT_IStream__
#define __UT_IStream__

#include "UT_API.h"
#include <iostream.h>
#include <fstream.h>
#include <stdio.h>
#include <string.h>
#include <SYS/SYS_Types.h>
#include "UT_WorkBuffer.h"
#include "UT_IntArray.h"
#include "UT_PtrArray.h"

class UT_String;
class UT_IStreamBuf;

typedef enum {
    UT_ISTREAM_ASCII=0,         // Ascii stream
    UT_ISTREAM_BINARY
} UT_ISTREAM_READTYPE;

//
// When saving/loading binary strings, we store the run length of the string
// prior to saving the string data.  This enum specifies the minimum value
// possible for the run-length.
//
// It is somewhat dangerous to use 8 bit lengths.
//
typedef enum {
    UT_ISTREAM_8BIT_IO = 8,
    UT_ISTREAM_16BIT_IO = 16,
    UT_ISTREAM_32BIT_IO = 32,
    UT_ISTREAM_64BIT_IO = 64
} UT_ISTREAM_RLE_IO;

class UT_API UT_IStream {
public:
             UT_IStream(FILE *fp,
                        UT_ISTREAM_READTYPE binary=UT_ISTREAM_BINARY);
             UT_IStream(istream &is,
                        UT_ISTREAM_READTYPE binary=UT_ISTREAM_BINARY);
             UT_IStream(const char *buffer, int bufsize,
                        UT_ISTREAM_READTYPE binary);

             UT_IStream(const UT_WorkBuffer &buffer,
                        UT_ISTREAM_READTYPE binary=UT_ISTREAM_ASCII);
    virtual ~UT_IStream();

    // Typically, when reading from a non-tty stdin, istreams are able to
    // buffer the contents.  However, in some cases, when there's a
    // controlling application sending commands sporadically, it's important
    // to set compatibility on stdin.  This will result in slightly slower
    // input and should only be used when required.
    static void         setStdinCompatible(bool state);

    enum {
        UT_SEEK_BEG=0,  // Seek from beginning of stream
        UT_SEEK_CUR=1,  // Seek from current location
        UT_SEEK_END=2   // Seek from the end of the stream
    };

    /// Query or seek to a position in the stream.  Please see documentation
    /// for standard istreams for further information.
    int64       tellg() const;
    bool        seekg(int64 pos, int seekdir=UT_SEEK_BEG);

    // Returns true if the stream is out of data OR if there's an error on the
    // stream.
    bool        isEof() const;

    // Return the error status.
    bool        isError() const         { return myError; }

    bool        isAscii() const         { return !myBinary; }
    bool        isBinary() const        { return myBinary; }

    /// The version information can be used to stash version information with
    /// the stream itself rather than having to pass the version information
    /// through to all other loading methods.  This is used primarily in
    /// geometry loading.
    void        setVersion(int version) { myVersion = version; }
    int         getVersion() const      { return myVersion; }

    /// The label methods provide a way to give the stream a label which is
    /// used to identify the stream in error messages.  For example,
    /// UT_IFStream sets the label to the filename.
    void         setLabel(const char *label);
    const char  *getLabel() const       { return myLabel ? myLabel : ""; }

    /// The read() methods use the binary state of the stream to determine
    /// whether to read ASCII or binary values.  Rather than calling this
    /// method directly, it would be better to create a UT_IStreamAutoBinary,
    /// which will automatically pop the state on its destruction.
    void        pushBinary(UT_ISTREAM_READTYPE binary);
    void        popBinary();

    /// For error handling.  If an error occurs on the stream, the operation
    /// will be added to the error message (i.e. "loading image").  Rather
    /// than calling this method directly, it would probably be better to use
    /// UT_IStreamAutoOp which automatically pops the operation.
    void        pushOperation(const char *operation);
    void        popOperation();

    // Set a sub-range of the stream.  The stream will automatically seek the
    // the start position specified.  The stream will hit EOF when nbytes have
    // been read from the stream.  Seeking should work (assertions will be
    // triggered if the seek is out of bounds).  Absolute seek positions are
    // specified based on the original stream.
    UT_IStreamBuf       *getStreamBuffer()      { return myStream; }
    UT_IStream          *getSubStream(int64 start, int64 nbytes);

    // The zlib and gzip streams are available for zlib and gzip compression.
    // The difference between zlib and gzip is subtle, but very important.
    //  - zlib compression uses the zlib library to perform inflation of the
    //          data.  However, the bit window specified is slightly different
    //          than for gzip compression.
    //  - gzip compression uses the zlib library to perform inflation of the
    //          data.  However, it expects that the data has a gzip header
    //          before the compressed data begins.  As well, the window size is
    //          slightly different than raw zlib compression.
    UT_IStream          *getZlibStream();
    UT_IStream          *getGzipStream();

    bool        getLine(UT_WorkBuffer &buffer, int end='\n');
    bool        skipLine(int end='\n');
    bool        getWord(UT_WorkBuffer &buffer);
    bool        getString(UT_WorkBuffer &buffer);
    bool        skipLeadingWhitespace();

    /// Reads in the entire stream from the current position to the end.
    /// Returns true if anything was read in, false otherwise.  Use
    /// isError() to test error state.
    bool        getAll(UT_WorkBuffer &buffer);

    /// Skips all the comment lines and reads the next token in the stream.
    /// Returns true if successful and false otherwise.
    bool        getNonCommentWord(UT_WorkBuffer &buffer, int comment='#');

    /// Skips all the comment lines and reads the next line in the stream.
    /// Returns the number of lines read.  Note that the resulting line will
    /// be stripped of leading white space as well.  The 
    /// strip_inline_comments argument determines whether or not the resulting
    /// line should have comments at the end, if any, stripped.
    int         getNonCommentLine(UT_WorkBuffer &buffer, int comment='#',
                                  bool strip_inline_comments = true);

    /// Reads in the next token (skipping comments) and compares it to the
    /// expected value.  Returns true if the tokens match, and false otherwise.
    bool        checkNonCommentToken(const char *expected, int comment='#')
                {
                    UT_WorkBuffer       wbuf;
                    if (!getNonCommentWord(wbuf, comment))
                        return false;
                    return !strcmp(wbuf.buffer(), expected);
                }

    /// Reads in the next token and compares it to the expected value.  
    /// Returns true if the tokens match, and false otherwise.
    bool        checkToken(const char *expected)
                {
                    UT_WorkBuffer       wbuf;
                    if (!getWord(wbuf))
                        return false;
                    return !strcmp(wbuf.buffer(), expected);
                }

    // These methods return -1 (EOF) on failure to read the stream.
    int         getc();
    int         peek();

    // Returns the number of characters the stream was able to rewind.  The
    // class is guaranteed to be able to put back one character.  Otherwise,
    // you takes your chances.  This is not true if you peek into the stream.
    // Calling peek() may cause backup to fail.
    int         ungetc()        { return unwind(1); }
    int         unwind(int amount);

    // Read data into an array of the given type.  The data will be
    // byte-swapped according to the Houdini standard.  The size specified is
    // the number of elements in the array (not the size in bytes).
    //
    // Due to an ambiguity when reading characters from an ASCII stream,
    // there is no generic method to read characters.  Use the bread() method
    // to read raw characters, or the getWord() method to read a word.
    int         read(int16 *array, int sz=1)
                {
                    return myBinary ? bread(array, sz) : aread(array, sz);
                }
    int         read(uint16 *array, int sz=1)
                {
                    return myBinary ? bread(array, sz) : aread(array, sz);
                }
    int         read(int32 *array, int sz=1)
                {
                    return myBinary ? bread(array, sz) : aread(array, sz);
                }
    int         read(uint32 *array, int sz=1)
                {
                    return myBinary ? bread(array, sz) : aread(array, sz);
                }
    int         read(int64 *array, int sz=1)
                {
                    return myBinary ? bread(array, sz) : aread(array, sz);
                }
    int         read(uint64 *array, int sz=1)
                {
                    return myBinary ? bread(array, sz) : aread(array, sz);
                }
    int         read(fpreal32 *array, int sz=1)
                {
                    return myBinary ? bread(array, sz) : aread(array, sz);
                }
    int         read(fpreal64 *array, int sz=1)
                {
                    return myBinary ? bread(array, sz) : aread(array, sz);
                }
    bool        read(UT_String &string)
                {
                    return myBinary ? bread(string) : aread(string);
                }

    // Equivalent to UTreadBinaryString
    bool        readBinaryString(UT_String &str,
                        UT_ISTREAM_RLE_IO startbits);

    bool        readBool(bool &result)
                {
                    int32       ival;
                    if (read(&ival))
                    {
                        result = (ival != 0);
                        return true;
                    }
                    return false;
                }
    bool        readChar(char &result)
                {
                    if (isBinary())
                        return bread(&result) == 1;
                    return areadChar(result);
                }
    bool        areadChar(char &result)
                {
                    if (!skipLeadingWhitespace())
                        return false;
                    return bread(&result, 1) == 1;
                }

    // Platform consistent binary reads of data.  The read methods return the
    // number of elements read.
    int         bread(char *buffer, int asize=1);
    int         bread(unsigned char *buffer, int asize=1)
                    { return bread((char *)buffer, asize); }
    int         bread(int16 *buffer, int asize=1);
    int         bread(uint16 *buffer, int asize=1)
                    { return bread((int16 *)buffer, asize); }
    int         bread(int32 *buffer, int asize=1);
    int         bread(uint32 *buffer, int asize=1)
                    { return bread((int32 *)buffer, asize); }
    int         bread(int64 *buffer, int asize=1);
    int         bread(uint64 *buffer, int asize=1)
                    { return bread((int64 *)buffer, asize); }
    int         bread(fpreal32 *buffer, int asize=1);
    int         bread(fpreal64 *buffer, int asize=1);
    bool        bread(UT_String &str)   { return readString(str, true); }

    // Read ASCII values into the buffers.  The process is that we read a word,
    // then run atoi() or atof() on the token.  This does NOT set an error bit
    // if the word is not an integer.
    //
    // The aread(char *) method does not exist due to an ambiguity.
    // The following code:
    //    char  chr;
    //    is.read(&chr);
    // would skip whitespace when reading from an ASCII stream.  Since this is
    // error prone (i.e. you might expect the next character of the stream to
    // be read), there is no implicit ASCII read method for an array of
    // characters.  To read a single character, please call readChar() or
    // areadChar().
    //
    int         aread(int16 *buffer, int asize=1);
    int         aread(uint16 *buffer, int asize=1);
    int         aread(int32 *buffer, int asize=1);
    int         aread(uint32 *buffer, int asize=1);
    int         aread(int64 *buffer, int asize=1);
    int         aread(uint64 *buffer, int asize=1);
    int         aread(fpreal32 *buffer, int asize=1);
    int         aread(fpreal64 *buffer, int asize=1);
    bool        aread(UT_String &str)   { return readString(str, false); }

protected:
    // Protected constructors (used either internally or by sub-classes)

    // If you can't access this, you want a UT_IFStream subclass
    UT_IStream(const char *filename);
    UT_IStream(UT_IStreamBuf *sbuf, UT_ISTREAM_READTYPE binary);

protected:
    void        initCommon(UT_ISTREAM_READTYPE binary);
    bool        readString(UT_String &str, bool binary);
    void        setError();
    void        clearError();

    UT_IntArray                  myBinaryStack;
    UT_PtrArray<const char *>    myOperationStack;
    UT_IStreamBuf               *myStream;
    char                        *myLabel;
    int                          myVersion;
    bool                         myBinary, myEof, myError;
};

//
// Simple wrapper class for file streams that handles open and close of the
// file automatically.
class UT_API UT_IFStream : public UT_IStream {
public:
             UT_IFStream();
             UT_IFStream(const char *filename,
                        UT_ISTREAM_READTYPE binary=UT_ISTREAM_BINARY);
    virtual ~UT_IFStream();

    bool        open(const char *filename,
                        UT_ISTREAM_READTYPE binary=UT_ISTREAM_BINARY);
    bool        close();
};

//
// Compressed data input.
// Please see the getZlib and getGzip stream methods on UT_IStream.
class UT_API UT_IZStream : public UT_IStream {
public:
             UT_IZStream(UT_IStream &src);
    virtual ~UT_IZStream();
};

class UT_API UT_IGZStream : public UT_IStream {
public:
             UT_IGZStream(UT_IStream &src);
    virtual ~UT_IGZStream();
};

// Data input encrypted with a blowfish algorithm.
class UT_API UT_IBlowfishStream : public UT_IStream {
public:
             UT_IBlowfishStream(UT_IStream &src, const unsigned char * key, 
                                int key_size,
                                UT_ISTREAM_READTYPE binary=UT_ISTREAM_BINARY);
    virtual ~UT_IBlowfishStream();

    /// Obtains the length of data after it has been decrypted from the stream.
    static int      getPlainTextLength(UT_IStream &src);
};

//
// Turn the stream into binary or ASCII while scoped
class UT_API UT_IStreamAutoBinary {
public:
    explicit UT_IStreamAutoBinary(UT_IStream &is, UT_ISTREAM_READTYPE binary)
        : myIs(is)
    {
        myIs.pushBinary(binary);
    }
    explicit UT_IStreamAutoBinary(UT_IStream &is, bool binary)
        : myIs(is)
    {
        myIs.pushBinary(binary ? UT_ISTREAM_BINARY : UT_ISTREAM_ASCII);
    }
    ~UT_IStreamAutoBinary()
    {
        myIs.popBinary();
    }
private:
    UT_IStream  &myIs;
};

//
// Push operations being performed on the stream.  This is for error
// reporting.
class UT_API UT_IStreamAutoOp {
public:
    // Typically the strings will be compile time defined, which means they
    // don't need to be hardened.  The UT_IStream expects the operation string
    // to be around for the duration of the operation.
    explicit UT_IStreamAutoOp(UT_IStream &is, const char *operation,
                        bool harden = false)
            : myIs(is),
              myOperation(operation, harden ? 1 : 0)
    {
        myIs.pushOperation(myOperation);
    }
    ~UT_IStreamAutoOp()
    {
        myIs.popOperation();
    }
private:
    UT_IStream  &myIs;
    UT_String    myOperation;
};

#endif

---