| Header file: | filestream.h |
| Object name: | fFILESTREAM |
| Object index: | 1 of 1 Object |
The filestream object is a wrapper for the C++ class fstream. I thought I might add a few extra properties to make this pretty simple component work even more simply.
Originally I attempted to write a version of this class that uses the Win32 API, but this failed miserably. Instead I used the C++ classes. However, the only problem with using the C++ classes is bloat - using the component adds 60-70kb to your executables size. However, I feel as though it's a small price to pay for something like this. Maybe in the future there will be a fAPIFILESTREAM.
Note: this class will happily compile and work under Linux too.
All of the flags listed here can be used with the OpenNormalFile() function. They are a mixture of substyles, and it should cover all that you need to do.
| Name | Description | Value |
| fmCreate | This creates a file for output. If the file already exists, then the contents are erased. | ios::out | ios::binary | ios::trunc |
| fmOpenRead | This style opens the file for reading. | ios::in | ios::binary |
| fmOpenWrite | This style opens the file ready to write to. | ios::out | ios::binary |
| fmOpen | This style opens the file for reading and/or writing. | ios::in | ios::out | ios::binary |
| fmAppend | This style opens the file to append whatever you write to the end of it. In other words, once the file is open, it seeks to the end of the file. | ios::app | ios::out | ios::binary |
These styles are used with the seek command to make it search from one point to another.
| Name | Description | Value |
| skBeginning | This style seeks to the location specified from the start of the file. | ios::beg |
| skFromCurrent | This style seeks from the current position in the file. | ios::cur |
| skToEnd | This style seeks directly to the end of the file. Useful if you decide you want to append data. | ios::end |
| Name | Description |
| fstream File; |
This member is the fstream object that the class uses. You have unlimited access to this member - and it doesn't matter what you do to it because the rest of the class works around what this object tells it at any given time. It may be useful to use this to acheive some other things that you can not nessecarily do with the usual functions provided. You would access this member as fFILESTREAM.File.FunctionName(). A useful thing that you might be able to use this for is to read data from a file and place it in a certain buffer that you already have, rather than having the class buffer it for you.
|
| bstring Buffer; | This member is the bstring buffer that is used for functions such as ReadLine() and ReadData(). If you lost the pointer when you used these functions, or they were not appropriate, then you can get the pointer again. You can fiddle with this as much as you want; it won't make any difference to the class. But please don't put anything important in the buffer - it will only be erased when you use some of the functions in the fFILESTREAM class. |
| Prototype | Description |
| bool OpenNormalFile(char* Name, int Method); | This function opens a file. You pass along a filename and a method of opening the file (the styles from the first table in this document) and it will return TRUE if successful, or FALSE otherwise. |
| void CloseFile(void); | This function closes the file. No more description should be needed. |
| bool Eof(void); | This function determines if the file is at it's end - ie, you've read enough data that it is now at the end of the file. |
| int GetSize(void); | This function returns the size of the currently open file, in bytes. |
| int ReadPosition(void); | This function returns the position at which the class will next read data from. |
| int WritePosition(void); | This function returns the position at which the class will next write data to. |
| void SeekRead(_seek_dir Direction, int Offset); | This function sets where the class will next read data from. The first parameter is one of the values from the second table from the top of this document, and the other value is a numeric value in bytes. |
| void SeekWrite(_seek_dir Direction, int Offset); | This function sets where the class will next write data to. The first parameter is one of the values from the second table from the top of this document, and the other value is a numeric value in bytes. |
| char* ReadLine(void); | This function reads one line of text from a text file and returns the pointer to that text. The line of text returned is terminated with return characters suitable for Windows purposes (ie. a CR+LF is tacked onto the end). However, the function has been written so that it can support UNIX or DOS style text files (LF vs CR+LF). |
| char* ReadData(int Size); | This function reads a block of data of the specified size. It allocates memory to store this and returns the pointer to that. Please note that if you use this function again, you will lose what the pointer pointed to last time. |
| void EmptyFBuffer(void); | This function empties the buffer that the component maintains to allow it to pass back pointers. Mostly the memory tied up will be in small amounts, but if you request large blocks in the above function, you might like to empty the buffer when you are done. |
| int ReadInt(void); | This function reads an integer number from a text file. |
| double ReadFloat(void); | This function reads a float number from a text file. |
| void WriteText(char* Text); | This function writes text to a text file. Simple. |
| void WriteEndLine(void); | This function writes the end line characters to file. This is useful after the last function, to terminate that line. The return characters written are the CR+LF characters, which Windows/DOS likes. |
| void WriteInt(int Number); | This function writes an integer number to file. Please note that the number is written as it's string equivalent. |
| void WriteFloat(double Number); | This function writes a float number to file. Please note that the number is written as a it's string equivalent. |
| void WriteData(char* Pointer, int Size); | This function writes a block of data to file. All you need to do is specify a pointer to the block that you want to write, and also tell the function how many bytes to write. It's as simple as that. |
| void Flush(void); | This function forces the file's buffer to flush. Ordinarily Windows may use lazy flushes, which you might like to override, depending on what you are doing. |
The following snippet gives a basic idea of how to use this component.
//Let's do some file handling!!
fFILESTREAM File;
//Create a file...
File.OpenNormalFile("c:\test.txt", fmCreate);
//Then write some data to it...
File.WriteText("Hello there! This is a test!!");
File.WriteEndLine();
File.WriteText("This is the next line. Isn't this cool?");
File.WriteEndLine();
//Maybe close the file, and do something
//more serious...
File.CloseFile();
//Let's be dangerous...
File.OpenNormalFile("c:\windows\shell32.dll", fmOpenRead);
... = File.GetSize(); //Find the size.
... = File.ReadData(1000); //Read 1000 bytes.
File.CloseFile();
| Back to index | The FreeFoote Foundation Classes Documentation |