SNBP Library Detailed Documentation

You like light mode? Ew!

1. Overview

The SNBP library is a comprehensive utility library designed for the Bassil language project. It provides a wide range of functions for string manipulation, Windows API interaction, file handling, and console output formatting.

Version: 0.7.4

Author: Nerd - Bear

Last Updated: 12/9/2024 (DD/MM/YYYY)

License: MIT License

2. Namespace

All functions and classes in this library are encapsulated within the SNBP namespace.

3. String Manipulation Functions

3.1 splitString

std::vector<std::string> splitString(const std::string &s, const std::string &delimiter = " ")

Description: Splits a string into a vector of substrings based on a specified delimiter.

Parameters:

s: The input string to be split.
delimiter: The string that serves as the delimiter for splitting. Default is a space.

Return Value: A vector containing the substrings resulting from splitting the input string.

Example:

std::string input = "apple,banana,cherry";
std::vector<std::string> result = SNBP::splitString(input, ",");
// result now contains {"apple", "banana", "cherry"}

3.2 ltrim, rtrim, trim

std::string& ltrim(std::string &s)
std::string& rtrim(std::string &s)
std::string& trim(std::string &s)

Description: These functions trim whitespace from strings.

ltrim: Removes leading whitespace.
rtrim: Removes trailing whitespace.
trim: Removes both leading and trailing whitespace.

Parameters:

s: The string to be trimmed (passed by reference).

Return Value: A reference to the modified string, allowing for method chaining.

Example:

std::string str = "  Hello, World!  ";
SNBP::trim(str);
// str is now "Hello, World!"

4. Windows API Interaction Functions

4.1 CreateWinAPI32MessageBox

int CreateWinAPI32MessageBox(const std::string &_title, const std::string &_message, int _type)

Description: Creates a Windows API 32-bit message box.

Parameters:

_title: The title of the message box.
_message: The content of the message box.
_type: The type of the message box, determining which buttons are displayed.

Return Value: The ID of the button clicked by the user.

Note: The _type parameter can have the following values:

1: MB_ABORTRETRYIGNORE (Abort, Retry, Ignore buttons)
2: MB_OKCANCEL (OK, Cancel buttons)
3: MB_CANCELTRYCONTINUE (Cancel, Try Again, Continue buttons)
4: MB_YESNOCANCEL (Yes, No, Cancel buttons)
5: MB_YESNO (Yes, No buttons)
6: MB_OK (OK button)

Example:

int result = SNBP::CreateWinAPI32MessageBox("Warning", "Are you sure?", 5);
if (result == IDYES) {
    // User clicked Yes
} else {
    // User clicked No
}

5. File Handling Functions

5.1 generalLog

int generalLog(const std::string &str, bool isPrintTrue = true)

Description: Logs a message to a file and optionally prints it to the console.

Parameters:

str: The message to be logged.
isPrintTrue: Flag to indicate if the message should be printed to the console. Default is true.

Return Value: Returns 0 on successful logging, 1 if there was an error opening the log file.

Note: The log file is located at "C:/coding-projects/CPP-Dev/bassil/output/logs.log".

Example:

int result = SNBP::generalLog("Application started", true);
if (result != 0) {
    std::cerr << "Failed to write to log file" << std::endl;
}

6. Console Formatting Functions

6.1 enableAnsiInConsole

int enableAnsiInConsole()

Description: Enables ANSI escape sequence processing for the console output, allowing the use of colored text and other formatting in the console.

Return Value: Returns 0 on success, 1 if there was an error enabling ANSI support.

Note: This function should be called once at the beginning of the program if ANSI support is needed.

Example:

if (SNBP::enableAnsiInConsole() == 0) {
    std::cout << "\033[31mThis text is red\033[0m" << std::endl;
} else {
    std::cerr << "Failed to enable ANSI support" << std::endl;
}

7. Hardware Information (dhi namespace)

The dhi (Detailed Hardware Information) namespace provides functions to retrieve various hardware details on Windows systems.

7.1 Structures

struct HardwareInfo {
    std::wstring category;
    std::vector<std::pair<std::wstring, std::wstring>> properties;
};

Description: This structure holds information about a specific hardware category.

category: The name of the hardware category (e.g., "System Information", "Processor Information").
properties: A vector of key-value pairs representing the properties of the hardware.

7.2 Key Functions

getSystemInfo(WMIService &wmi): Retrieves general system information.
getProcessorInfo(WMIService &wmi): Retrieves processor information.
getMemoryInfo(WMIService &wmi): Retrieves memory information.
getDiskInfo(WMIService &wmi): Retrieves disk information.
getGraphicsInfo(WMIService &wmi): Retrieves graphics card information.

Note: These functions require a WMIService object, which handles the Windows Management Instrumentation (WMI) queries.

8. Initialization

8.1 SNPBinit

int SNPBinit()

Description: Initializes the SNBP library, setting up version information and other necessary configurations.

Return Value: Returns 0 on successful initialization.

Note: This function should be called at the beginning of your program before using any other SNBP functions.

Example:

        if (SNBP::SNPBinit() == 0) {
            std::cout << "SNBP library initialized successfully" << std::endl;
        } else {
            std::cerr << "Failed to initialize SNBP library" << std::endl;
        }

9. Error Handling

The SNBP library uses a combination of return values and exceptions for error handling:

Many functions return integer values (0 for success, non-zero for failure) or boolean values (true for success, false for failure).
Some functions throw exceptions for critical errors or invalid inputs.

9.1 Common Exceptions

std::runtime_error: Thrown for general runtime errors, such as file I/O failures or Windows API errors.
std::invalid_argument: Thrown when a function receives invalid input parameters.
std::out_of_range: Thrown when attempting to access elements outside the valid range, e.g., in file reading operations.

9.2 Best Practices for Error Handling

Always check return values of functions that return error codes.
Use try-catch blocks when calling functions that may throw exceptions.
Log errors and exceptions for debugging purposes.

Example:

try {
    std::string content = SNBP::readFileToString("config.txt");
    std::cout << "File content: " << content << std::endl;
} catch (const std::runtime_error& e) {
    std::cerr << "Error reading file: " << e.what() << std::endl;
    SNBP::generalLog("File read error: " + std::string(e.what()));
}

10. Thread Safety

The SNBP library is not inherently thread-safe. When using SNBP functions in a multi-threaded environment, consider the following:

File I/O operations (e.g., generalLog, readFileToString) should be synchronized when accessed from multiple threads.
Windows API functions may have their own thread safety considerations. Refer to the Windows API documentation for specific function thread safety.
The hardware information retrieval functions in the dhi namespace use COM, which requires proper initialization in a multi-threaded environment.

Example of thread-safe logging:

#include <mutex>

std::mutex logMutex;

void threadSafeLog(const std::string& message) {
    std::lock_guard<std::mutex> lock(logMutex);
    SNBP::generalLog(message);
}

11. Performance Considerations

String Operations: Functions like splitString and trim may create copies of strings. For large strings or frequent operations, consider using string views or references where possible.
File I/O: File operations can be slow. For frequent small writes, consider buffering data and writing in larger chunks.
Windows API Calls: Some Windows API functions, especially those in the dhi namespace, can be relatively slow. Cache results when appropriate rather than calling these functions repeatedly.
ANSI Escape Sequences: Enabling ANSI escape sequences (enableAnsiInConsole) may have a small performance impact on console output. Only enable if needed.

Example of optimized string splitting:

void processSplitString(const std::string& input, const std::string& delimiter) {
    size_t start = 0;
    size_t end = input.find(delimiter);
    while (end != std::string::npos) {
        processSubstring(input.substr(start, end - start));
        start = end + delimiter.length();
        end = input.find(delimiter, start);
    }
    processSubstring(input.substr(start));
}

12. Best Practices

Initialization: Always call SNBP::SNPBinit() at the start of your program.
Error Handling: Consistently check return values and use try-catch blocks for functions that may throw exceptions.
Resource Management: Properly close files and release Windows resources (e.g., handles) when no longer needed.
String Handling: Use const std::string& for input parameters to avoid unnecessary copying.
Console Output: When using ANSI escape sequences for formatting, ensure they are supported by checking isAnsiEnabledInConsole().
Windows API: Be aware of the Windows version requirements for different API calls used in the library.

Example of good practice:

int main() {
    if (SNBP::SNPBinit() != 0) {
        std::cerr << "Failed to initialize SNBP library" << std::endl;
        return 1;
    }

    if (SNBP::enableAnsiInConsole() == 0 && SNBP::isAnsiEnabledInConsole()) {
        std::cout << SNBP::colorText("ANSI colors enabled", "#00FF00") << std::endl;
    } else {
        std::cout << "ANSI colors not supported" << std::endl;
    }

    try {
        // Use SNBP functions here
    } catch (const std::exception& e) {
        SNBP::generalLog("Error occurred: " + std::string(e.what()));
        return 1;
    }

    return 0;
}

13. Compatibility

The SNBP library is primarily designed for Windows environments. Key compatibility points:

Operating System: Windows-specific. Many functions will not work on other operating systems.
Windows Versions: Tested on Windows 10 and later. Some functions may have different behavior or may not be available on earlier Windows versions.
Compiler: Developed and tested with MSVC (Microsoft Visual C++). May require adjustments for other compilers.
Character Encoding: Uses UTF-8 for string handling. Ensure your project is configured for UTF-8 support.
C++ Standard: Requires C++11 or later.

14. Contributing and Support

The SNBP library is an open-source project. Contributions and feedback are welcome.

Reporting Issues: Use the GitHub issue tracker to report bugs or suggest enhancements.
Contributing Code: Submit pull requests for bug fixes or new features. Ensure code follows the existing style and includes appropriate documentation and tests.
Documentation: Improvements to documentation, including this detailed guide, are highly appreciated.
Support: For questions or support, use the GitHub discussions feature or contact the maintainers directly.

For more information, visit the SNBP GitHub repository.