Add summary statistics helpers and simulation examples

[HubertRonald]

Summary

This PR adds a new LuaSF improvement phase focused on summary statistics helpers and simulation-oriented examples.

The goal is to make LuaSF more useful for teaching, scripting, lightweight data analysis, simulations, and game/modding scenarios while preserving the existing public API and compatibility entry points.

What changed

Added summary statistics helpers

Added the following modern API functions:

• mode(array)
• range(array)
• iqr(array)
• percentile(array, p)
• summary(array)

The new summary(array) helper returns a compact table with common descriptive statistics:

{
  count = 5,
  min = 1,
  max = 5,
  mean = 3,
  median = 3,
  variance = 2.5,
  stddev = 1.5811
}

Added simulation-oriented examples

Added new examples under examples/:

• examples/weighted_loot_drop.lua
• examples/monte_carlo_pi.lua
• examples/poisson_arrivals.lua
• examples/binomial_coin_flips.lua
• examples/bootstrap_mean.lua

These examples are intended to make LuaSF easier to understand and more useful for practical simulation, teaching, and scripting scenarios.

Added tests

Updated spec/test_stats.lua with tests for the new summary statistics helpers.

The new tests cover:

• mode(array)
• range(array)
• iqr(array)
• percentile(array, p)
• summary(array)

Documentation

Updated documentation to include the new helpers and examples:

• Updated README.md
• Updated docs/api.md
• Updated CHANGELOG.md

LuaRocks preparation

Added a new rockspec draft for the next release:

• luasf-0.4.0-1.rockspec

This prepares the project for:

v0.4.0 - Summary Statistics and Simulation Examples

Compatibility notes

This PR does not remove or rename existing public functions.

The existing legacy API remains available, including:

stats.sumF(array)
stats.avF(array)
stats.stvF(array)
stats.frecuencyF(array)
stats.nomalVA(mu, sig)
stats.normalVA(mu, sig)
stats.normal_inv_D(p, mu, sig)
stats.bernoulliVA(p)
stats.unifVA(min, max)
stats.expoVA(beta)
stats.weibullVA(alpha, beta)
stats.erlangVA(n, lambda)
stats.trianVA(a, b, c)
stats.binomialVA(n, p)
stats.geometricVA(p)
stats.poissonVA(lambda)
stats.chiSquareVA(n)
stats.gamVA(alpha, lambda)
stats.lognoVA(m, s)
stats.lognoRandVA(m, s)

The new functions are added as modern API helpers only.

Testing

Tested locally with:

lua spec/test_stats.lua
lua spec/test_distributions.lua
lua spec/test_sampling.lua

Examples can be run with:

lua examples/weighted_loot_drop.lua
lua examples/monte_carlo_pi.lua
lua examples/poisson_arrivals.lua
lua examples/binomial_coin_flips.lua
lua examples/bootstrap_mean.lua

Release target

After this PR is merged into master, the next release target is:

LuaSF v0.4.0 - Summary Statistics and Simulation Examples

Recommended tag after merge:

git checkout master
git pull origin master

git tag -a v0.4.0 -m "LuaSF v0.4.0 - Summary Statistics and Simulation Examples"
git push origin v0.4.0