---

File Class Reference

A file object for reading, writing, or otherwise manipulating files. More...

#include <miodevice.h>

Inheritance diagram for File:

List of all members.

Public Methods
	File (FILE *str=stdout)
	File (const String &name, int mode=0) throw (open_failure)
bool	exists () const throw (system_failure)
bool	remove ()
virtual bool	open (int mode)
virtual void	close ()
virtual void	flush ()
virtual uint	size () const
virtual int	at () const
virtual bool	seek (int position)
virtual bool	atEnd () const
virtual int	readBlock (char *data, uint len) throw (device_not_open)
virtual int	readLine (char *data, uint maxlen) throw (device_not_open)
int	readLine (String &str, int maxlen=-1) throw (device_not_open)
virtual int	writeBlock (const char *data, uint len) throw (device_not_open)
virtual int	getch () throw (device_not_open)
virtual void	putch (char) throw (device_not_open)
virtual void	ungetch (char) throw (device_not_open)

---

Detailed Description

A file object for reading, writing, or otherwise manipulating files.

@example

     File myfile ("myfile.txt", IO_Readable);
     String linebuf;
     while (!in.atEnd()) {
         in.readLine (linebuf);
         sout << linebuf;
     }

For streamed interface, you can attach the file device to a stream.

Definition at line 188 of file miodevice.h.

---

Constructor & Destructor Documentation

File (  FILE *    file = stdout )

Standard constructor for File objects. It is assumed that the FILE stream is already opened. Parameters: file  An open FILE stream object to use. Definition at line 351 of file miodevice.cc.

File (  const String &    name, int    mode = 0 )  throw (open_failure)

Constructor. Creates a File object, and opens it if the mode parameter is given. If the mode parameter is not given, the file can be opened later, or the object can be used to perform also other tasks on the file, such as deletion, etc. Parameters: name  Name of the file to open. mode  Mode for opening. See open for details. Definition at line 370 of file miodevice.cc. References MagiC::i18n(), IO_Readable, and IO_Writable.

---

Member Function Documentation

int at (    )  const [virtual]

Returns the current position in device. Only meaningful for "block devices", which have a defined size. Reimplemented from IODevice. Definition at line 527 of file miodevice.cc. References MagiC::i18n().

bool atEnd (    )  const [virtual]

Returns true if currently at end of file, and false if not. Reimplemented from IODevice. Definition at line 558 of file miodevice.cc.

void close (    )  [virtual]

Closes the device. Flushes open buffers. Reimplemented from IODevice. Definition at line 478 of file miodevice.cc. References MagiC::i18n(), and IO_Open. Referenced by open().

bool exists (    )  const throw (system_failure)

Returns true if the file exists. Exceptions: system_failure  Thrown if there occurred some system problem while checking the existence of the file. Definition at line 398 of file miodevice.cc. References MagiC::i18n().

void flush (    )  [virtual]

Flushes (writes) the buffers. Flushing ensures that all data that has been written to the device is really written, and does not wait in a buffer. This is important if an application crashes unexpectedly, or if we just want to be able to read it immediately. This has only effect if the device has been opened for buffered writing. Reimplemented from IODevice. Definition at line 500 of file miodevice.cc. References MagiC::i18n().

int getch (    )  throw (device_not_open) [virtual]

Reads and returns one character from device. Returns: The character read. Reimplemented from IODevice. Definition at line 655 of file miodevice.cc. References MagiC::i18n(), and IO_EOS.

bool open (  int    mode )  [virtual]

Opens device with given I/O mode. Typical usage: File myFile ("/path/file.ext"); myFile.open (IO_Readable); String myFileContents = myFile.readAll (); myFile.close (); IO_Raw Raw (unbuffered) I/O mode IO_Readable The device is opened read-only IO_Writable The device is opened write-only IO_ReadWrite The device is opened read-write. This is equivalent to (IO_Readable | IO_Writable). IO_Append The device is appended, if possible IO_Truncate The device is truncated Exceptions: invalid_flags  if the combination of mode flags was somehow invalid. open_failure  if there was some other error while opening. Returns: true if successful, false if opening failed for an obvious reason. Reimplemented from IODevice. Definition at line 434 of file miodevice.cc. References close(), MagiC::i18n(), and String::isEmpty().

void putch (  char    ch )  throw (device_not_open) [virtual]

Writes one character to device. Reimplemented from IODevice. Definition at line 676 of file miodevice.cc. References MagiC::i18n().

int readBlock (  char *    data, uint    maxlen )  throw (device_not_open) [virtual]

Reads a data block of a given length to a buffer. The buffer must be allocated to contain the given length of bytes. Returns: The number of bytes actually read. Parameters: data  Data buffer to receive the block read. maxlen  Maximum number of bytes to read. Reimplemented from IODevice. Definition at line 572 of file miodevice.cc. References IO_EOS.

int readLine (  String &    buffer, int    maxlen = -1 )  throw (device_not_open)

Reads a newline-terminated line to a buffer. The buffer is grown as needed, so the maxlen parameter can be much greater than the allocated length of the buffer. Returns: Number of bytes actually read. Parameters: buffer  Data buffer to receive the line. maxlen  Maximum number of bytes to read or -1 for unlimited. Definition at line 616 of file miodevice.cc. References MagiC::i18n(), and IO_EOS.

int readLine (  char *    data, uint    maxlen )  throw (device_not_open) [virtual]

Reads a newline (\n) terminated line from device. The buffer must be allocated to contain the given length of bytes. The function spares one byte for the terminating zero, so the actual maximum number of bytes read is one less than the maxlen parameter. Example: // Read in chunks char buffer [1024]; int bytesRead = 0; int totalRead = 0; while (bytesRead = mpDevice->readLine (buffer, 1024)) { linebuf.append (buffer); totalRead += bytesRead; } Note: The default implementation reads the line with getch(). If you are implementing a device, you may want to implement a faster version that uses lower-level functions. Returns: Returns the number of bytes actually read, or 0 if none. Parameters: data  Data buffer to receive the line. maxlen  Maximum number of bytes to read. Reimplemented from IODevice. Definition at line 592 of file miodevice.cc. References IO_EOS.

bool remove (    )

Removes a file or directory from the filesystem. Returns: false if successful, true if failed for some reason. Definition at line 422 of file miodevice.cc.

bool seek (  int    position )  [virtual]

Changes the current position in device. The function has meaning only if the device is capable of direct access. Returns: true if successfull, false on failure. Reimplemented from IODevice. Definition at line 543 of file miodevice.cc. References MagiC::i18n().

uint size (    )  const [virtual]

Returns the size of the file. Reimplemented from IODevice. Definition at line 510 of file miodevice.cc. References MagiC::i18n().

void ungetch (  char    ch )  throw (device_not_open) [virtual]

Ungets the last character read from the device. Note: The file may be at EOF when this function is called. In such case, the function returns the object to non-EOF state. Reimplemented from IODevice. Definition at line 692 of file miodevice.cc. References MagiC::i18n(), and IO_EOS.

int writeBlock (  const char *    data, uint    len )  throw (device_not_open) [virtual]

Reads a block of data to file. Returns: Number of bytes actually written. Parameters: data  Data block to write. len  Length of the data block. Reimplemented from IODevice. Definition at line 639 of file miodevice.cc. References MagiC::i18n().

---

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

• miodevice.h
• miodevice.cc

---