====== Math ======

Math is a module containing numbers with automatic type promotion and various math operations.

===== Numeral =====

''Numeral'' is a type that can wrap six different number types. It also contains methods for conversion between these types. Numeral is immutable, and every operation on it creates a new instance, just like native Java number types. The six types are:

  * ''IntNumeral'', which is backed by an ''int''
  * ''LongNumeral'', which is backed by a ''long''
  * ''BigIntNumeral'', which is backed by a ''BigInteger''
  * ''FloatNumeral'', which is backed by a ''float''
  * ''DoubleNumeral'', which is backed by a ''double''
  * ''BigDecNumeral'', which is backed by a ''BigDecimal''

The numeral has various conversion methods. The methods do not allow conversions that would result in an integer overflow or an infinite floating point value, but do allow conversions from non-integers to integers. The methods are:

  * ''convert(NumeralType)'' converts a numeral to the type if allowed, and throws ''ExtendedArithmeticException'' otherwise
  * ''convertIfAllowed(NumeralType)'' converts a numeral to the type if allowed, and returns the same numeral otherwise
  * ''toInteger()'' converts a numeral to the smallest allowed integer type
  * ''toDecimal()'' converts a numeral to the smallest allowed decimal type
  * ''toSmallestType()'' converts a numeral to the smallest allowed type, but does not convert between integer and decimal types

Along these methods, the numeral also has methods for converting them to native Java number types. These methods throw ''ExtendedArithmeticException'' if the numeral’s value is out of bounds.

Numerals can be created with their constructors, but the ''Numerals'' utility contains various methods for creating numerals. Details of utility classes are explained below.

===== Utility classes =====

==== Conversion ====

''Conversion'' contains methods for converting numerals into native Java number types. The conversion methods are used internally by the conversion methods within numerals.

==== Numerals ====

''Numerals'' contains methods for creating numerals from numbers, including string representations of numbers and arbitrary ''Number'' instances.

==== Operations ====

''Operations'' contains a multitude of math operations for numerals. These operations automatically promote numeral types to allow every operation to finish. The ''MathContext'' for ''BigDecimal'' operations can be chosen with ''Operations.setContext(MathContext)'' and the default value is ''MathContext.DECIMAL128''.

List of operations: ''add'', ''subtract'', ''multiply'', ''divide'', ''inverse'', ''power'', ''exp'', ''sqrt'', ''cbrt'', (nth) ''root'', ''log'', ''log2'', ''log10'', ''logN'', ''min'', ''max'' and ''lerp''.

==== Range ====

''Range'' contains methods for checking if a number or numeral is within the allowed range of a numeral type.