filesystem::byte_filer Class Reference

Provides file managment services using the standard I/O support. More...

#include <byte_filer.h>

Collaboration diagram for filesystem::byte_filer:

Public Types
enum	origins { FROM_START, FROM_END, FROM_CURRENT }
Public Member Functions
	byte_filer ()
	constructs an object that doesn't access a file yet.
	byte_filer (const basis::astring &filename, const basis::astring &permissions)
	opens a file "filename" as specified in "permissions".
	byte_filer (const char filename, const char permissions)
	synonym for above but takes char pointers.
	byte_filer (bool auto_close, void *opened)
	uses a previously "opened" stdio FILE handle. be careful!
	~byte_filer ()
bool	open (const basis::astring &filename, const basis::astring &permissions)
	opens a file with "filename" and "permissions" as in the constructor.
void	close ()
	shuts down the open file, if any.
basis::astring	filename () const
	returns the filename that this was opened with.
bool	good ()
	returns true if the file seems to be in the appropriate desired state.
size_t	length ()
	returns the file's total length, in bytes.
size_t	tell ()
	returns the current position within the file, in terms of bytes.
void	flush ()
	forces any pending writes to actually be saved to the file.
bool	seek (int where, origins origin=FROM_START)
	places the cursor in the file at "where", based on the "origin".
bool	eof ()
	returns true if the cursor is at (or after) the end of the file.
int	read (basis::abyte *buffer, int buffer_size)
	reads "buffer_size" bytes from the file into "buffer".
int	write (const basis::abyte *buffer, int buffer_size)
	writes "buffer_size" bytes into the file from "buffer".
int	read (basis::byte_array &buffer, int desired_size)
	reads "buffer_size" bytes from the file into "buffer".
int	write (const basis::byte_array &buffer)
	writes the "buffer" into the file.
int	read (basis::astring &buffer, int desired_size)
	read() pulls up to "desired_size" bytes from the file into "buffer".
int	write (const basis::astring &buffer, bool add_null=false)
	stores the string in "buffer" into the file at the current position.
int	getline (basis::abyte *buffer, int desired_size)
	reads a line of text (terminated by a return) into the "buffer".
int	getline (basis::byte_array &buffer, int desired_size)
	reads a line of text (terminated by a return) into the "buffer".
int	getline (basis::astring &buffer, int desired_size)
	reads a line of text (terminated by a return) into the "buffer".
bool	truncate ()
	truncates the file after the current position.
void *	file_handle ()
	provides a hook to get at the operating system's file handle.
Static Public Member Functions
static size_t	file_size_limit ()
	returns the maximum size that seek and length can support.

Detailed Description

Provides file managment services using the standard I/O support.

Definition at line 29 of file byte_filer.h.

Member Enumeration Documentation

enum filesystem::byte_filer::origins

Enumerator:

FROM_START	offset is from the beginning of the file.
FROM_END	offset is from the end of the file.
FROM_CURRENT	offset is from current cursor position.

Definition at line 91 of file byte_filer.h.

Constructor & Destructor Documentation

filesystem::byte_filer::byte_filer ( )

constructs an object that doesn't access a file yet.

use open() to make the object valid.

Definition at line 52 of file byte_filer.cpp.

filesystem::byte_filer::byte_filer	(	const basis::astring &	filename,
		const basis::astring &	permissions
	)

opens a file "filename" as specified in "permissions".

these are identical to the standard I/O permissions:

"r" - opens text file for reading.
"w" - opens text file for writing and discards any previous contents.
"a" - opens text file for writing at end; appends to contents.
"r+" - opens text file for update (both reading and writing).
"w+" - creates a text file for update; any previous contents are lost.
"a+" - opens or creates a text file for update, appending at end.

a "b" can be added to the end of these to indicate a binary file should be used instead of a text file.

Definition at line 58 of file byte_filer.cpp.

References open().

filesystem::byte_filer::byte_filer	(	const char *	filename,
		const char *	permissions
	)

synonym for above but takes char pointers.

Definition at line 64 of file byte_filer.cpp.

References open().

filesystem::byte_filer::byte_filer	(	bool	auto_close,
		void *	opened
	)

uses a previously "opened" stdio FILE handle. be careful!

the "opened" object must be a valid FILE pointer; void * is used to avoid pulling in the stdio header. this method will not close the file handle if "auto_close" is false.

Definition at line 70 of file byte_filer.cpp.

filesystem::byte_filer::~byte_filer ( )

Definition at line 80 of file byte_filer.cpp.

References close(), and basis::WHACK().

Member Function Documentation

void filesystem::byte_filer::close ( )

shuts down the open file, if any.

open() will have to be invoked before this object can be used again.

Definition at line 107 of file byte_filer.cpp.

References NIL.

Referenced by open(), versions::version_ini::write_code(), versions::version_ini::write_rc(), and ~byte_filer().

bool filesystem::byte_filer::eof ( )

returns true if the cursor is at (or after) the end of the file.

Definition at line 132 of file byte_filer.cpp.

Referenced by filesystem::huge_file::eof(), write_build_config::execute(), filesystem::huge_file::length(), manifest_chunk::read_a_string(), and loggers::file_logger::truncate().

void * filesystem::byte_filer::file_handle ( )

provides a hook to get at the operating system's file handle.

this is of the type FILE *, as defined by <stdio.h>.

Definition at line 130 of file byte_filer.cpp.

size_t filesystem::byte_filer::file_size_limit ( ) [static]

returns the maximum size that seek and length can support.

use the huge_file class if you need to exceed the stdio limits.

Definition at line 84 of file byte_filer.cpp.

References filesystem::BTFL_FILE_TELL_LIMIT.

Referenced by filesystem::huge_file::length(), filesystem::huge_file::move_to(), and truncate().

astring filesystem::byte_filer::filename ( ) const

returns the filename that this was opened with.

Definition at line 82 of file byte_filer.cpp.

Referenced by write_build_config::execute(), filesystem::huge_file::length(), versions::version_ini::write_assembly(), and write_build_config::write_output_file().

void filesystem::byte_filer::flush ( )

forces any pending writes to actually be saved to the file.

Definition at line 176 of file byte_filer.cpp.

Referenced by loggers::file_logger::flush(), filesystem::huge_file::flush(), and truncate().

int filesystem::byte_filer::getline	(	basis::astring &	buffer,
		int	desired_size
	)

reads a line of text (terminated by a return) into the "buffer".

Definition at line 225 of file byte_filer.cpp.

References basis::astring::access(), getline(), basis::non_negative(), basis::astring::pad(), and basis::astring::shrink().

int filesystem::byte_filer::getline	(	basis::byte_array &	buffer,
		int	desired_size
	)

reads a line of text (terminated by a return) into the "buffer".

Definition at line 219 of file byte_filer.cpp.

References basis::array< contents >::access(), getline(), and basis::array< contents >::reset().

int filesystem::byte_filer::getline	(	basis::abyte *	buffer,
		int	desired_size
	)

reads a line of text (terminated by a return) into the "buffer".

Referenced by write_build_config::execute(), getline(), and bookmark_tree::read_csv_file().

bool filesystem::byte_filer::good ( )

returns true if the file seems to be in the appropriate desired state.

Definition at line 114 of file byte_filer.cpp.

Referenced by write_build_config::execute(), loggers::file_logger::format_bytes(), loggers::file_logger::good(), filesystem::huge_file::good(), loggers::file_logger::log(), loggers::file_logger::log_bytes(), main(), open(), bookmark_tree::read_csv_file(), configuration::ini_configurator::sections(), tell(), loggers::file_logger::truncate(), versions::version_ini::write_code(), write_build_config::write_output_file(), and versions::version_ini::write_rc().

size_t filesystem::byte_filer::length ( )

returns the file's total length, in bytes.

this cannot accurately report a file length if it is file_size_limit() or greater.

Definition at line 151 of file byte_filer.cpp.

References FROM_END, FROM_START, seek(), and tell().

Referenced by filesystem::huge_file::length().

bool filesystem::byte_filer::open	(	const basis::astring &	filename,
		const basis::astring &	permissions
	)

opens a file with "filename" and "permissions" as in the constructor.

if a different file had already been opened, it is closed.

Definition at line 86 of file byte_filer.cpp.

References close(), good(), NIL, basis::astring::s(), and basis::astring::t().

Referenced by byte_filer().

int filesystem::byte_filer::read	(	basis::astring &	buffer,
		int	desired_size
	)

read() pulls up to "desired_size" bytes from the file into "buffer".

since the read() will grab as much data as is available given that it fits in "desired_size". null characters embedded in the file are a bad issue here; some other method must be used to read the file instead (such as the byte_array read above). the "buffer" is shrunk to fit the zero terminator that we automatically add.

Definition at line 160 of file byte_filer.cpp.

References basis::non_negative(), basis::astring::observe(), basis::astring::pad(), read(), and basis::astring::shrink().

int filesystem::byte_filer::read	(	basis::byte_array &	buffer,
		int	desired_size
	)

reads "buffer_size" bytes from the file into "buffer".

Definition at line 140 of file byte_filer.cpp.

References basis::array< contents >::access(), basis::array< contents >::length(), read(), basis::array< contents >::reset(), and basis::array< contents >::zap().

int filesystem::byte_filer::read	(	basis::abyte *	buffer,
		int	buffer_size
	)

reads "buffer_size" bytes from the file into "buffer".

for all of the read and write operations, the number of bytes that is actually processed for the file is returned.

Referenced by filesystem::huge_file::length(), main(), filesystem::huge_file::read(), read(), manifest_chunk::read_a_filetime(), manifest_chunk::read_a_string(), configuration::ini_configurator::sections(), loggers::file_logger::truncate(), versions::version_ini::write_assembly(), and write_build_config::write_output_file().

bool filesystem::byte_filer::seek	(	int	where,
		origins	origin = `FROM_START`
	)

places the cursor in the file at "where", based on the "origin".

note that if the origin is FROM_END, then the offset "where" should be a negative number if you're trying to access the interior of the file; positive offsets indicate places after the actual end of the file.

Definition at line 198 of file byte_filer.cpp.

References FROM_CURRENT, FROM_END, and FROM_START.

Referenced by filesystem::huge_file::length(), length(), filesystem::huge_file::move_to(), filesystem::huge_file::seek(), loggers::file_logger::truncate(), and versions::version_ini::write_assembly().

size_t filesystem::byte_filer::tell ( )

returns the current position within the file, in terms of bytes.

this is also limited to file_size_limit().

printf(a_sprintf("failed to tell size, calling it %.0f, and one plus that is %.0f\n", double(BTFL_FILE_TELL_LIMIT), double(long(long(BTFL_FILE_TELL_LIMIT) + 1))).s());

Definition at line 116 of file byte_filer.cpp.

References filesystem::BTFL_FILE_TELL_LIMIT, and good().

Referenced by length(), loggers::file_logger::log(), loggers::file_logger::log_bytes(), loggers::file_logger::truncate(), and truncate().

bool filesystem::byte_filer::truncate ( )

truncates the file after the current position.

Definition at line 182 of file byte_filer.cpp.

References file_size_limit(), fileno, flush(), and tell().

Referenced by filesystem::huge_file::truncate(), and versions::version_ini::write_assembly().

int filesystem::byte_filer::write	(	const basis::astring &	buffer,
		bool	add_null = `false`
	)

stores the string in "buffer" into the file at the current position.

if "add_null" is true, then write() adds a zero terminator to what is written into the file. otherwise just the string's non-null contents are written.

Definition at line 169 of file byte_filer.cpp.

References basis::astring::length(), basis::astring::observe(), and write().

int filesystem::byte_filer::write ( const basis::byte_array & buffer )

writes the "buffer" into the file.

Definition at line 148 of file byte_filer.cpp.

References basis::array< contents >::length(), basis::array< contents >::observe(), and write().