diff --git a/ElunaQueryMethods.h b/ElunaQueryMethods.h index ef5d894..144ca1e 100644 --- a/ElunaQueryMethods.h +++ b/ElunaQueryMethods.h @@ -12,19 +12,31 @@ #else #define RESULT (*result) #endif + +/*** + * The result of a database query. + * + * E.g. the return value of [Global:WorldDBQuery]. + */ namespace LuaQuery { - void CheckFields(Eluna* /*E*/, lua_State* L, ElunaQuery* result) + static void CheckFields(lua_State* L, ElunaQuery* result) { if (Eluna::CHECKVAL(L, 2) >= RESULT->GetFieldCount()) luaL_argerror(L, 2, "invalid field index"); } /* BOOLEAN */ - int IsNull(Eluna* E, lua_State* L, ElunaQuery* result) + /** + * Returns `true` if the specified column of the current row is `NULL`, otherwise `false`. + * + * @param uint32 column + * @return bool isNull + */ + int IsNull(Eluna* /*E*/, lua_State* L, ElunaQuery* result) { uint32 col = Eluna::CHECKVAL(L, 2); - CheckFields(E, L, result); + CheckFields(L, result); #ifndef TRINITY Eluna::Push(L, RESULT->Fetch()[col].IsNULL()); @@ -35,126 +47,195 @@ namespace LuaQuery } /* GETTERS */ + /** + * Returns the number of columns in the result set. + * + * @return uint32 columnCount + */ int GetColumnCount(Eluna* /*E*/, lua_State* L, ElunaQuery* result) { Eluna::Push(L, RESULT->GetFieldCount()); return 1; } + /** + * Returns the number of rows in the result set. + * + * @return uint32 rowCount + */ int GetRowCount(Eluna* /*E*/, lua_State* L, ElunaQuery* result) { if (RESULT->GetRowCount() > (uint32)-1) Eluna::Push(L, (uint32)-1); else - Eluna::Push(L, RESULT->GetRowCount()); + Eluna::Push(L, (uint32)(RESULT->GetRowCount())); return 1; } - int GetBool(Eluna* E, lua_State* L, ElunaQuery* result) + /** + * Returns the data in the specified column of the current row, casted to a boolean. + * + * @param uint32 column + * @return bool data + */ + int GetBool(Eluna* /*E*/, lua_State* L, ElunaQuery* result) { uint32 col = Eluna::CHECKVAL(L, 2); - CheckFields(E, L, result); + CheckFields(L, result); Eluna::Push(L, RESULT->Fetch()[col].GetBool()); return 1; } - int GetUInt8(Eluna* E, lua_State* L, ElunaQuery* result) + /** + * Returns the data in the specified column of the current row, casted to an unsigned 8-bit integer. + * + * @param uint32 column + * @return uint8 data + */ + int GetUInt8(Eluna* /*E*/, lua_State* L, ElunaQuery* result) { uint32 col = Eluna::CHECKVAL(L, 2); - CheckFields(E, L, result); + CheckFields(L, result); Eluna::Push(L, RESULT->Fetch()[col].GetUInt8()); return 1; } - int GetUInt16(Eluna* E, lua_State* L, ElunaQuery* result) + /** + * Returns the data in the specified column of the current row, casted to an unsigned 16-bit integer. + * + * @param uint32 column + * @return uint16 data + */ + int GetUInt16(Eluna* /*E*/, lua_State* L, ElunaQuery* result) { uint32 col = Eluna::CHECKVAL(L, 2); - CheckFields(E, L, result); + CheckFields(L, result); Eluna::Push(L, RESULT->Fetch()[col].GetUInt16()); return 1; } - int GetUInt32(Eluna* E, lua_State* L, ElunaQuery* result) + /** + * Returns the data in the specified column of the current row, casted to an unsigned 32-bit integer. + * + * @param uint32 column + * @return uint32 data + */ + int GetUInt32(Eluna* /*E*/, lua_State* L, ElunaQuery* result) { uint32 col = Eluna::CHECKVAL(L, 2); - CheckFields(E, L, result); + CheckFields(L, result); Eluna::Push(L, RESULT->Fetch()[col].GetUInt32()); return 1; } - int GetUInt64(Eluna* E, lua_State* L, ElunaQuery* result) + /** + * Returns the data in the specified column of the current row, casted to an unsigned 64-bit integer. + * + * @param uint32 column + * @return uint64 data + */ + int GetUInt64(Eluna* /*E*/, lua_State* L, ElunaQuery* result) { uint32 col = Eluna::CHECKVAL(L, 2); - CheckFields(E, L, result); + CheckFields(L, result); Eluna::Push(L, RESULT->Fetch()[col].GetUInt64()); return 1; } - int GetInt8(Eluna* E, lua_State* L, ElunaQuery* result) + /** + * Returns the data in the specified column of the current row, casted to a signed 8-bit integer. + * + * @param uint32 column + * @return int8 data + */ + int GetInt8(Eluna* /*E*/, lua_State* L, ElunaQuery* result) { uint32 col = Eluna::CHECKVAL(L, 2); - CheckFields(E, L, result); + CheckFields(L, result); Eluna::Push(L, RESULT->Fetch()[col].GetInt8()); return 1; } - int GetInt16(Eluna* E, lua_State* L, ElunaQuery* result) + /** + * Returns the data in the specified column of the current row, casted to a signed 16-bit integer. + * + * @param uint32 column + * @return int16 data + */ + int GetInt16(Eluna* /*E*/, lua_State* L, ElunaQuery* result) { uint32 col = Eluna::CHECKVAL(L, 2); - CheckFields(E, L, result); + CheckFields(L, result); Eluna::Push(L, RESULT->Fetch()[col].GetInt16()); return 1; } - int GetInt32(Eluna* E, lua_State* L, ElunaQuery* result) + /** + * Returns the data in the specified column of the current row, casted to a signed 32-bit integer. + * + * @param uint32 column + * @return int32 data + */ + int GetInt32(Eluna* /*E*/, lua_State* L, ElunaQuery* result) { uint32 col = Eluna::CHECKVAL(L, 2); - CheckFields(E, L, result); + CheckFields(L, result); Eluna::Push(L, RESULT->Fetch()[col].GetInt32()); return 1; } - int GetInt64(Eluna* E, lua_State* L, ElunaQuery* result) + /** + * Returns the data in the specified column of the current row, casted to a signed 64-bit integer. + * + * @param uint32 column + * @return int64 data + */ + int GetInt64(Eluna* /*E*/, lua_State* L, ElunaQuery* result) { uint32 col = Eluna::CHECKVAL(L, 2); - CheckFields(E, L, result); + CheckFields(L, result); Eluna::Push(L, RESULT->Fetch()[col].GetInt64()); return 1; } - int GetFloat(Eluna* E, lua_State* L, ElunaQuery* result) + /** + * Returns the data in the specified column of the current row, casted to a 32-bit floating point value. + * + * @param uint32 column + * @return float data + */ + int GetFloat(Eluna* /*E*/, lua_State* L, ElunaQuery* result) { uint32 col = Eluna::CHECKVAL(L, 2); - CheckFields(E, L, result); + CheckFields(L, result); Eluna::Push(L, RESULT->Fetch()[col].GetFloat()); return 1; } - int GetDouble(Eluna* E, lua_State* L, ElunaQuery* result) + /** + * Returns the data in the specified column of the current row, casted to a 64-bit floating point value. + * + * @param uint32 column + * @return double data + */ + int GetDouble(Eluna* /*E*/, lua_State* L, ElunaQuery* result) { uint32 col = Eluna::CHECKVAL(L, 2); - CheckFields(E, L, result); + CheckFields(L, result); Eluna::Push(L, RESULT->Fetch()[col].GetDouble()); return 1; } - int GetString(Eluna* E, lua_State* L, ElunaQuery* result) + /** + * Returns the data in the specified column of the current row, casted to a string. + * + * @param uint32 column + * @return string data + */ + int GetString(Eluna* /*E*/, lua_State* L, ElunaQuery* result) { uint32 col = Eluna::CHECKVAL(L, 2); - CheckFields(E, L, result); - -#ifndef TRINITY - Eluna::Push(L, RESULT->Fetch()[col].GetCppString()); -#else - Eluna::Push(L, RESULT->Fetch()[col].GetString()); -#endif - return 1; - } - - int GetCString(Eluna* E, lua_State* L, ElunaQuery* result) - { - uint32 col = Eluna::CHECKVAL(L, 2); - CheckFields(E, L, result); + CheckFields(L, result); #ifndef TRINITY Eluna::Push(L, RESULT->Fetch()[col].GetString()); @@ -167,8 +248,11 @@ namespace LuaQuery /* OTHER */ /** - * Advances the ElunaQuery to the next row in the result returned. - * Returns false if there was no new row, otherwise true. + * Advances the [ElunaQuery] to the next row in the result set. + * + * *Do not* call this immediately after a query, or you'll skip the first row. + * + * Returns `false` if there was no new row, otherwise `true`. * * @return bool hadNextRow */ @@ -180,9 +264,18 @@ namespace LuaQuery /** * Returns a table from the current row where keys are field names and values are the row's values. + * * All numerical values will be numbers and everything else is returned as a string. - * For example `SELECT entry, name FROM creature_template` would result in a table of `{ entry = 123, name = "some creature name" }` - * To move to next row see [ElunaQuery:NextRow] + * + * **For example,** the query: + * + * SELECT entry, name FROM creature_template + * + * would result in a table like: + * + * { entry = 123, name = "some creature name" } + * + * To move to next row use [ElunaQuery:NextRow]. * * @return table rowData : table filled with row columns and data where `T[column] = data` */ diff --git a/LuaFunctions.cpp b/LuaFunctions.cpp index f65523a..dc02d7d 100644 --- a/LuaFunctions.cpp +++ b/LuaFunctions.cpp @@ -1123,7 +1123,6 @@ ElunaRegister QueryMethods[] = { "GetFloat", &LuaQuery::GetFloat }, // :GetFloat(column) - returns the value of a float column { "GetDouble", &LuaQuery::GetDouble }, // :GetDouble(column) - returns the value of a double column { "GetString", &LuaQuery::GetString }, // :GetString(column) - returns the value of a string column, always returns a string - { "GetCString", &LuaQuery::GetCString }, // :GetCString(column) - returns the value of a string column, can return nil { "IsNull", &LuaQuery::IsNull }, // :IsNull(column) - returns true if the column is null { NULL, NULL },