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 Jul 20 10:46:48 2004 for s11n by doxygen 1.3.7