-
Notifications
You must be signed in to change notification settings - Fork 42
Functions
In this section each of the functions in Q OS are described in detail so that developers of Q OS can use them without studying the source code.
If you are writing a new function for Q OS in a forked version of the master branch, please create a subsection here that goes into detail about what your function does, how to use it and (briefly), why it works.
uint16 strlen(string ch);
This is one of the simplest functions in Q OS at the moment with the sole purpose of returning the length of the specified string. It is declared in stringUtils.h and initialised in stringUtils.c. To use the function, simply use strlen(string), replacing string with the string you want to get the length of. For example, to get the length of a string called myString which must be previously declared and initialised, you can use strlen(myString);. To get the length of a string that you want to hard code into the output, you can for example do this: strlen("This is the string that we will get the length of");. There is little purpose in doing this because you can just specify the length of the string if it will always be the same, but it works nevertheless.
Because strlength returns an integer, you can use it to set any integer type variable to the length of the string you are assessing. For this usage, you will need to create or use a pre-existing integer to store the length of the string you want to evaluate and you will need to use a pre-existing string type variable to assess the length of. Assuming we want to find the length of myAwesomeString and store it in the integer value aCoolInt which does not already exist, we can simply enter this line of code: uint16 aCoolInt = strlen(myAwesomeString);.
The strlength function works by creating a uint16 variable called i and then looping through each letter of ch, which is equal to the string you enter when invoking the function, until you reach the last letter of ch, and by that point i will be equal to the amount of characters in ch. You can see the code behind the strlen function in /inc/stringUtils.c or below:
uint16 strlen(string ch)
{
uint16 i = 1;
while(ch[i++]);
return --i;
}bool streql(string ch1,string ch2);
The streql is a very powerful, simple and effective function contained in stringUtils.c and declared in stringUtils.h. It is used to compare two strings and returns true when they are equal and false if they are not equal. Usage:
int main()
{
if(streql("Foo","Bar"))
{
print("Foo is equal");
return 1;
}
else
{
print("Foo is not equal");
return 0;
}
}Output:
Foo is not equal
Really!? Near fully compatible with the major implementations.
// Prints this extremely frequently seen text in black
printf("Hello, world!");The clearLine() function clears the specified line.
updateCursor is used to make sure that the cursor is at the current position defined by cursorX and cursorY. All processes in Q OS have access to the cursorX and cursorY values, so they should not be overused or all the processes will cease to work due to the cursor moving at unexpected times.
The clearScreen command simply loops through each line number using the clearLine command to clear all text on the screen.
The scrollUp command moves the text on the screen up by the amount of lines specified in brackets.
This function just checks if the cursor is off the screen, and if it is then it executes scrollUp(1) to move the text up one line.
This function is a varadic function:
key_pressed waitUntilKey(amount of keys, key1, key2, ...)Example from function messageBox_YN
// First parameter is 3 because there are 3 possible keys
int val = waitUntilKey(3, 0x15 /*Y*/, 0x31, /*N*/, 0x2E /*C*/);
switch(val)
{
case 0x15: // Y was pressed
case 0x31: // N was pressed
case 0x2E: // C was pressed
}This function is used to print a single character to the screen. Writing that exact code would print the letter A in white at the current position of the cursor, which you can modify by changing the values of cursorX and cursorY. Usage:
int main()
{
printch('A', black);
return 0;
}Output:
A
The print function can be used to print any amount of characters to the screen in the colour you want. That example would print Enter some text to print to the screen at the current cursorX and cursorY position in the hexadecimal colour 0x3A. You can specify any 8-bit hex colour and also any text you want.
The print function theoretically supports any characters in the current Unicode character subset but some may display differently on different systems.
Usage:
print("Enter some text to print to the screen", 0x3A);Output:
Enter some text to print to the screen
string readstr(); string readpasswd();
Used to get input from the end user in a text based form, both functions will initiate a blinking cursor and allow the user to type using an attached keyboard and receive input on the screen. Both functions returns a string output. Usage:
string myCoolString = readstr();
// The screen shows up * instead of the actual chars
string myPasswdStr = readpasswd();Output: Function returns no output
uint8 inportb (uint16 _port);
Read a single 8-bit I/O port. This is a complex function that will return the value in a port that you specify. Usage:
#include "assemblyFunctions.h"
int main()
{
//Get value from address 0x70
return inportb (0x70);
}Output: This function will return whatever value is in that I/O port
void outportb (uint16 _port, uint8 _data);
Write a single 8-bit I/O port. This is a assembly based function that lets you put data into a specified port. Usage:
#include "assemblyFunctions.h"
int main() {
//Copy to address
outportb (0x70, 0x0A);
}Output: Function returns no output
int getTime(strings args);
Return the current time value as int from argument passed. Accepted arguments:
- year - Return current year
- month - Return current month (NYI)
- day - (NYI)
- hour - (NYI)
- minute - (NYI)
- second - (NYI)
Usage:
#include "math.h"
int main()
{
printf("%d", getTime("year"));
}Output:
2015