diff --git a/Nerd_STF/Mathematics/Abstract/IAbsolute.cs b/Nerd_STF/Mathematics/Abstract/IAbsolute.cs index 47135bc..2c9d9b9 100644 --- a/Nerd_STF/Mathematics/Abstract/IAbsolute.cs +++ b/Nerd_STF/Mathematics/Abstract/IAbsolute.cs @@ -1,6 +1,20 @@ namespace Nerd_STF.Mathematics.Abstract; +/// +/// An that can be derived from to implement +/// absolute value functionality. This interface includes one method: +/// +/// +/// +/// +/// This type. public interface IAbsolute where T : IAbsolute { + /// + /// Calculate the positive value of . + /// I know, this isn't technically the "absolute" value but whatever. + /// + /// The value of to calculate the absolute value of. + /// The positive vlaue of . public static abstract T Absolute(T val); } diff --git a/Nerd_STF/Mathematics/Mathf.cs b/Nerd_STF/Mathematics/Mathf.cs index 3105c8e..d2c6343 100644 --- a/Nerd_STF/Mathematics/Mathf.cs +++ b/Nerd_STF/Mathematics/Mathf.cs @@ -1,16 +1,49 @@ namespace Nerd_STF.Mathematics; +/// +/// A class that contains various mathematical methods using s. +/// public static class Mathf { + /// + /// Calculate the absolute value of a . + /// + /// The to calculate the absolute value of. + /// + /// Runs in O(1) time. public static float Absolute(float val) => val < 0 ? -val : val; + /// + /// Calculate the absolute value of a . + /// + /// The to calculate the absolute value of. + /// + /// Runs in O(1) time. public static int Absolute(int val) => val < 0 ? -val : val; + /// + /// Calculates the absolute modulus value of a number. In C# by default, getting + /// the modulus of a negative number returns a negative value, while in math + /// that number is usually positive. This method ensures the number is positive. + /// + /// The value to apply the modulus to. + /// The number to modulus by. + /// The smallest positive number that can be added to to create a multiple of . + /// Runs in O(n) time. public static float AbsoluteMod(float val, float mod) { while (val >= mod) val -= mod; while (val < 0) val += mod; return val; } + /// + /// Calculates the absolute modulus value of a number. In C# by default, getting + /// the modulus of a negative number returns a negative value, while in math + /// that number is usually positive. This method ensures the number is positive. + /// + /// The value to apply the modulus to. + /// The number to modulus by. + /// The smallest positive number that can be added to to create a multiple of . + /// Runs in O(n) time. public static int AbsoluteMod(int val, int mod) { while (val >= mod) val -= mod; @@ -18,15 +51,76 @@ public static class Mathf return val; } + /// + /// Calculates the inverse cosine of the value , such that + /// cos(arccos()) = . + /// + /// Since cos(x) only returns a value between -1 and 1, the domain of + /// arccos(x) is [-1, 1], and its range is [0, π]. + /// + /// The value to calculate the inverse cosine of. + /// The angle θ representing cos(θ) = . + /// Runs in O(n) time. public static Angle ArcCos(float value) => ArcSin(-value) + Angle.Quarter; + /// + /// Calculates the inverse cotangent of the value , such that + /// cot(arccot()) = . + /// + /// Since cot(x) returns any real number value, the domain of arccot(x) + /// is (-∞, ∞), and its range is (0, π). + /// + /// The value to calculate the inverse cotangent of. + /// The angle θ representing cot(θ) = . + /// Runs in O(n) time. public static Angle ArcCot(float value) => ArcCos(value / Sqrt(1 + value * value)); + /// + /// Calculates the invese cosecant of the value , such that + /// csc(arccsc()) = . + /// + /// Since csc(x) returns any real number value such that |csc(x)| >= 1, + /// the domain of arccsc(x) is (-∞, 1] ∪ [1, ∞) and its range is [-π/2, π/2]. + /// + /// The value to calculate the inverse cosecant of. + /// The angle θ representing csc(θ) = . + /// Runs in O(n) time. public static Angle ArcCsc(float value) => ArcSin(1 / value); + /// + /// Calculates the inverse secant of the value , such that + /// sec(arcsec()) = . + /// + /// Since sec(x) returns any real number value such that |sec(x)| >= 1, + /// the domain of arcsec(x) is (-∞, 1] ∪ [1, ∞) and its range is [0, π]. + /// + /// The value to calculate the inverse secant of. + /// The angle θ representing sec(θ) = . + /// Runs in O(n) time. public static Angle ArcSec(float value) => ArcCos(1 / value); + /// + /// Calculates the inverse sine of the value , such that + /// sin(arcsin()) = . + /// + /// Since sin(x) returns a value between [-1, 1], the domain of arcsin(x) + /// is [-1, 1] and its range is [-π/2, π/2]. + /// + /// The value to calculate the inverse sine of. + /// The angle θ representing sin(θ) = . + /// Thrown when the input is out of the domain of [-1, 1]. + /// Runs in O(n) time. public static Angle ArcSin(float value) { if (value > 1 || value < -1) throw new ArgumentOutOfRangeException(nameof(value)); return (SolveNewton(x => Sin(x) - value, 0), Angle.Type.Radians); - } + } + /// + /// Calculates the inverse tangent of the value , such that + /// tan(arctan()) = . + /// + /// Since tan(x) returns any real number value, the domain of arctan(x) + /// is (-∞, ∞), and its range is (-π/2, π/2). + /// + /// The value to calculate the inverse cotangent of. + /// The angle θ representing tan(θ) = . + /// Runs in O(n) time. public static Angle ArcTan(float value) => ArcSin(value / Sqrt(1 + value * value)); public static Angle ArcTan2(float a, float b) => ArcTan(a / b); @@ -47,12 +141,26 @@ public static class Mathf for (float x = min; x <= max; x += step) vals.Add(equ(x)); return Average(vals.ToArray()); } + /// + /// Calculates the average of an array of s. + /// + /// The array to calculate the average of. + /// The average of the array. + /// Runs in O(n) time. public static float Average(params float[] vals) { float sum = 0; foreach (float f in vals) sum += f; return sum / vals.Length; } + /// + /// Calculates the average of an array of s. + /// Because the return type is also an , the average + /// will be rounded down to the nearest whole number. + /// + /// The array to calculate the average of. + /// The average of the array, rounded down to the nearest . + /// Runs in O(n) time. public static int Average(params int[] vals) { int sum = 0; @@ -63,6 +171,12 @@ public static class Mathf public static float Binomial(int n, int total, float successRate) => Combinations(total, n) * Power(successRate, n) * Power(1 - successRate, total - n); + /// + /// Calculates the cube root of a number. + /// + /// The number to calculate the cube root of. + /// The cube root of . + /// Runs in O(n) time. public static float Cbrt(float value) => SolveNewton(x => x * x * x - value, 1); public static int Ceiling(float val) @@ -200,6 +314,15 @@ public static class Mathf else return CordicHelper.LogAnyBase(@base, val, 16, 16); } + /// + /// Creates an out of a + /// of XY points. This equation has a domain of all real numbers and linearly + /// interpolates between points. + /// + /// The of XY points to include in the . + /// An equation that interpolates between each point in . + /// Thrown when no points are contained in or when two points in the dictionary cannot be joined together. + /// Generates the in O(1) time, however invoking that equation returns a result in O(n) time where n is the amount of points in . public static Equation MakeEquation(Dictionary vals) => delegate (float x) { if (vals.Count < 1) throw new UndefinedException(); @@ -335,6 +458,15 @@ public static class Mathf // nPr (n = total, r = size) public static int Permutations(int total, int size) => Factorial(total) / Factorial(total - size); + /// + /// Returns an that contains all prime factors of the number + /// . A prime factor is defined as a prime number that + /// is divisible by at least once. Any counting number can + /// be represented as a unique collection of prime factors. Duplicate factors are + /// included. + /// + /// The number to calculate the prime factors of. + /// An of prime factors. public static int[] PrimeFactors(int num) { List factors = new(); diff --git a/Nerd_STF/Mathematics/Samples/Constants.cs b/Nerd_STF/Mathematics/Samples/Constants.cs index dbb05b6..681903f 100644 --- a/Nerd_STF/Mathematics/Samples/Constants.cs +++ b/Nerd_STF/Mathematics/Samples/Constants.cs @@ -1,25 +1,101 @@ namespace Nerd_STF.Mathematics.Samples; +/// +/// A container of various mathematical constants. +/// public static class Constants { + /// + /// The ratio between a degree and a radian. This constant is intended to be used + /// as follows: + /// degrees = radians * + /// This is the reciprocal of . + /// public const float DegToRad = Pi / 180; + /// + /// Exactly one half of the constant . While this constant has many + /// uses, most of them are just a shorthand for / 2, unlike + /// . + /// + /// See also: Pi - Wikipedia public const float HalfPi = Pi / 2; + /// + /// The ratio between a circle's circumference and its diameter. This constant has + /// many uses. + /// + /// See also: Pi - Wikipedia public const float Pi = 3.14159265359f; + /// + /// The ratio between a radian and a degree. This constant is intended to be used + /// as follows: + /// radians = degrees * + /// This is the reciprocal of . + /// public const float RadToDeg = 180 / Pi; + /// + /// Exactly double the value of the constant . Unlike + /// , there are circumstances where this constant is preferrable + /// over its actual value of * 2. + /// + /// See also: Pi - Wikipedia public const float Tau = Pi * 2; + /// + /// E is also known as Euler's number or the natural number. This constant + /// has a very large number of interpretations and uses. + /// + /// See also: e (mathematical constant) - Wikipedia public const float E = 2.71828182846f; + /// + /// The limit of the summed error between the harmonic series and the natural logarithm. + /// + /// See also: Euler's constant - Wikipedia public const float EulerConstant = 0.5772156649f; + /// + /// The natural logarithm of 2. It is a trancendental number. + /// + /// + /// See also: Natural logarithm of 2 - Wikipedia
+ /// See also: Natural logarithm - Wikipedia + /// public const float Ln2 = 0.69314718056f; + /// + /// The natural logarithm of 3. It is a trancendental number. + /// + /// See also: Natural logarithm - Wikipedia public const float Ln3 = 1.09861228867f; + /// + /// The natural logarithm of 5. It is a trancendental number. + /// + /// See also: Natural logarithm - Wikipedia public const float Ln5 = 1.60943791243f; + /// + /// The natural logarithm of 10. It is a trancendental number. + /// + /// See also: Natural logarithm - Wikipedia public const float Ln10 = 2.30258509299f; + /// + /// The logarithm (base 10) of 2. + /// public const float Log2 = 0.301029995664f; + /// + /// The logarithm (base 10) of 3. + /// public const float Log3 = 0.47712125472f; + /// + /// The logarithm (base 10) of 5. + /// public const float Log5 = 0.698970004336f; + /// + /// The logarithm (base 10) of 10. + /// public const float Log10 = 1; + /// + /// The resulting smallest angle when you apply the golden ratio to a circle (in degrees). + /// + /// See also: Golden angle - Wikipedia public const float GoldenAngle = 180 * (3 - Sqrt5); public const float GoldenRatio = (1 + Sqrt5) / 2; public const float SilverRatio = Sqrt2 + 1;