----------------------------------------------------------------------
This is the API documentation for the gdtest_docstring_tables library.
----------------------------------------------------------------------


## Functions

Public functions


compare_methods(data: list) -> dict

Compare sorting methods on the given data.

Runs multiple sorting algorithms on the input data and
returns a dictionary with timing and memory metrics
for each method.

Parameters
----------
data
    A list of comparable elements to sort.

Returns
-------
dict
    A dictionary mapping method names to their performance
    metrics.

Notes
-----
The following table summarizes the complexity characteristics
of the sorting methods compared:

========  =========  ===========
Method    Speed      Memory
========  =========  ===========
Quick     O(n log n) O(log n)
Merge     O(n log n) O(n)
Bubble    O(n^2)     O(1)
========  =========  ===========

The speed column shows average-case time complexity.
Memory shows auxiliary space complexity, excluding
the input array.

For small datasets (n < 50), the differences between
these methods are negligible due to constant factors.

Examples
--------
>>> result = compare_methods([5, 3, 1])
>>> sorted(result.keys())
['bubble', 'merge', 'quick']

format_report(stats: dict) -> str

Format a statistics dictionary into a human-readable report.

Takes a dictionary of metric names to values and produces
a formatted string table.

Parameters
----------
stats
    A dictionary mapping metric names (str) to their
    values (numeric).

Returns
-------
str
    A formatted report string.

Notes
-----
The report is formatted as a simple two-column table:

==========  =====
Metric      Value
==========  =====
count       100
mean        42.5
std         12.3
==========  =====

Numeric values are formatted to one decimal place if they
are floats, or as integers if they have no fractional part.

Examples
--------
>>> print(format_report({"count": 10, "mean": 5.5}))
count: 10
mean: 5.5