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

#include <byte_filer.h>

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. More...

	byte_filer (const basis::astring &fname, const basis::astring &permissions)
	opens a file "fname" as specified in "permissions". More...

	byte_filer (const char fname, const char permissions)
	synonym for above but takes char pointers. More...

	byte_filer (bool auto_close, void *opened)
	uses a previously "opened" stdio FILE handle. be careful! More...

	~byte_filer ()

bool	open (const basis::astring &fname, const basis::astring &permissions)
	opens a file with "fname" and "permissions" as in the constructor. More...

void	close ()
	shuts down the open file, if any. More...

const basis::astring &	name () const
	returns the file name that the object is operating on. More...

bool	good ()
	returns true if the file seems to be in the appropriate desired state. More...

size_t	length ()
	returns the file's total length, in bytes. More...

size_t	tell ()
	returns the current position within the file, in terms of bytes. More...

void	flush ()
	forces any pending writes to actually be saved to the file. More...

bool	seek (int where, origins origin=FROM_START)
	places the cursor in the file at "where", based on the "origin". More...

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

int	read (basis::abyte *buffer, int buffer_size)
	reads "buffer_size" bytes from the file into "buffer". More...

int	write (const basis::abyte *buffer, int buffer_size)
	writes "buffer_size" bytes into the file from "buffer". More...

int	read (basis::byte_array &buffer, int desired_size)
	reads "buffer_size" bytes from the file into "buffer". More...

int	write (const basis::byte_array &buffer)
	writes the "buffer" into the file. More...

int	read (basis::astring &buffer, int desired_size)
	read() pulls up to "desired_size" bytes from the file into "buffer". More...

int	write (const basis::astring &buffer, bool add_null=false)
	stores the string in "buffer" into the file at the current position. More...

int	getline (basis::abyte *buffer, int desired_size)
	reads a line of text (terminated by a return) into the "buffer". More...

int	getline (basis::byte_array &buffer, int desired_size)
	reads a line of text (terminated by a return) into the "buffer". More...

int	getline (basis::astring &buffer, int desired_size)
	reads a line of text (terminated by a return) into the "buffer". More...

bool	truncate ()
	truncates the file after the current position. More...

void *	file_handle ()
	provides a hook to get at the operating system's file handle. More...

Static Public Member Functions
static size_t	file_size_limit ()
	returns the maximum size that seek and length can support. More...

Detailed Description

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

Definition at line 31 of file byte_filer.h.

Member Enumeration Documentation

◆ origins

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 93 of file byte_filer.h.

Constructor & Destructor Documentation

◆ byte_filer() [1/4]

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.

◆ byte_filer() [2/4]

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

opens a file "fname" 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().

◆ byte_filer() [3/4]

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

synonym for above but takes char pointers.

Definition at line 64 of file byte_filer.cpp.

References open().

◆ byte_filer() [4/4]

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.

◆ ~byte_filer()

filesystem::byte_filer::~byte_filer ( )

Definition at line 80 of file byte_filer.cpp.

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

Member Function Documentation

◆ close()

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 96 of file byte_filer.cpp.

References NULL_POINTER, and filesystem::filename::reset().

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

◆ eof()

bool filesystem::byte_filer::eof ( )

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

Definition at line 121 of file byte_filer.cpp.

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

◆ file_handle()

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 119 of file byte_filer.cpp.

◆ file_size_limit()

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().

◆ flush()

void filesystem::byte_filer::flush ( )

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

Definition at line 165 of file byte_filer.cpp.

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

◆ getline() [1/3]

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

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

Definition at line 201 of file byte_filer.cpp.

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

◆ getline() [2/3]

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 214 of file byte_filer.cpp.

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

◆ getline() [3/3]

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 208 of file byte_filer.cpp.

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

◆ good()

bool filesystem::byte_filer::good ( )

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

Definition at line 103 of file byte_filer.cpp.

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

◆ length()

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 140 of file byte_filer.cpp.

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

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

◆ name()

const astring & filesystem::byte_filer::name ( ) const

returns the file name that the object is operating on.

Definition at line 82 of file byte_filer.cpp.

References filesystem::filename::raw().

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

◆ open()

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

opens a file with "fname" 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(), NULL_POINTER, filesystem::filename::raw(), filesystem::filename::reset(), basis::astring::s(), and basis::astring::t().

Referenced by byte_filer().

◆ read() [1/3]

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.

Definition at line 123 of file byte_filer.cpp.

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

◆ read() [2/3]

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 149 of file byte_filer.cpp.

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

◆ read() [3/3]

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

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

Definition at line 129 of file byte_filer.cpp.

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

◆ seek()

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 187 of file byte_filer.cpp.

References FROM_CURRENT, FROM_END, and FROM_START.

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

◆ tell()

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 105 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(), truncate(), and loggers::file_logger::truncate().

◆ truncate()

bool filesystem::byte_filer::truncate ( )

truncates the file after the current position.

Definition at line 171 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().

◆ write() [1/3]

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

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

Definition at line 126 of file byte_filer.cpp.

Referenced by loggers::file_logger::log(), loggers::file_logger::log_bytes(), loggers::file_logger::truncate(), write(), filesystem::huge_file::write(), versions::version_ini::write_assembly(), write_build_config::write_output_file(), and versions::version_ini::write_rc().

◆ write() [2/3]

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 158 of file byte_filer.cpp.

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

◆ write() [3/3]

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

writes the "buffer" into the file.

Definition at line 137 of file byte_filer.cpp.

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

The documentation for this class was generated from the following files:

/opt/feistymeow.org/feisty_meow/nucleus/library/filesystem/byte_filer.h
/opt/feistymeow.org/feisty_meow/nucleus/library/filesystem/byte_filer.cpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ origins

Constructor & Destructor Documentation

◆ byte_filer() [1/4]

◆ byte_filer() [2/4]

◆ byte_filer() [3/4]

◆ byte_filer() [4/4]

◆ ~byte_filer()

Member Function Documentation

◆ close()

◆ eof()

◆ file_handle()

◆ file_size_limit()

◆ flush()

◆ getline() [1/3]

◆ getline() [2/3]

◆ getline() [3/3]

◆ good()

◆ length()

◆ name()

◆ open()

◆ read() [1/3]

◆ read() [2/3]

◆ read() [3/3]

◆ seek()

◆ tell()

◆ truncate()

◆ write() [1/3]

◆ write() [2/3]

◆ write() [3/3]