File Class Reference

This class offers a rich set of low and high-level operations for safe and convenient handling of raw files that can be randomly accessed, including commonly used operations like reading, writing, copying, removing, existence and difference checking and so forth.

#include "universal__File.h"

Namespace

universal

Public Member Functions

• File ( const String & c_sFileName , String sMode = "r" , bool bDoOpen = true ) 
• virtual ~File ( ) 
• bool isOpen ( ) const 
• bool isDirectory ( ) const 
• bool fail ( ) const 
• bool eof ( ) 
• bool flush ( ) 
• bool purge ( ) 
• void clear ( ) 
• String name ( ) const 
• String basename ( ) const 
• String lookupPath ( ) 
• String absolutePath ( ) 
• String dos83alias ( ) 
• String devicePath ( ) 
• String hardDriveId ( ) 
• String getErrorMessage ( ) const 
• virtual void open ( ) 
• virtual void close ( ) 
• bool remove ( ) 
• bool cat ( ) 

Public Static Member Functions

• String path ( String sPath1 , String sPath2 ) 
• bool exists ( const char * c_pszFilePath ) 
• bool diff ( const char * pszFile1 , const char * pszFile2 ) 
• bool copy ( const char * pszSrcFile , const char * pszDstFile , bool bOverwrite = false ) 
• String separator ( ) 

Public Static Member Variables

• unsigned long MAXIMUM_PATH_LENGTH 

Detailed Description

This class offers a rich set of low and high-level operations for safe and convenient handling of raw files that can be randomly accessed, including commonly used operations like reading, writing, copying, removing, existence and difference checking and so forth.

The file is handled and viewed as a raw stream of bytes. Sometimes high-level string objects can be passed as input to or/and returned as result of a function.

This class is optimised for high performance and relies directly upon the C file stream API (FILE*, fwrite(), fread()...).

Files Included

#include <stdio.h>

#include <vector>

#include "universal.h"

#include "universal__String.h"

Member Functions Documentation

Checks whether the passed file exists. Returns true if so.

Creates a new path by concatenating path1 and path2 and separating them with a path separator.

See also:

static String separator ( )

Copy file of path c_pszSrcFile to file of path c_pszDstFile.

bOverwrite tells whether to overwrite the file c_pszDstFile if it already exists.

Returns true if the operation was successful and the file was written or overwritten.

Tells whether the file of path c_pszFile1 and the file of path c_pszFile2 differ. If an error was encountered while reading either of these files, true is returned.

Returns the separator string used in the file paths, depending on the current OS.

Constructor.

c_sFileName gives the name of the directory or the file. The name can be a base name, a relative path or an absolute path.

If c_sFileName is a file, the constructor will attempt to open the file according to the opening mode sMode.

sMode give the mode. It is the same string that the one passed to the C FILE stream function ::fopen(...);

sMode is optional. By default, it is set to "r" (read-only). As remainder, the possible modes are the following:

r Open text file for reading. The stream is positioned at the beginning of the file. r+ Open for reading and writing. The stream is positioned at the beginning of the file. w Truncate file to zero length or create text file for writing. The stream is positioned at the beginning of the file. w+ Open for reading and writing. The file is created if it does not exist, otherwise it is truncated. The stream is positioned at the beginning of the file. a Open for writing. The file is created if it does not exist. The stream is positioned at the end of the file. a+ Open for reading and writing. The file is created if it does not exist. The stream is positioned at the end of the file.

bDoOpen tells whether to attempt to open the file immediately. bDoOpen is optional. By default, it is set to "true" (do open the file with the specified mode).

Destructor.

Tells whether the file is actually a directory.

Clears the failure flag to allow to execute further actions on the file.

Tells whether a failure occurred while opening, reading, writing or removing.

Tells whether EOF was encountered.

Sets the failure flag.

In case of a failure, this allows to get the error message. This is the string as returned by the system function ::strerror(int).

See also:

bool fail ( ) const

Removes the file from file system. If open, the file is closed prior to the removal.

Opens the file with the specified mode.

Tells whether the file is open.

Returns the name of the file as passed to the constructor.

Returns the base name of the file name passed to the constructor by stripping directory and suffix.

Returns a string uniquely identifying the hard drive on which is located this file. This operation may require super-user priviledges and this function may set the failure flag and failure error message.

See also:

String devicePath ( )

Returns the path of the device on which is located this file.

See also:

String absolutePath ( )

Looks up the absolute path of the file in the environment, assuming this object refers to an executed file. This path resolution process is the following:

- If the file name is already an absolute path, return it as is - If the file name is a relative path, reconstitue the path by appending this relative path to the absolute path of the current working directory. - Otherwise, scan the PATH environnment variable and ckeck that the absolute path of the executed file can be resolved from one of the paths defined by the PATH environement variable. - If no absolute file could be, the absolute path of the file as returned the following function is returned.

See also:

String absolutePath ( )

Returns the absolute path of the file, assuming this object refers to a valid existing static file (not an executed one) from the current working directory.

If the file name is already an absolute path, it is returned as is.

If the file does not exist, failure flag and message are set and the original name of the file is returned.

See also:

String lookupPath ( )

Returns the DOS short name. Under UNIX, just returns the name of the file.

See also:

String File::name ( ) const

Returns true if the creation if the full path was successful.

Returns false if any component of the path couldn't be created; In that case, the directory may only be partially created.

Under UNIX, the permissions assigned to the created directory is rwxr-xr-x.

Returns the current position in the file. Returns -1 if the file is not open.

Returns the size in byte of the file, or -1 if this size couldn't be determined. This data is cached in an internal variable.

Writes the passed string to the file and appends a new line char.

See also:

void write ( const String & c_s )

Writes the passed string to the file.

See also:

void write ( unsigned char * c_pucBytes , unsigned long uOffset , unsigned long uLen )

Writes uLen bytes from offset uOffset of the passed buffer c_pucBytes.

Flushes any buffered written data.

Returns true on success. Otherwise the failure flag and error message is set.

Purges any buffered input or output data.

This operation is actually not supported yet ! Returns always false.

Returns true on success. Otherwise the failure flag and error message is set.

Reads uSize bytes from the current position and puts them from offset uOffset in the passed byte buffer pucBytes.

Returns the number of bytes read or -1 on error.

Reads exactly one byte from the file. If a failure occurred 0 is returned and fail() returns true.

Closes the file. Called from the destructor.

Prints the content of the file to the standard output. This is performed regardless of the current file status (open or not, failure or not...).

Returns a boolean telling whether any failure occurred (the file can't be open or read).

Reads as many bytes as possible till to encounter a new line char in the file.

This function is Windows-compatible : ^M are ignored

Returns a string containing the read chars without the new line char.

Reads iSize bytes from the current position in the file. If iSize is negative (default value), all the bytes till the end of file are read. The read bytes are put to the passed string.

Returns the number of bytes read or -1 on error.

Sets the position from the beginning of the file at which the next read or write occurs. The seek function allows the file offset to be set beyond the end of the existing end-of-file of the file. If data is later written at this point, subsequent reads of the data in the gap return bytes of zeros (until data is actually written into the gap).

Moves of iOffset byte(s) the current position in the file at which the next read or write occurs

See also:

bool seek ( unsigned long uPos )

Shifts the content of the file of iByteOffset bytes. If the content is moved beyond the EOF, the file will grow up of byteOffset bytes. The first byteOffset bytes of the file will be set to 0. After the shift, the file pointer is pointing to the same data as before the shift. If the file pointer was initiallly located before the shifted data, it is repositioned at this location. Otherwise, it will move of iByteOffset.

If the content is moved toward the beginning of the file, the first byteOffset will be lost and the trailing byteOffset bytes set to 0. After the shift, the file pointer will point to the same data as before the shift, but only it is not part of the lost data. In this case, the pointer is positioned at the beginning of the file. If the file pointer was initiallly located on the shifted file area, it will move back of iByteOffset. Otherwise, it will be unchanged.

Returns false if the file opening mode is incompatible with this operation, i.e. if mode is either "w", "r" or "a".

This function is provided. It behaves like the referred to function below, the except that the start position of the shift is the current position.

See also:

Fills the file with the passed char from the current position

Returns a pointer on itself.

Inserts the string sBuf at the given file position. The initial content of the file starting at this position is shifted from the number of bytes of the string, using the shift() function.

See also:

bool shift ( unsigned long uFromPos , long byteOffset )

Lists the files of the directory.

The returned File objects do not open the file. Users may want to open the file afterwards for further processing.

If the file is a conventional file, the returned vector is empty and the failure flag is set.

See also:

bool isOpen ( ) const

virtual void open ( )

This file is part of the LLOOP LL Object-Oriented Parser Generator and Object Expander Generator. Copyright (c) 2005 Michel MEHL, France. All rights reserved. LLOOP is distributed by the company ERSA SaRL.