GS9 Programming Language

DEFAULT LIBRARY
A Programming Language Manual

print

( lib: Default, file: gslib_default.cpp )

print( ... )

IN
...	...	any number of parameters of any type is accepted

Can handle multiple parameters of any type, printing all their values in the console, one by one.
There's an decent limit of length when printing, so huge texts will not be fully displayed.

// will print "one" and "two" on the same line and "three" on the next one
print("one ","two \n","three ");
// will print "four" on the same line with previous "three"
print("four ");

C/C++ source code

println

( lib: Default, file: gslib_default.cpp )

println( ... )

IN
...	...	any number of parameters of any type is accepted

Can handle multiple parameters of any type, printing all their values in the console, one by one.
It also adds a new line character (\n), so the next print call will write it's text on the next line.
There's an decent limit of length when printing, so huge texts will not be fully displayed.

// will print "one" and "two" on the same line and "three" on the next line.
println("one ","two ");
println("three ");

C/C++ source code

scanln

( lib: Default, file: gslib_default.cpp )

str scanln( )

OUT
str	input line

Waits for the user to input some text in the console and to hit enter, then returns it as a string.
This instruction is usefull only in text console applications.
There's an decent limit of input text (256 characters).

sz = scanln(); // will wait for input and enter key
print(sz);     // will print the entered text

C/C++ source code

getch

( lib: Default, file: gslib_default.cpp )

int getch( )

OUT
int	key code

Waits for the user to hit a key and returns the key's code.
For printable characters the key code is the associated ASCII code.
For special keys like arrows or function keys, the codes are higher values.

ch = getch();  // will wait for a key press
print(ch);     // will print the key code

C/C++ source code

tabsize

( lib: Default, file: gslib_default.cpp )

int tabsize( t )

IN
reftab	t	reference to table
OUT
int	table size

Returns the number of elements from the table refered by t, or 0 if bad parameter.
Similar to sizeof.

t = {'a','b','c'};
println( tabsize(&t) ); // will print 3

C/C++ source code

tabresize

( lib: Default, file: gslib_default.cpp )

tabresize( t, size )

IN
reftab	t	reference to table
int	size	new table size

Resizes the table refered by t.
If the new size is smaller than the old size, the last elements will be deleted.
If the new size is bigger, then the new elements, added at the end of the table, will have NUL values.

t={1,2,3};
println(t);       // will print [1,2,3]
tabresize(&t,5);  // grow
println(t);       // will print [1,2,3,NUL,NUL]
tabresize(&t,2);  // shrink
println(t);       // will print [1,2]

C/C++ source code

tabdel

( lib: Default, file: gslib_default.cpp )

tabdel( t, pos, count )

IN
reftab	t	reference to table
int	pos	position to start deleting
int	count	number of elements to delete

Deletes count elements from the table refered by t, starting from position pos.
The last elements remaining are shifted and the table is resized.

t={1,2,3,4};
println(t);		// will print [1,2,3,4]
tabdel(&t,1,2);	// delete two elements from the position 1
println(t);		// will print [1,4]

C/C++ source code

tabins

( lib: Default, file: gslib_default.cpp )

tabins( t, pos, count )

IN
reftab	t	reference to table
int	pos	position where to start insertion
int	count	number of elements to insert

Inserts count elements into the table refered by t, starting from position pos.
The inserted elements will have NUL values.
The last elements after the insertion, are shifted and the table is resized.

t={1,2,3};
println(t);		// will print [1,2,3]
tabins(&t,1,2);	// insert two new elements, starting with position 1
println(t);		// will print [1,NUL,NUL,2,3]

C/C++ source code

tabadd

( lib: Default, file: gslib_default.cpp )

tabadd( t, count )

IN
reftab	t	reference to table
int	count	number of elements to add at the end of the table

Adds count elements at the end of the table refered by t.

t={1,2,3};
println(t);		// will print [1,2,3]
tabadd(&t,2);
println(t);		// will print [1,2,3,NUL,NUL]

C/C++ source code

strempty

( lib: Default, file: gslib_default.cpp )

int strempty( s )

IN
str\|refstr	s	string or reference to string
OUT
int	true if string is empty or false if not

Returns true (1) if the string s (or the string refered by s) is empty or VOID and false (0) if not.
Empty strings have the length 0 and their first element is always the eos character (0).
Invalid strings (VOID) have the length 0, by convention.

C/C++ source code

strlen

( lib: Default, file: gslib_default.cpp )

int strlen( s )

IN
str\|refstr	s	string or reference to string
OUT
int	string's length

Returns the number of characters in the string s (or the string refered by s), until the eos character (0) is reached.
For empty or invalid strings it will return 0.

println( strlen("test") ); // will print 4
println( strlen("") );     // will print 0

C/C++ source code

strpos

( lib: Default, file: gslib_default.cpp )

int strpos( s1, s2, pos=0 )

IN
str\|refstr	s1	string to search in
str\|refstr	s2	string to search for
int	pos=0	search starting position (optional)
OUT
int	found position or -1 if not found

Searches in the string s1 for the presence of string s2, starting from the specified position #pos.
If the start position is not specified, the search will begin with the first character of s1 (at position 0).
Returns the first position where s2 was found, or -1 if not found at all.

// will print 2, because of the word 'this'
println( strpos("this is a test","is") );
// will print -1, because we didn't start from the beginning
println( strpos("this is a test","this", 2) );

C/C++ source code

strchr

( lib: Default, file: gslib_default.cpp )

int strchr( s1, s2, pos=0 )

IN
str \| refstr	s1	string to search in
str \| refstr	s2	characters to search for
int	pos=0	search starting position (optional)
OUT
int	found position or -1 if not found

Searches for any characters from string s2 that are present in string s1.
If the start position is not specified, the search will begin with the first character of s1 (at position 0).
Returns the first position in s1, where a character form the s2 was found.
If, from the specified start position, until the end of s1, no characters from the second string were found, -1 is returned.

println( strchr("12b3ca45", "abcd") );    // will print 2, because b was found
println( strchr("12b3ca45", "abcd", 6) ); // will print -1

C/C++ source code

strskip

( lib: Default, file: gslib_default.cpp )

int strskip( s1, s2, pos=0 )

IN
str\|refstr	s1	string to process
str\|refstr	s2	characters to skip
int	pos=0	position to start skipping (optional)
OUT
int	position after skipping

Starting with the specified position in string s1, it skips all characters that belong to the second string s2.
If the start position is not specified, the processing will begin with the first character of s1 (at position 0).
Returns the position of the first character in s1, that is not found in s2.
If all characters from s1 are found in the s2 too, then all the length of s1 is returned.
If any of the strings are invalid, -1 will be returned to mark the error.

// will print 4, because we start with position 1
// and skip 3 characters from the second string
println( strskip("1bac234dd","abcd",1) );

C/C++ source code

strlwr

( lib: Default, file: gslib_default.cpp )

str strlwr( s )

IN
str\|refstr	s	string or reference to string
OUT
str	lower case string

Returns the string s converted to lower case.
All characters from 'A' to 'Z' become 'a' to 'z'.
If the string is invalid, an invalid string will be returned.

println( strlwr("Gs9") ); // will print "gs9"

C/C++ source code

strupr

( lib: Default, file: gslib_default.cpp )

str strupr( s )

IN
str\|refstr	s	string or reference to string
OUT
str	upper case string

Returns the string s converted to upper case.
All characters from 'a' to 'z' become 'A' to 'Z'.
If the string is invalid, an invalid string will be returned.

println( strlwr("Gs9") ); // will print "GS9"

C/C++ source code

strsub

( lib: Default, file: gslib_default.cpp )

str strsub( s, pos, count )

IN
str\|ref_str	s	string to substract from
int	pos	position of the substring
int=all	count	number of elements of the substring (optional)
OUT
str	substring

Returns a substring (a part) of the string s, starting with position pos and containing count characters (if available).
If the optional count parameter is not specified, the substring will represent the last part s1, from the start position, up to the eos character.
If any of the strings are invalid, an invalid string will be returned.

println( strsub("this is a test",5,2) ); // will print "is"
println( strsub("this is a test",5) );   // will print "is a test"

C/C++ source code

strtrim

( lib: Default, file: gslib_default.cpp )

str strtrim( s1, s2 )

IN
str\|refstr	s1	string to be trimmed
str\|refstr	s2	characters to trim
OUT
str	trimmed string

Processes the string s1 by removing beginning and ending characters that are also found in string s2 and return the result.
If any of the strings is invalid, an invalid string will be returned.

println( strtrim("b12c3dd","abcd") ); // will print "12c3"

C/C++ source code

strexplode

( lib: Default, file: gslib_default.cpp )

tab strexplode( s, separator )

IN
str\|refstr	s	string or reference to string
int	separator	ASCII code of the separator character
OUT
tab	exploded table with substrings

Creates a table containing substrings from s, separated by a specified character.
The separator character is given throught it's ASCII code.
If the input string is invalid, an invalid string will be returned.

// will print the table ["one","two","three"]
println( strexplode("one;two;three",';') );

C/C++ source code

strimplode

( lib: Default, file: gslib_default.cpp )

str strimplode( t, separator )

IN
tab\|reftab	t	table of substrings
int	separator	ASCII code of the separator character
OUT
str	imploded string with separators

Concatenates all the valid string elements from a table t, into a string, separating them with a specified character.
Non string elements from the table are ignored.

// will print the string "one;two;three"
println( strimplode({"one","two","three"},';') );

C/C++ source code

gs_time

( lib: Default, file: gslib_default.cpp )

int gs_time( )

OUT
int	tickcount time (ms)

Returns the computer's time counter, called Tick Count, in milliseconds (1sec = 1000 ms).
This counter is incremented each millisecond, since the computer was started.
This function can be used to track time.

C/C++ source code

gs_systemtime

( lib: Default, file: gslib_default.cpp )

gs_systemtime( hour, minute, second )

IN
refint	hour	computer current hour [0..23]
refint	minute	computer current minute [0..59]
refint	second	computer current second [0..59]

Returns in the reference parameters the computer's curent time.

C/C++ source code

gs_systemdate

( lib: Default, file: gslib_default.cpp )

gs_systemdate( year, month, day )

IN
refint	year	computer's current year
refint	month	computer's current month [0..11]
refint	day	computer's current day [0..31]

Returns in the reference parameters the computer's curent date.

C/C++ source code

gs_rand

( lib: Default, file: gslib_default.cpp )

int gs_rand( range=100 )

IN
int	range=100	generation interval from 0 to range (optional)
OUT
int	random value in given range

Returns an integer random number in a specified range, form 0 up to #range-1.
If #range parameter is missing a default range of 100 will be used.

println( gs_rand(10) ); // will print a number between 0 and 9 (inclusive)

C/C++ source code

gs_frand

( lib: Default, file: gslib_default.cpp )

float gs_frand( range=1.0 )

IN
float	range=1.0	generation interval from 0 to range (optional)
OUT
float	random value in given range

Returns a float random number in a specified range, form 0.0 up to almost #range.
If #range parameter is missing a default range of 1.0 will be used.

println( gs_rand(10.0) ); // will print a number between 0.0 and 9.999999

C/C++ source code

gs_srand

( lib: Default, file: gslib_default.cpp )

gs_srand( seed=time )

IN
int	seed=time	random generator seed (optional)

Resets the random numbers generator, with a specified #seed value.
After calling this function with the same seed, the same random pattern will be generated by calls of gs_rand.
By default, if no seed is specified, a value based on the computer's time counter is used, so the random pattern will be different each time.

gs_srand(1000);        // fixed seed
println(gs_rand(100)); // will print the same number, on every program execution
gs_srand(gs_time());   // variable seed
println(gs_rand(100)); // will print different numbers each time

C/C++ source code

gs_gid

( lib: Default, file: gslib_default.cpp )

int gs_gid( varname )

IN
str	varname	global variable's name
OUT
int	variable's id or -1 if not found

Returns the internal id of the varname global variable.
If no global variable is found with the specified name, -1 will be returned.
The id can be used in var commands, to access the variable.
See the Advanced access chapter.

C/C++ source code

gs_fid

( lib: Default, file: gslib_default.cpp )

int gs_fid( funcname )

IN
str	funcname	function's name
OUT
int	finction's id or -1 if not found

Returns the internal id of the funcname function.
If no function is found with the specified name, -1 will be returned.
The id can be used in call commands, to call the function.
See the Advanced access chapter.

C/C++ source code

gs_gidname

( lib: Default, file: gslib_default.cpp )

str gs_gidname( gid )

IN
int	gid	global variable's id
OUT
str	global variable's name or VOID if not found

Returns the name of a global variable with the gid internal id.
If no global variable was found with the specified id, VOID will be returned.
Use gs_gid to obtain the id of a global variable.
See the Advanced access chapter.

C/C++ source code

gs_fidname

( lib: Default, file: gslib_default.cpp )

str gs_fidname( fid )

IN
int	fid	function's id
OUT
str	function's name or VOID if not found

Returns the name of a function with the fid internal id.
If no function was found with the specified id, VOID will be returned.
Use gs_fid to obtain the id of a function.
See the Advanced access chapter.

C/C++ source code

gs_compilefile

( lib: Default, file: gslib_default.cpp )

int gs_compilefile( programfile )

IN
str	programfile	path to a valid program file
OUT
int	1=success, 0=fail

Compiles the program contained in the specified file and remember it's content.
The content of the file must be a valid GS9 program (with functions).
If an error occures or the file is not found, it will return false.
Somehow similar to the #include instruction.

C/C++ source code

gs_compilestring

( lib: Default, file: gslib_default.cpp )

int gs_compilestring( programtext )

IN
str	programtext	valid program text
OUT
int	1=success, 0=fail

Compiles the program contained in the specified string and remember it's content.
The content of the string must be a valid GS9 program (with functions).

C/C++ source code

gs_dofile

( lib: Default, file: gslib_default.cpp )

int gs_dofile( codefile )

IN
str	codefile	path to a valid instructions file
OUT
int	1=success, 0=fail

Compiles and execute the instructions contained in the specified file, than forget it's content.
The file must contain valid GS9 instructions, but no functions or other global declarations.
The effect will be like if the code from the file would be in a temporary function and that function is called right there.

C/C++ source code

gs_dostring

( lib: Default, file: gslib_default.cpp )

int gs_dostring( codetext )

IN
str	codetext	valid instrutions text
OUT
int	1=success, 0=fail

Compiles and execute the instructions contained in the specified string, than forget it's content.
The string must contain valid GS9 instructions, but no functions or other global declarations.
The effect will be like if the code from the string would be in a temporary function and that function is called right there.

println("one");                      // will print one
gs_dostring( "println(\"two\");" );  // will print two
println("three");                    // will print three

C/C++ source code

gs_error

( lib: Default, file: gslib_default.cpp )

gs_error( info )

IN
str	info	error info (optional)

Generates an user error and stop the execution of the program.
If info is specified, the text will be reported along with the error.
It can be used to handle critical errors, that usually shouldn't happend, and to stop program in a "controlled" way.

C/C++ source code

gs_debug

( lib: Default, file: gslib_default.cpp )

gs_debug( debuglevel )

IN
int	debuglevel	binary debug flags

This function is used for advanced debuging.
It changes the processor level of debug, to receive more or less information when an error occures.
The debug level is an integer value with various flag options stored on bits.
bit 0: halt on errors, with a message box info
bit 1: log error description and short call stack info
bit 2: list current function machine code (used when bit 4 is set)
bit 3: list data on the stack (used when bit 4 is set)
bit 4: list extensive info about the current call stack (use bit 2 and 3)
bit 5: dump global variables with names and values
bit 6: dump all functions assemler code
The default level of debug is 3 (halt and short description) and should be enough to track most common errors.

gs_debug(255); // set all debug bits for the highest level of debug
a = b+1;       // this will produce an error, because b is NUL

C/C++ source code