From 9a1071f7e7737b884a6245358da17c735132a627 Mon Sep 17 00:00:00 2001 From: "U-SWANOS\\Swanos" Date: Mon, 18 Sep 2023 20:30:16 +1000 Subject: [PATCH] Getting Started With SplashKit Database --- ...Getting Started With SplashKit Database.md | 318 ++++++++++++++++++ 1 file changed, 318 insertions(+) create mode 100644 docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With SplashKit Database.md diff --git a/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With SplashKit Database.md b/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With SplashKit Database.md new file mode 100644 index 000000000..64eb84773 --- /dev/null +++ b/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With SplashKit Database.md @@ -0,0 +1,318 @@ +# Getting Started With SplashKit Database + +## Introduction + +### What is SplashKit Database? + +SplashKit has a database library that allows you to create or load databases and perform queries on +them. These databases are stored in database files, and with functions from the SplashKit library, +we can query and manipulate the database. + +### Usage + +You may have learned the use of database, which is for storing information. On SplashKit, you may +want to use database to store information of different users who have access to the game, such as +levels, high score, or save files. You may also want to use databases when creating data heavy +games, e.g., to store information about all the different items, skills, weapons, etc. available in +game. + +## Opening Database in SplashKit + +### Database + +Accessed databases are stored in the `Database` object. + +### Open Database + +`Open Database` is the function used to access or create a database file. If the filename used in +the parameter is an existing database, it will retrieve and access the file. Otherwise, it will +create a new database file with the provided filename. + +Syntax in C++: + +``` +database open_database(string name, string filename) +``` + +### Has Database + +`Has Database` is a boolean fuction used to check if the database with the given name has been +loaded into the program, and return either true or false accordingly. + +Syntax in C++: + +``` +bool has_database(string name) +``` + +### Database Named + +`Database Named` is a function that retrieves the database that has been opened with +`Open Database`. This is useful when you want to use the database without storing it into a +variable. + +Syntax in C++: + +``` +database database_named(string name) +``` + +### Free Database + +After you have finished using your database, you should free the resource using `Free Database`. +There are two versions of the function, one where you use the database object as the parameter, and +one where you use the name of the database for the parameter. + +Syntax in C++: + +``` +void free_database(database db_to_close) +``` + +``` +void free_database(string name_of_db_to_close) +``` + +### Free All Databases + +Another way of freeing all databases at once is using the `Free All Databases` function. + +Syntax in C++: + +``` +void free_all_databases() +``` + +### Demonstration + +``` +int main() +{ + // Open database named "test" from a file named "test_database" + open_database("test", "test_database"); + + // Check if database has been loaded + if (has_database("test")) + { + // Store database to a variable x + database x = database_named("test"); + } + + // Free the database since we are done + free_all_databases(); + + // Alternatives + // free_database("test"); + // free_database(x); +} +``` + +## Performing a Query on the Database + +### Query Result + +`Query Result` is another important data type related to database. This is used to store the result +after performing a query on a database. + +### Run Sql + +`Run Sql` performs an sql command to the database and returns the result as a `Query Result`. Either +the database object or the string name can be used to pass the database on to the function. + +Syntax in C++: + +``` +query_result run_sql(database db, string sql) +``` + +``` +query_result run_sql(string database_name, string sql) +``` + +### Query Success + +`Query Success` can be used to check if the most recent query on a `Query Result` was successful or +not. Syntax in C++: + +``` +bool query_success(query_result db_result) +``` + +### Query Column For Boolean + +`Query Column For Boolean` is used to access a column of a `Query Result` which consists of booleans +at the current row (the top row). + +Syntax in C++: + +``` +bool query_column_for_bool(query_result db_result, int col) +``` + +### Query Column For Double + +`Query Column For Double` is similar to the previous function, except it is used when the data type +is double. + +Syntax in C++: + +``` +double query_column_for_double(query_result db_result, int col) +``` + +### Query Column For Integer + +Similar to the previous two functions, this has the same usage except it is for integers. + +Syntax in C++: + +``` +int query_column_for_int(query_result db_result, int col) +``` + +### Query Column For String + +The final query column function performs similarly to the other functions, where it is used for +strings. + +Syntax in C++: + +``` +string query_column_for_string(query_result db_result, int col) +``` + +### Query Type Of Col + +`Query Type Of Col` is used to check what the data type of the column is. This is useful when you +don't know what data types are used in the database. + +Syntax in C++: + +``` +string query_type_of_col(query_result db_result, int col) +``` + +### Rows Changed + +This function is used to check how many rows has been changed on a database the last time a changing +query was performed on the database. + +Syntax in C++: + +``` +int rows_changed(database db) +``` + +### Free Query Result + +Similar to a `Database`, we should free `Query Result` that we have finished using. + +Syntax in C++: + +``` +void free_query_result(query_result query) +``` + +### Free All Query Results + +`Free All Query Results` can be used to free all `Query Results` at once. + +Syntax in C++: + +``` +void free_all_query_results() +``` + +### Demonstration + +``` +int main() +{ + // Open database named "users" with a table "Users" and the collumns "UID", "Name" + open_database("users", "users_database"); + + // Create a query result to store results + query_result result; + int uid; + string name; + + // Perform SQL to add a new user + run_sql("users", "INSERT INTO Users VALUES('001', 'John');"); + + // Now, if rows_changed(database_named("users")); is used, it should return 1. + + // Perform SQL to get the whole table + result = run_sql("users", "SELECT * FROM Users;"); + + // Get the values into variables + uid = query_column_for_integer(result, 0); + name = query_column_for_string(result, 1); + + // Free the resources since we are done + free_all_databases(); + free_all_query_results(); +} +``` + +## Iterating Through a Database + +You may have noticed that the `Query Column` functions only get the data from the first row of the +`Query Result`. This section will show you how to access the other rows, and iterating through the +whole table. + +### Get Next Row + +`Get Next Row` checks if there is a valid row and moves you to the next row of the `Query Result`. +It is a boolean function that will return either true or false depending on whether the next row +exists or not. + +Syntax in C++: + +``` +bool get_next_row(query_result db_result) +``` + +### Has Row + +Syntax in C++: + +``` +bool has_row(query_result db_result) +``` + +### Reset Query Result + +Syntax in C++: + +``` +void reset_query_result(query_result db_result) +``` + +### Demonstration + +Sample data of "test_database": + +Table | ID | | ---- | | 0 | | 1 | | 2 | + +``` +int main() +{ + // Open a database from a file "test_database" which has a table "Table" with the collumn "ID" + open_database("test", "test_database"); + + query_result result = run_sql("test", "SELECT * From Table";); + + // Check if there is a valid row since the table may be empty + if (has_row(result)) + { + do + { + int id = query_column_for_integer(result, 0); // This will return the values 0, 1, and 2 + + } while (get_next_row(result)) // Loop while there is a valid next row + } + + free_all_databases(); + free_all_query_results(); +} +```