PLCore::File Class Reference

Class for accessing a file in the file system. More...

#include <File.h>

Inheritance diagram for PLCore::File:

List of all members.

Public Types
enum	EAccess {   FileRead = 1, FileWrite = 2, FileAppend = 4, FileCreate = 8,   FileText = 16, FileMemBuf = 32 }
	File access flags. More...
enum	ESeek { SeekSet = 0, SeekCurrent, SeekEnd }
	Seek position enumerations. More...
Public Member Functions
	File ()
	Constructor.
	File (const String &sUrl, const FileAccess *pAccess=nullptr)
	Constructor.
	File (const Url &cUrl, const FileAccess *pAccess=nullptr)
	Constructor.
	File (FILE *pFile, uint32 nAccess)
	Constructor for a standard OS stream.
	File (handle hFile)
	Constructor.
PLCORE_API	File (uint8 *pnData, uint32 nNumOfBytes, bool bCopy=true, const String &sUrl="")
	Constructor.
virtual	~File ()
	Destructor.
bool	Create (bool bAlways=false)
	Create file.
bool	Delete ()
	Delete file.
PLCORE_API bool	Open (uint32 nAccess, String::EFormat nStringFormat=String::ASCII)
	Open the file for reading and/or writing.
void	Close ()
	Close the file.
bool	IsMemoryBuffered () const
	Returns whether the file is memory buffered (opened with flag 'FileMemBuf')
bool	IsOpen () const
	Returns whether the file is open.
bool	IsReadable () const
	Returns whether the file is readable.
bool	IsWritable () const
	Returns whether the file is writable.
String::EFormat	GetStringFormat () const
	Returns the string encoding format to use when dealing with string functions.
bool	IsEof () const
	Returns whether end of file has been reached.
int	GetC ()
	Reads a character.
bool	PutC (int nChar)
	Writes a character.
String	GetS ()
	Reads a string.
int	PutS (const String &sString)
	Writes a string.
uint32	Read (void *pBuffer, uint32 nSize, uint32 nCount)
	Reads the given number of bytes.
uint32	Write (const void *pBuffer, uint32 nSize, uint32 nCount)
	Writes the given number of bytes.
bool	Flush ()
	Flushes the file buffer.
bool	Seek (int32 nOffset=0, ESeek nLocation=SeekSet)
	Sets the starting position.
int32	Tell () const
	Gets the current position of the file pointer.
uint32	GetSize () const
	Returns the file size.
bool	Print (const String &sString)
	Writes a string into the file.
bool	PrintLn (const String &sString)
	Writes a string and a newline into the file.
const uint8 *	GetMemoryBuffer () const
	Returns a pointer to the buffer for memory buffered file.
PLCORE_API String	GetContentAsString ()
	Returns the complete content of the file as string.
Static Public Member Functions
static PLCORE_API uint32	CFileModeToAccessFlags (const String &sMode)
	Translates a given C file mode into access flags.
Static Public Attributes
static PLCORE_API File	StandardInput
static PLCORE_API File	StandardOutput
static PLCORE_API File	StandardError

---

Detailed Description

Class for accessing a file in the file system.

---

Member Enumeration Documentation

enum PLCore::File::EAccess

File access flags.

Enumerator:

FileRead	File can be read
FileWrite	File can be written
FileAppend	File will be appended
FileCreate	File will be created
FileText	File will be opened in text mode (whenever possible, don't set this flag because not each platform may support it)
FileMemBuf	File will be opened memory buffered (only usable for reading!)

enum PLCore::File::ESeek

Seek position enumerations.

Enumerator:

SeekSet	Seek relative to the start of the file (default setting)
SeekCurrent	Seek relative to the current position
SeekEnd	Seek relative to the end of the file

---

Constructor & Destructor Documentation

PLCore::File::File

(

)

[inline]

Constructor.

PLCore::File::File	(	const String &	sUrl,
		const FileAccess *	pAccess = nullptr
	)		[inline]

Constructor.

Parameters:

[in]	sUrl	URL of a file
[in]	pAccess	Additional file access information (can be a null pointer)

PLCore::File::File	(	const Url &	cUrl,
		const FileAccess *	pAccess = nullptr
	)		[inline]

Constructor.

Parameters:

[in]	cUrl	URL of a file
[in]	pAccess	Additional file access information (can be a null pointer)

PLCore::File::File	(	FILE *	pFile,
		uint32	nAccess
	)		[inline]

Constructor for a standard OS stream.

Parameters:

[in]	pFile	Standard stream pointer
[in]	nAccess	Access flags that were used to open the stream

PLCore::File::File

(

handle

hFile

)

[inline]

Constructor.

Parameters:

[in]

hFile

OS file handle

Note:

• On Linux, the handle is a file handle of type int.
• On Windows, the handle is a file handle of type HANDLE. Do not expect an int (fileno) here! If you need it to work with low level io functions, you need to convert the HANDLE to a file handle by yourself (see _open_osfhandle).

PLCORE_API PLCore::File::File	(	uint8 *	pnData,
		uint32	nNumOfBytes,
		bool	bCopy = true,
		const String &	sUrl = ""
	)

Constructor.

Parameters:

[in]	pnData	The file data, if a null pointer same as the standard constructor
[in]	nNumOfBytes	Number of file data bytes, MUST be valid!
[in]	bCopy	Copy the given data or use this one directly? Do ONLY set bCopy to 'false' if you are sure there can't go anything wrong. (data pointer MUST stay valid!)
[in]	sUrl	URL of a file

PLCore::File::~File

(

)

[inline, virtual]

Destructor.

Note:

• The file is closed automatically

---

Member Function Documentation

static PLCORE_API uint32 PLCore::File::CFileModeToAccessFlags

(

const String &

sMode

)

[static]

Translates a given C file mode into access flags.

Parameters:

[in]

sMode

C file mode ("r", "r+", "w", "w+", "a", "a+", "t", "r+t" etc. used for e.g. "fopen") to translate

Returns:

The access flags (see EAccess)

bool PLCore::File::Create

(

bool

bAlways = false

)

[inline]

Create file.

Parameters:

[in]

bAlways

If 'true', the file is created (and therefore overwritten) if it already exists

Returns:

'true', if all went fine, else 'false'

bool PLCore::File::Delete

(

)

[inline]

Delete file.

Returns:

'true', if all went fine, else 'false'

PLCORE_API bool PLCore::File::Open	(	uint32	nAccess,
		String::EFormat	nStringFormat = String::ASCII
	)

Open the file for reading and/or writing.

Parameters:

[in]	nAccess	Access mode, combination of 'EAccess' flags
[in]	nStringFormat	String encoding format to use when dealing with string functions (not supported by all file implementations)

Returns:

'false' on error, else 'true'

Note:

• 'FileStandardInput', 'FileStandardOutput' and 'FileStandardError' are special access flags that can't be combined with other flags and the filename must be empty
• It's not recommended to use Unicode by because internally wchar_t is used and this data type has not the same size on every platform (use ASCII or UTF8 instead)

void PLCore::File::Close

(

)

[inline]

Close the file.

Reimplemented from PLCore::FileObject.

bool PLCore::File::IsMemoryBuffered

(

)

const [inline]

Returns whether the file is memory buffered (opened with flag 'FileMemBuf')

Returns whether the file is memory buffered (opened with flag FileMemBuf)

Returns:

'true', if the file is memory buffered, else 'false'

See also:

• GetMemoryBuffer()

bool PLCore::File::IsOpen

(

)

const [inline]

Returns whether the file is open.

Returns:

'true', if the file is open, else 'false'

bool PLCore::File::IsReadable

(

)

const [inline]

Returns whether the file is readable.

Returns:

'true', if the file can be read, else 'false'

bool PLCore::File::IsWritable

(

)

const [inline]

Returns whether the file is writable.

Returns:

'true', if the file can be written, else 'false'

String::EFormat PLCore::File::GetStringFormat

(

)

const [inline]

Returns the string encoding format to use when dealing with string functions.

Returns:

String encoding format to use when dealing with string functions

bool PLCore::File::IsEof

(

)

const [inline]

Returns whether end of file has been reached.

Returns:

'true', if the end of the file has been reached, else 'false'

int PLCore::File::GetC

(

)

[inline]

Reads a character.

Returns:

A character from file, < 0 if there was an error

bool PLCore::File::PutC

(

int

nChar

)

[inline]

Writes a character.

Parameters:

[in]

nChar

Character to write

Returns:

'true' if all went fine, else 'false' (maybe file is read only)

String PLCore::File::GetS

(

)

[inline]

Reads a string.

Returns:

Read string

int PLCore::File::PutS

(

const String &

sString

)

[inline]

Writes a string.

Parameters:

[in]

sString

String which should be written into the file

Returns:

Number of bytes written, 0 if nothing was written, < 0 if there was an error

uint32 PLCore::File::Read	(	void *	pBuffer,
		uint32	nSize,
		uint32	nCount
	)		[inline]

Reads the given number of bytes.

Parameters:

[out]	pBuffer	Buffer were the data should be copied in (MUST valid and large enough!)
[in]	nSize	Item size in bytes
[in]	nCount	Maximum number of items to be read

Returns:

Number of fully read items, if != 'nCount' an error occurred

uint32 PLCore::File::Write	(	const void *	pBuffer,
		uint32	nSize,
		uint32	nCount
	)		[inline]

Writes the given number of bytes.

Parameters:

[in]	pBuffer	Buffer with the data which should be written into the file (MUST valid and large enough!)
[in]	nSize	Item size in bytes
[in]	nCount	Maximum number of items to be written

Returns:

Number of fully written items, if != 'nCount' an error occurred

bool PLCore::File::Flush

(

)

[inline]

Flushes the file buffer.

Returns:

'true' if all went fine, else 'false'

Remarks:

Writes down all temporarily buffered data.

bool PLCore::File::Seek	(	int32	nOffset = 0,
		ESeek	nLocation = SeekSet
	)		[inline]

Sets the starting position.

Parameters:

[in]	nOffset	File offset in bytes relative to the given location
[in]	nLocation	Location

Returns:

'true' if all went fine, else 'false'

int32 PLCore::File::Tell

(

)

const [inline]

Gets the current position of the file pointer.

Returns:

The current byte position of the file pointer, < 0 if there was an error

uint32 PLCore::File::GetSize

(

)

const [inline]

Returns the file size.

Returns:

File size in bytes

bool PLCore::File::Print

(

const String &

sString

)

[inline]

Writes a string into the file.

Parameters:

[in]

sString

String which should be written into the file

Returns:

'true' if all went fine, else 'false'

bool PLCore::File::PrintLn

(

const String &

sString

)

[inline]

Writes a string and a newline into the file.

Parameters:

[in]

sString

String which should be written into the file

Returns:

'true' if all went fine, else 'false'

const uint8 * PLCore::File::GetMemoryBuffer

(

)

const [inline]

Returns a pointer to the buffer for memory buffered file.

Returns:

Pointer to the buffer for memory buffered file, a null pointer if there's no such buffer

See also:

• IsMemoryBuffered()

PLCORE_API String PLCore::File::GetContentAsString

(

)

Returns the complete content of the file as string.

Returns:

The complete file content as string, empty string on error or if the file is just empty

---

Member Data Documentation

PLCORE_API File PLCore::File::StandardInput [static]

Standard OS input stream (stdin)

PLCORE_API File PLCore::File::StandardOutput [static]

Standard OS output stream (stdout)

PLCORE_API File PLCore::File::StandardError [static]

Standard OS error stream (stderr)

---

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

• File.h
• File.inl