From 17bfcac8ea5f4bfff9206b0b4bb2fb1fa914a8b4 Mon Sep 17 00:00:00 2001
From: MagmaBurnsV <111158858+MagmaBurnsV@users.noreply.github.com>
Date: Sat, 7 Sep 2024 15:08:51 -0400
Subject: [PATCH] Add `math.map` to the standard library

---
 docs/function-math-map.md | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)
 create mode 100644 docs/function-math-map.md

diff --git a/docs/function-math-map.md b/docs/function-math-map.md
new file mode 100644
index 0000000..548d1af
--- /dev/null
+++ b/docs/function-math-map.md
@@ -0,0 +1,36 @@
+
+# math.map
+
+## Summary
+
+Add a `map` function to the `math` library, which maps a number from one range to another.
+
+## Motivation
+
+Numerical mapping is a very common operation within game development. With only a brief search of the CoreScript source on the Roblox Client Tracker, there are about [three](https://github.com/MaximumADHD/Roblox-Client-Tracker/blob/9add9114d12e24cf08fa5680dbc95ace2af5c981/scripts/CoreScripts/Modules/PlayerList/Components/PresentationMobile/PlayerListApp.lua#L51) [different](https://github.com/MaximumADHD/Roblox-Client-Tracker/blob/9add9114d12e24cf08fa5680dbc95ace2af5c981/scripts/PlayerScripts/StarterPlayerScriptsCommon/RbxCharacterSounds.lua#L55) [implementations](https://github.com/MaximumADHD/Roblox-Client-Tracker/blob/9add9114d12e24cf08fa5680dbc95ace2af5c981/scripts/PlayerScripts/StarterPlayerScripts/PlayerModule.module/CameraModule/CameraUtils.lua#L53) of this function, each having about five to ten uses per context.
+
+A native function would help boost ergonomics and provide potential performance benefits in these cases.
+
+## Design
+
+A new function, `math.map`, will be added and will act equivalently to the following user-defined function.
+
+```luau
+function math.map(x: number, inmin: number, inmax: number, outmin: number, outmax: number): number
+	return outmin + (x - inmin) * (outmax - outmin) / (inmax - inmin)
+end
+```
+
+Just like common Luau implementations, `x` is allowed to be outside the input range. Since clamped mapping is not as widely used and can be easily replicated using `math.clamp`, it would not be supported.
+
+## Drawbacks
+
+This would add a new function to the native library, taking yet another fastcall slot.
+
+The function may also not provide enough performance improvements to warrant its addition, so implementations of this should be benchmarked.
+
+## Alternatives
+
+Not doing anything and letting people continue writing their own mapping functions. This would keep the same problems as before.
+
+If the use of clamped mapping turns out to be more widespread, then adding an optional sixth argument to enable clamping could be considered. Not doing this may lead to the same problem of people writing their own implementations as before.