GS9 Programming Language

FILES LIBRARY
A Programming Language Manual

fopen

( lib: Files, file: ../src/gs/gslib_files.cpp )

ptr fopen( filename, mode )

IN
str	filename	path to the file to be opened
int	mode	open mode 0=read, 1=write, 2=both
OUT
ptr	file handler

Opens the file with the path and name specified by the filename parameter.
If mode is 0 then the file will be opened only for read. File must exist.
If mode is 1 then the file will be opened only for write. If not found, the file is created, otherwise it's content will cleared.
If mode is 2 then the file will be opened for both read and write. If not found, the file is created. Useful for appending new data.
If the open is successful, the file handler is returned. If not, it will return an invalid ptr (NULL).
The directories from the specified file path must always exist.
Remember that to specify the backslash in file paths, you must use a double backslash (like "c:\\myfile.txt")
The file cursor is the current position inside the file (in bytes), where the next read or write will take place.
When a file is opened, it's file cursor is set from the beginning of the file (0).
Always remeber to finaly close opened files, with gs_fileclose.

// will load and print the program file
func main()
{
	f = fopen("program.txt",0);        // open for read the program file
	if(f)                                 // if opened successfuly
	{
		fseek(f,0,2);                  // move read cursor to the end of the file to get the file size
		size = fsize(f);               // get file's size
		s = freads( f, buffer, size ); // read file's content as a string
		fclose(f);                     // close file
		println(s);                       // displaying the content with prinln is limited to a decent size
	}
}

C/C++ source code

fsize

( lib: Files, file: ../src/gs/gslib_files.cpp )

int fsize( f )

IN
ptr	f	file handler
OUT
int	file's size

Returns the file's size in bytes
See gs_fopen for examples.

C/C++ source code

fseek

( lib: Files, file: ../src/gs/gslib_files.cpp )

int fseek( f, pos, mode )

IN
ptr	f	file handler
int	pos	position to seek to
int	mode	seek mode 0=beginning, 1=current, 2=end
OUT
int	1=success, 0=fail

Moves file cursor to the specified position in file.
If mode is 0, pos position is considered from the beginning of the file and it must be positive or zero.
If mode is 1, pos position is considered as an offset from where the cursor is right now.
If mode is 2, pos position is considered from the end of the file and it must be negative or zero.

C/C++ source code

ftell

( lib: Files, file: ../src/gs/gslib_files.cpp )

int ftell( f )

IN
ptr	f	file handler
OUT
int	current position or -1 if error

Returns the current position of the file cursor (in bytes).

C/C++ source code

fwrite

( lib: Files, file: ../src/gs/gslib_files.cpp )

int fwrite( f, buffer, pos, size )

IN
ptr	f	file handler
ptr	buffer	memory buffer
int	pos	position in buffer where to write
int	size	number of bytes to write
OUT
int	written size

Writes size bytes from given buffer from pos position, into the file at the current position of the file cursor.
If less than size is returned, then an error occured.
Take great care not to exceed of buffer's bounds.
The file must be opened for write.

C/C++ source code

fwriteb

( lib: Files, file: ../src/gs/gslib_files.cpp )

int fwriteb( f, v )

IN
ptr	f	file handler
int	v	byte number to write
OUT
int	1=success, 0=fail

Writes the byte value of the parameter v in the file f at the current position of the file cursor.
The file cursor will be incremented with 1 byte.
The file must be opened for write.

C/C++ source code

fwritew

( lib: Files, file: ../src/gs/gslib_files.cpp )

int fwritew( f, v )

IN
ptr	f	file handler
int	v	word number to write
OUT
int	1=success, 0=fail

Writes the word value of the parameter v in the file f at the current position of the file cursor.
The file cursor will be incremented with 2 bytes.
The file must be opened for write.

C/C++ source code

fwritei

( lib: Files, file: ../src/gs/gslib_files.cpp )

int fwritei( f, v )

IN
ptr	f	file handler
int	v	integer number to write
OUT
int	1=success, 0=fail

Writes the integer value of the parameter v in the file f at the current position of the file cursor.
The file cursor will be incremented with 4 bytes.
The file must be opened for write.

C/C++ source code

fwritef

( lib: Files, file: ../src/gs/gslib_files.cpp )

int fwritef( f, v )

IN
ptr	f	file handler
flt	v	float number to write
OUT
int	1=success, 0=fail

Writes the float value of the parameter v in the file f at the current position of the file cursor.
The file currsor will be incremented with 4 bytes.
The file must be opened for write.

C/C++ source code

fwrites

( lib: Files, file: ../src/gs/gslib_files.cpp )

int fwrites( f, s, size )

IN
ptr	f	file handler
str	s	string to write
int	size	size to write (optional)
OUT
int	1=success, 0=fail

Writes size characters from string s in file f at the current position of the file cursor.
If size is greater then the string's length, the rest of the characters written will be 0.
If size is not specified, the string's length is used.
The file must be opened for write.

func main()
{
	f = fopen("testfile.txt",1);
	fwrites(f,"This is a line of text.\n");
	fwrites(f,"This is another line of text.\r\nAnd yet, another one.");
	fclose(f);
}

C/C++ source code

fwritetext

( lib: Files, file: ../src/gs/gslib_files.cpp )

int fwritetext( f, s )

IN
ptr	f	file handler
str	s	text line to write
OUT
int	1=success, 0=fail

Writes a line of text. EOL characters (/r/n) are written after the text.
The file must be opened for write.

C/C++ source code

fread

( lib: Files, file: ../src/gs/gslib_files.cpp )

int fread( f, buffer, pos, size )

IN
ptr	f	file handler
ptr	buffer	memory buffer
int	pos	position to read into
int	size	number of bytes to read
OUT
int	read size

Reads size bytes in given buffer at psoition pos.
If less than size is returned, then an error occured.
Take great care not to exceed of buffer's bounds.

C/C++ source code

freadb

( lib: Files, file: ../src/gs/gslib_files.cpp )

int, int freadb( f )

IN
ptr	f	file handler
OUT
int	read byte
int	1=success, 0=fail

Reads a byte value from file f and increment the file cursor with 1 byte.
If the operation fails, a 0 value is returned.

C/C++ source code

freadw

( lib: Files, file: ../src/gs/gslib_files.cpp )

int, int freadw( f )

IN
ptr	f	file handler
OUT
int	read word
int	1=success, 0=fail

Reads a word value from file f and increment the file cursor with 2 bytes.
If the operation fails, a 0 value is returned.

C/C++ source code

freadi

( lib: Files, file: ../src/gs/gslib_files.cpp )

int, int freadi( f )

IN
ptr	f	file handler
OUT
int	read integer
int	1=success, 0=fail

Reads an integer value from file f and increment the file cursor with 4 bytes.
If the operation fails, a 0 value is returned.

C/C++ source code

freadf

( lib: Files, file: ../src/gs/gslib_files.cpp )

flt, int freadf( f )

IN
ptr	f	file handler
OUT
flt	read float
int	1=success, 0=fail

Reads a float value from file f and increment the file cursor with 4 bytes.
If the operation fails, a 0 value is returned.

C/C++ source code

freads

( lib: Files, file: ../src/gs/gslib_files.cpp )

str, int freads( f, size )

IN
ptr	f	file handler
int	size	size to read (in bytes)
OUT
str	read string
int	1=success, 0=fail

Reads the given number of characters (bytes) from file f.
If a 0 value is encountered, the string's length will be less than size,
but the file cursor will still be increnented with size bytes.
If the operation fails, an empty string value is returned.

func main()
{
	s = "123";
	f = fopen("testfile.txt,1);
	fwrites(f,s,8); // will write 5 additional 0 bytes
	fclose(f);
	f = fopen("testfile.txt,0);
	s = freads(f,8); // will read 8 bytes but return "123"
	fclose(f);
}

C/C++ source code

freadtext

( lib: Files, file: ../src/gs/gslib_files.cpp )

str, int freadtext( f )

IN
ptr	f	file handler
OUT
str	read text line
int	1=success, 0=fail

Reads a line of text based on EOL characters (\n or \r)
If the operation fails, an empty string value is returned.

C/C++ source code

fclose

( lib: Files, file: ../src/gs/gslib_files.cpp )

int fclose( f )

IN
ptr	f	file handler
OUT
int	1=success, 0=fail

Closes the file handler f.
After closing the file, the handler f becomes invalid, and the file requires another opening if more read or write is needed.

C/C++ source code