Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members

file_util.h

00001 #ifndef s11n_FILE_UTIL_H_INCLUDED
00002 #define s11n_FILE_UTIL_H_INCLUDED 1
00003 
00004 #include <string>
00005 
00006 namespace s11n {
00007 
00008         /**
00009            CompressionPolicy describes the framework-wide policy
00010            regarding compression when writing to files. (Sorry, pure
00011            stream-based compression isn't yet supported.)
00012 
00013            Setting to GZip/BZipCompression only enables compression if
00014            HAVE_ZLIB or HAVE_BZLIB ars set during library compilation,
00015            otherwise non-compressed streams are used in all cases.
00016 
00017            bzip compresses much better than gzip, but is notably
00018            slower. The speed should not make much of a difference
00019            unless you are working with very large data sets, and then
00020            you will notice that gzip is faster.
00021 
00022            Tip: you can use get_istream() on an arbitrary filename to
00023            get an appropriate input stream. Likewise, use
00024            get_ostream() to open writable a file with the
00025            policy-mandated stream type (if possible, defaulting to
00026            std::ofstream).
00027          */
00028         enum CompressionPolicy {
00029             /** NoCompression implies just what it says - do not use compressed output streams. */
00030             NoCompression = 0,
00031                 /** GZipCompression means to use the s11n::ogzstream class for output streams. */
00032             GZipCompression = 1,
00033                 /** BZipCompression means to use the s11n::obzstream class for output streams. */
00034             BZipCompression = 2
00035         };
00036 
00037         /**
00038            Sets the framework-wide CompressionPolicy preference.
00039            See the s11n::CompressionPolicy enum.
00040          */
00041         void compression_policy( CompressionPolicy c );
00042 
00043         /**
00044            Returns the framework-wide CompressionPolicy preference.
00045            See the s11n::CompressionPolicy enum.
00046          */
00047         CompressionPolicy compression_policy();
00048 
00049         /**
00050            Looks at the given file and tries to figure out what type
00051            of decompression stream, if any, should be used.
00052            It will return one of the following types:
00053 
00054            - std::ifstream
00055            - s11n::gzstream
00056            - s11n::bzstream
00057 
00058            It will return NULL if it cannot open filename, or a
00059            std::ifstream if it cannot figure out a decompression
00060            scheme.
00061 
00062            It will only return one of the compressed stream types if
00063            this code is built with the appropriate macros: HAVE_ZLIB
00064            and HAVE_BZLIB, and then linked against -lgz and/or -lbz2.
00065            Thus, if this code is not built with compression support it
00066            is possible that it returns a std::ifstream reading from a
00067            compressed file.
00068 
00069            If AsFilename is true, input is treated as a file,
00070            otherwise it is treated as a string, for which an
00071            stringstream is returned. Compressor streams are currently
00072            only supported when AsFile is true. This feature has subtle
00073            uses in writing more generic client code for handling arbitrary
00074            input streams.
00075         */
00076         std::istream * get_istream( const std::string & src, bool AsFile = true );
00077 
00078 
00079         /**
00080            Returns one of the following types of ostreams, depending
00081            on compression_policy() and compile-time library settings
00082            of HAVE_ZLIB and HAVE_BZLIB.
00083 
00084            - s11n::ogzstream
00085            - s11n::obzstream
00086            - std::ofstream
00087 
00088            Note that this function only uses filename to pass to the
00089            stream's constructor, and does no checking of the file.
00090 
00091            The caller is responsible for deleting the pointer.
00092 
00093            For determining the type of input stream for a file, 
00094            see s11n::get_istream().
00095         */
00096         std::ostream * get_ostream( const std::string & filename );
00097 
00098 
00099 
00100         
00101         /**
00102            Returns the first 'bytes' bytes from the given file,
00103            assuming the file exists and can be read. It stops at the
00104            first newline character unless read_past_nl is true.
00105 
00106            On error an empty string is returned.
00107 
00108            This function is primarily intended to be used for looking
00109            for magic cookies. It is also sometimes useful, for
00110            example, for checking the type of a file or grabbing, e.g.,
00111            the CVSROOT out of CVS/Root.
00112 
00113            Results are undefined with binary files.
00114 
00115            If this library is compiled with HAVE_ZLIB/HAVE_BZLIB set
00116            to true then this function supports transparent
00117            decompression of gzipped/bzipped files.
00118 
00119            It caches requests, so subsequent lookups are fast.
00120          */
00121         std::string bytes_from_file( const std::string & fn, unsigned int bytes = 128, bool read_past_nl = false );
00122 
00123 }; // namespace s11n
00124 
00125 #endif // s11n_FILE_UTIL_H_INCLUDED

Generated on Tue Oct 26 18:25:59 2004 for s11n by  doxygen 1.3.9.1