Implement ScientificNumber

[JordanRL]

Implementation Checklist

This checklist outlines the necessary steps to fully integrate the new floating-point value type into the Fermat library.

Core Module

• Create a new abstract class for the new type, extending Samsara\Fermat\Core\Types\Base\Number.
• Create Immutable and Mutable implementations of the new abstract class.
• Integrate the new type into the Numbers factory (Samsara\Fermat\Core\Numbers). This will involve:
  • Adding new constants for the Immutable and Mutable versions of the new type.
  • Updating the make() and makeOrDont() methods to handle the new type.
• Implement all abstract methods from the Samsara\Fermat\Core\Types\Base\Number class in the new abstract class.
• Create a new set of arithmetic traits for the new type, or adapt the existing ones. These traits should handle:
  • Addition, subtraction, multiplication, and division.
  • Trigonometric, inverse trigonometric, and hyperbolic trigonometric functions.
  • Logarithmic and exponential functions.
  • Other relevant mathematical operations.
• Update the ArithmeticProvider (Samsara\Fermat\Core\Provider\ArithmeticProvider) to handle the new type.
• Update the RoundingProvider (Samsara\Fermat\Core\Provider\RoundingProvider) to handle the new type.
• Update the ComparisonTrait (Samsara\Fermat\Core\Types\Traits\ComparisonTrait) to handle the new type.
• Update other relevant providers as needed (e.g., BaseConversionProvider, ConstantProvider, RandomProvider, SequenceProvider, SeriesProvider).

Other Modules

• Complex Module:
  • Update the ComplexNumber class (Samsara\Fermat\Complex\Types\ComplexNumber) to accept the new type for its real and imaginary parts.
• LinearAlgebra Module:
  • Ensure the Matrix and Vector classes can store and operate on the new type.
• Coordinates Module:
  • Investigate if the new type should be supported by the Coordinate classes.
• Expressions Module:
  • Ensure the Expression class can be evaluated with variables of the new type.
• Stats Module:
  • Update the StatsProvider and distribution classes to support the new type.

Documentation and Tests

• Add comprehensive documentation for the new type, including its API, usage examples, and any limitations.
• Write a full suite of unit tests for the new type, covering all its functionality and edge cases.

Feasibility of Extending Tuple

The Tuple class, in its current implementation, is not suitable for direct extension for the new value type. The Tuple class is designed to hold a fixed-size collection of ImmutableDecimal objects, and its constructor and methods are tightly coupled to this type.

To use a Tuple-like structure for the new value type, the following changes would be necessary:

1. Generalize the Tuple class: The Tuple class would need to be modified to accept any Number type, not just ImmutableDecimal. This would involve changing the type hints in the constructor and methods, and updating the Numbers::makeOrDont() call to handle different types.
2. Create a new base class: A new base class could be created for Tuple-like structures, which could then be extended by the existing Tuple class and the new value type.

Given the complexity of these changes and the fact that the new value type represents a single number (composed of a mantissa and an exponent) rather than a collection of numbers, it is recommended to create a new class for the new value type rather than extending Tuple. The new class can still use a Tuple internally to store its components if desired, but it should not extend the Tuple class directly.

Proposed Names

Here are some proposed names for the new value type, designed to be descriptive, avoid confusion with native PHP types, and remain consistent with the library's naming conventions:

• ScientificNumber or SciNumber: This name accurately reflects the scientific notation-like structure of the number (mantissa and exponent) and its common use cases.
• FloatingPoint or FloatingPointNumber: While the request was to avoid "float", using the full "FloatingPoint" name is more descriptive and less likely to be confused with the native float type.
• ExponentialNumber or ExpNumber: This name highlights the exponent part of the number.
• MantissaExponent or MantExp: This name is very descriptive of the internal structure of the number.

Of these, ScientificNumber is the most recommended, as it is both descriptive and professional, and it aligns well with the library's existing naming conventions. The abbreviation SciNumber could be used for brevity in the class names (e.g., ImmutableSciNumber, MutableSciNumber).