1 #ifndef BYTE_FILER_CLASS
2 #define BYTE_FILER_CLASS
4 /*****************************************************************************\
7 * Author : Chris Koeritz *
9 *******************************************************************************
10 * Copyright (c) 2000-$now By Author. This program is free software; you can *
11 * redistribute it and/or modify it under the terms of the GNU General Public *
12 * License as published by the Free Software Foundation; either version 2 of *
13 * the License or (at your option) any later version. This is online at: *
14 * http://www.fsf.org/copyleft/gpl.html *
15 * Please send any updates to: fred@gruntose.com *
16 \*****************************************************************************/
18 #include <basis/astring.h>
19 #include <basis/byte_array.h>
20 #include <basis/definitions.h>
22 namespace filesystem {
24 // forward declarations.
27 //! Provides file managment services using the standard I/O support.
33 //!< constructs an object that doesn't access a file yet.
34 /*!< use open() to make the object valid. */
36 byte_filer(const basis::astring &filename, const basis::astring &permissions);
37 //!< opens a file "filename" as specified in "permissions".
38 /*!< these are identical to the standard I/O permissions:
40 - "r" - opens text file for reading.
41 - "w" - opens text file for writing and discards any previous contents.
42 - "a" - opens text file for writing at end; appends to contents.
43 - "r+" - opens text file for update (both reading and writing).
44 - "w+" - creates a text file for update; any previous contents are lost.
45 - "a+" - opens or creates a text file for update, appending at end.
47 a "b" can be added to the end of these to indicate a binary file should
48 be used instead of a text file. */
50 byte_filer(const char *filename, const char *permissions);
51 //!< synonym for above but takes char pointers.
53 byte_filer(bool auto_close, void *opened);
54 //!< uses a previously "opened" stdio FILE handle. be careful!
55 /*!< the "opened" object must be a valid FILE pointer; void * is used to
56 avoid pulling in the stdio header. this method will not close the file
57 handle if "auto_close" is false. */
61 static size_t file_size_limit();
62 //!< returns the maximum size that seek and length can support.
63 /*!< use the huge_file class if you need to exceed the stdio limits. */
65 bool open(const basis::astring &filename, const basis::astring &permissions);
66 //!< opens a file with "filename" and "permissions" as in the constructor.
67 /*!< if a different file had already been opened, it is closed. */
70 //!< shuts down the open file, if any.
71 /*!< open() will have to be invoked before this object can be used again. */
73 basis::astring filename() const;
74 //!< returns the filename that this was opened with.
77 //!< returns true if the file seems to be in the appropriate desired state.
80 //!< returns the file's total length, in bytes.
81 /*!< this cannot accurately report a file length if it is file_size_limit()
85 //!< returns the current position within the file, in terms of bytes.
86 /*!< this is also limited to file_size_limit(). */
89 //!< forces any pending writes to actually be saved to the file.
92 FROM_START, //!< offset is from the beginning of the file.
93 FROM_END, //!< offset is from the end of the file.
94 FROM_CURRENT //!< offset is from current cursor position.
97 bool seek(int where, origins origin = FROM_START);
98 //!< places the cursor in the file at "where", based on the "origin".
99 /*!< note that if the origin is FROM_END, then the offset "where" should
100 be a negative number if you're trying to access the interior of the file;
101 positive offsets indicate places after the actual end of the file. */
104 //!< returns true if the cursor is at (or after) the end of the file.
106 int read(basis::abyte *buffer, int buffer_size);
107 //!< reads "buffer_size" bytes from the file into "buffer".
108 /*!< for all of the read and write operations, the number of bytes that
109 is actually processed for the file is returned. */
110 int write(const basis::abyte *buffer, int buffer_size);
111 //!< writes "buffer_size" bytes into the file from "buffer".
113 int read(basis::byte_array &buffer, int desired_size);
114 //!< reads "buffer_size" bytes from the file into "buffer".
115 int write(const basis::byte_array &buffer);
116 //!< writes the "buffer" into the file.
118 int read(basis::astring &buffer, int desired_size);
119 //!< read() pulls up to "desired_size" bytes from the file into "buffer".
120 /*!< since the read() will grab as much data as is available given that it
121 fits in "desired_size". null characters embedded in the file are a bad
122 issue here; some other method must be used to read the file instead (such
123 as the byte_array read above). the "buffer" is shrunk to fit the zero
124 terminator that we automatically add. */
126 int write(const basis::astring &buffer, bool add_null = false);
127 //!< stores the string in "buffer" into the file at the current position.
128 /*!< if "add_null" is true, then write() adds a zero terminator to what
129 is written into the file. otherwise just the string's non-null contents
132 int getline(basis::abyte *buffer, int desired_size);
133 //!< reads a line of text (terminated by a return) into the "buffer".
134 int getline(basis::byte_array &buffer, int desired_size);
135 //!< reads a line of text (terminated by a return) into the "buffer".
136 int getline(basis::astring &buffer, int desired_size);
137 //!< reads a line of text (terminated by a return) into the "buffer".
140 //!< truncates the file after the current position.
143 //!< provides a hook to get at the operating system's file handle.
144 /*!< this is of the type FILE *, as defined by <stdio.h>. */
147 file_hider *_handle; //!< the standard I/O support that we rely upon.
148 basis::astring *_filename; //!< holds onto our current filename.
149 bool _auto_close; //!< true if the object should close the file.
152 byte_filer(const byte_filer &);
153 byte_filer &operator =(const byte_filer &);