File Dll - Help
Made by Matrebatre
With this dll you can read and write to files, without getting errors if the file could not be opened. The standard GM functions like file_text_open_read will display an error message if the file could not be opened. The functions in this dll will just return 0 if the file could not be opened, so this way you can show your own error message to the user.
Most of the functions in this dll are about as fast as the standard functions in GM. However, the f_readfromfile function is a lot faster because GM doesn't have a function to read the entire file at once. (With the GM functions, opening a 1MB file can take minutes, but with f_readfromfile it takes about 0.2 seconds.)
If you are not using the extension, you should call filedll_init once before using the other functions.
You can open up to 16 files at the same time.
Text file functions:
f_text_open(filename,mode) - Opens a file in text mode. Filename is the file name (absolute or relative). Mode should be:
1 = f_mode_read: Opens for reading. Returns an error if the file does not exist.
2 = f_mode_write: Opens for writing and clears the existing file. Creates the file if it does not exist.
3 = f_mode_append: Opens for writing and sets the position to the end of the file. Creates the file if it does not exist.
Returns a file id (1-16) or 0 if the file could not be opened, or -1 if an error occurred (invalid mode or more than 16 files opened).
f_text_readline(fileid) - Reads a line from the file and stores it in the file buffer. If there was still data in the buffer this data will be lost. Returns 1, or 0 if the last line was read, or -1 if an error occurred (invalid file id).
f_text_read_dataleft(fileid) - Returns whether there is data left in the file buffer, or -1 if an error occurred (invalid file id).
f_text_read_real(fileid) - Reads a real from the file buffer. A real ends when a space or the end of the buffer is reached.
f_text_read_word(fileid) - Reads a word from the file buffer. A word ends when a space or the end of the buffer is reached.
f_text_read_string(fileid) - Reads a string from the file buffer. A string ends when the end of the buffer is reached.
f_text_writeline(fileid,addnewline) - Writes the file buffer to the file. Addnewline indicates whether to add a newline after the buffer. Returns 1, or -1 if an error occurred (invalid file id).
f_text_write_real(fileid) - Writes a real to the file buffer. If the buffer was not empty then a space will be added first. Returns 1, or -1 if an error occurred (invalid file id).
f_text_write_word(fileid) - Writes a word to the file buffer. If the buffer was not empty then a space will be added first. Returns 1, or -1 if an error occurred (invalid file id).
f_text_write_string(fileid) - Writes a string to the file buffer. If the buffer was not empty then a space will be added first. Returns 1, or -1 if an error occurred (invalid file id).
f_text_eof(fileid) - Returns whether the last line was read. This will return the same result as the last call to f_text_readline, so most of the time you won't need it. Returns -1 if an error occurred (invalid file id).
f_text_memoryerror(fileid) - Returns whether reading failed because of a memory error since the last call of this function. This will only happen if there was not enough free memory. Returns -1 if an error occurred (invalid file id).
f_text_close(fileid) - Closes the file with id fileid. Returns whether successful (almost always), or -1 if an error occurred (invalid file id). If the function fails, the file will still be closed but it might be corrupted.
Binary file functions:
All functions for reading/writing multi-byte integers use the big-endian format, which means the bytes that represent the biggest values are saved first. For example, 276 will be saved as 0-1-20.
f_bin_open(filename,mode) - Opens a file in binary mode. Filename is the file name (absolute or relative). Mode should be:
1 = tf_mode_read: Opens for reading. Returns an error if the file does not exist.
2 = tf_mode_write: Opens for writing and clears the existing file. Creates the file if it does not exist.
3 = tf_mode_append: Opens for writing and sets the position to the end of the file. Creates the file if it does not exist.
Returns a file id (1-16) or 0 if the file could not be opened, or -1 if an error occurred (invalid mode or more than 16 files opened).
f_bin_read_byte(fileid) - Reads a byte from the file. Returns the value of the byte, or 0 if the end of the file was reached. Returns 0 if an error occurred (invalid file id).
f_bin_read_byte2(fileid) - Reads 2 bytes from the file. Returns the value of the bytes, or 0 if the end of the file was reached. Returns 0 if an error occurred (invalid file id).
f_bin_read_byte3(fileid) - Reads 3 bytes from the file. Returns the value of the bytes, or 0 if the end of the file was reached. Returns 0 if an error occurred (invalid file id).
f_bin_write_byte(fileid,number) - Writes a byte to the file. Number can be 0-255. Returns 1, or -1 if an error occurred (invalid file id).
f_bin_write_byte2(fileid,number) - Writes 2 bytes to the file. Number can be 0-65535. Returns 1, or -1 if an error occurred (invalid file id).
f_bin_write_byte3(fileid,number) - Writes 3 bytes to the file. Number can be 0-16777215. Returns 1, or -1 if an error occurred (invalid file id).
f_bin_read_chars(fileid,length) - Reads length bytes from the file and returns them as a string. All NULL bytes in the string will be removed. Returns an empty string if an error occurred (invalid file id).
f_bin_write_chars(fileid,length,string) - Writes length bytes from the string to the file. If the string is shorter than length the remaining bytes will be filled with NULL bytes. If the string is longer it wil be truncated. Returns 1, or -1 if an error occurred (invalid file id).
f_bin_eof(fileid) - Returns whether the last reading function failed because it reached the end of the file. Normally your game should not depend on this function, but use it only for error checking. Returns -1 if an error occurred (invalid file id).
f_bin_seek(fileid,pos) - Sets the current reading/writing position of the file.
f_bin_memoryerror(fileid) - Returns whether reading failed because of a memory error since the last call of this function. This will only happen if there was not enough free memory. Returns -1 if an error occurred (invalid file id).
f_bin_close(fileid) - Closes the file with id fileid. Returns whether successful (almost always), or -1 if an error occurred (invalid file id). If the function fails, the file will still be closed but it might be corrupted.
Other file functions:
f_gettext() - Returns the text in the text buffer.
f_settext(string) - Sets the text in the text buffer. Returns 1, or -1 if an error occurred (not enough free memory).
f_cleartext() - Clears the text in the text buffer, freeing the memory used. This is not required, but it is a good idea to call this function after you used the text buffer.
f_readfromfile(fname) - Opens a text file and stores the contents in the text buffer. Returns whether successful, or -1 if an error occurred (not enough free memory).
f_writetofile(fname,append) - Creates a text file with the contents of the text buffer. Append indicates whether the text should be appended instead of rewriting the file. Returns whether successful.
Extra functions:
f_deletefile(filename) - Deletes a file. Returns whether successful.
f_renamefile(filename,newname) - Renames a file. Returns whether successful.
f_copyfile(filename,newname) - Copies a file. Returns whether successful.
Examples:
When you are using a text file to store data, and the number of lines is important, it is a good idea to have one empty line at the end of the file. This way it is easier to write to the file (addnewline should always be true) and you can also create a file with no data, which is not possible with the previous method (there will always be at least one (empty) line). To use this method, you could use this code:
Reading:
var f;
f = f_text_open('file.dat',1);
if f>0 {
while f_text_readline(f) {
show_message(f_text_read_string(f));
}
f_text_close(f);
} else {
show_message('Error opening the file!');
}
Writing:
var f;
f = f_text_open('file.dat',2);
if f>0 {
repeat 3 {
f_text_write_string(f,get_string('Enter a line:',''));
f_text_writeline(f,1);
}
f_text_close(f);
} else {
show_message('Error opening the file!');
}
If you want to use a log file to save error messages etc, you could use the f_writetofile function:
f_settext('An error occurred!'+chr(10)); // chr(10) is a newline character
f_writetofile('log.txt',1);
Good luck using this dll!