ktsu.io.SignificantNumber
1.2.1
Prefix Reserved
dotnet add package ktsu.io.SignificantNumber --version 1.2.1
NuGet\Install-Package ktsu.io.SignificantNumber -Version 1.2.1
<PackageReference Include="ktsu.io.SignificantNumber" Version="1.2.1" />
paket add ktsu.io.SignificantNumber --version 1.2.1
#r "nuget: ktsu.io.SignificantNumber, 1.2.1"
// Install ktsu.io.SignificantNumber as a Cake Addin #addin nuget:?package=ktsu.io.SignificantNumber&version=1.2.1 // Install ktsu.io.SignificantNumber as a Cake Tool #tool nuget:?package=ktsu.io.SignificantNumber&version=1.2.1
ktsu.io.SignificantNumber
The SignificantNumber
class represents a number with a significand and an exponent, enabling high-precision arithmetic operations that comply with calculation rules for significant figures. It provides a robust set of functionalities for mathematical computations and formatting.
Features
- High-precision arithmetic operations (addition, subtraction, multiplication, division)
- Support for significant figures and exponents
- Integration with .NET numerical interfaces
- Comprehensive error handling and validation
Table of Contents
Installation
To install the SignificantNumber
library, you can use the .NET CLI:
dotnet add package ktsu.io.SignificantNumber
Or, add the package reference directly in your project file:
<PackageReference Include="ktsu.io.SignificantNumber" Version="x.x.x" />
Usage
Creating a SignificantNumber
You can create a SignificantNumber
from various numeric types using the ToSignificantNumber
extension method:
Supported Numeric Types
The SignificantNumber
class supports a wide range of numeric types through the ToSignificantNumber
extension method, leveraging the INumber
interface for conversions. The following types are supported:
Integer Types:
int
long
short
sbyte
uint
ulong
ushort
byte
BigInteger
Floating-Point Types:
double
float
Half
decimal
Examples
You can convert various numeric types to SignificantNumber
using the ToSignificantNumber
extension method:
using ktsu.io.SignificantNumber;
// Integer types
int intValue = 12345;
SignificantNumber significantNumberFromInt = intValue.ToSignificantNumber();
BigInteger bigIntValue = new BigInteger(9876543210);
SignificantNumber significantNumberFromBigInt = bigIntValue.ToSignificantNumber();
// Floating-point types
double doubleValue = 123.45;
SignificantNumber significantNumberFromDouble = doubleValue.ToSignificantNumber();
Half halfValue = (Half)123.45;
SignificantNumber significantNumberFromHalf = halfValue.ToSignificantNumber();
float floatValue = 123.45f;
SignificantNumber significantNumberFromFloat = floatValue.ToSignificantNumber();
decimal decimalValue = 123.45m;
SignificantNumber significantNumberFromDecimal = decimalValue.ToSignificantNumber();
Arithmetic Operations
You can perform various arithmetic operations on SignificantNumber
instances:
var result1 = number1 + number2;
var result2 = number1 - number2;
var result3 = number1 * number2;
var result4 = number1 / number2;
// Square and cube operations
var squared = number1.Squared();
var cubed = number1.Cubed();
// Power operation
var powerResult = number1.Pow(3); // number1 raised to the power of 3
Comparison Operations
You can compare SignificantNumber
instances using comparison operators:
bool isEqual = number1 == number2;
bool isGreater = number1 > number2;
bool isLessOrEqual = number1 <= number2;
Formatting and Parsing
You can format a SignificantNumber
as a string:
string formatted = number1.ToString("G", CultureInfo.InvariantCulture);
Console.WriteLine(formatted); // Outputs the formatted number
Parsing is not supported and will throw NotSupportedException
:
try
{
var parsedNumber = SignificantNumber.Parse("123.45", CultureInfo.InvariantCulture);
}
catch (NotSupportedException ex)
{
Console.WriteLine(ex.Message);
}
Instead, you should parse the number as another numeric type and convert it to a SignificantNumber
:
double parsedDouble = double.Parse("123.45", CultureInfo.InvariantCulture);
SignificantNumber significantNumberFromDouble = parsedDouble.ToSignificantNumber();
Extension Methods
ToSignificantNumber
Converts various numeric types to a SignificantNumber
.
Usage:
public static SignificantNumber ToSignificantNumber<TInput>(this INumber<TInput> input)
where TInput : INumber<TInput>
Parameters:
input
: The input number to convert.
Returns:
SignificantNumber
: The convertedSignificantNumber
.
Example:
double floatingPointValue = 123.45;
SignificantNumber significantNumberFromFloat = floatingPointValue.ToSignificantNumber();
int integerValue = 12345;
SignificantNumber significantNumberFromInt = integerValue.ToSignificantNumber();
SignificantNumber result = significantNumberFromFloat + significantNumberFromInt;
// result = 12468.45
Conversion
To<TOutput>
Converts a SignificantNumber
to the specified numeric type.
Usage:
public TOutput To<TOutput>()
where TOutput : INumber<TOutput>
Parameters:
- None
Returns:
TOutput
: The converted value of theSignificantNumber
.
Example:
SignificantNumber significantNumber = new SignificantNumber(3, 12345); // 12345e3
double result = significantNumber.To<double>();
Console.WriteLine(result); // Outputs 12345000
Precision
The SignificantNumber
class is designed to handle high-precision arithmetic operations with significant figures and exponents.
Here's how it ensures precision:
Significand and Exponent
A SignificantNumber
consists of two main components:
- Significand: This is the significant part of the number, stored as a
BigInteger
to accommodate a wide range of values with high precision. - Exponent: This is the exponent part of the number, which scales the significand by a power of ten.
Precision Handling
- Maximum Significant Digits: When converting from a floating-point number to a
SignificantNumber
maximum number of significant digits is limited to 7 forfloat
values, and 16 fordouble
values. - Trailing Zero Removal: The class automatically sanitizes the significand by removing trailing zeros, ensuring that the number is stored in its most compact and precise form.
- Rounding: You can round a
SignificantNumber
to a specified number of decimal digits, ensuring that you can control the precision of your calculations.
Example of Precision
Consider the number 123.456000
:
- When stored as a
SignificantNumber
, it will be represented as123456e-3
after removing the trailing zeros and adjusting the exponent accordingly. - This ensures that the number is represented with the exact precision required for your calculations, without unnecessary trailing zeros.
By using the SignificantNumber
class, you can perform high-precision arithmetic operations and maintain control over the significant figures and exponent, ensuring accurate and efficient mathematical computations.
API Reference
Properties
static SignificantNumber NegativeOne
- Gets the value -1 for the type.static SignificantNumber One
- Gets the value 1 for the type.static SignificantNumber Zero
- Gets the value 0 for the type.static int Radix
- Gets the radix, or base, for the type.static SignificantNumber AdditiveIdentity
- Gets the additive identity of the current type.static SignificantNumber MultiplicativeIdentity
- Gets the multiplicative identity of the current type.
Methods
bool Equals(SignificantNumber other)
- Determines whether the specified object is equal to the current object.int CompareTo(object? obj)
- Compares the current instance with another object.int CompareTo(SignificantNumber other)
- Compares the current instance with another significant number.int CompareTo<TInput>(TInput other) where TInput : INumber<TInput>
- Compares the current instance with another number.SignificantNumber Abs()
- Returns the absolute value of the current instance.SignificantNumber Round(int decimalDigits)
- Rounds the current instance to the specified number of decimal digits.SignificantNumber Clamp<TNumber>(TNumber min, TNumber max) where TNumber : INumber<TNumber>
- Clamps the specified value between the minimum and maximum values.string ToString(string? format, IFormatProvider? formatProvider)
- Converts the current instance to its equivalent string representation using the specified format and format provider.bool TryFormat(Span<char> destination, out int charsWritten, ReadOnlySpan<char> format, IFormatProvider? provider)
- Attempts to format the current instance into the provided span.TOutput To<TOutput>() where TOutput : INumber<TOutput>
- Converts the current significant number to the specified numeric type.
Static Methods
static SignificantNumber Abs(SignificantNumber value)
- Returns the absolute value of aSignificantNumber
.static bool IsCanonical(SignificantNumber value)
- Determines whether the specified value is canonical.static bool IsComplexNumber(SignificantNumber value)
- Determines whether the specified value is a complex number.static bool IsEvenInteger(SignificantNumber value)
- Determines whether the specified value is an even integer.static bool IsFinite(SignificantNumber value)
- Determines whether the specified value is finite.static bool IsImaginaryNumber(SignificantNumber value)
- Determines whether the specified value is an imaginary number.static bool IsInfinity(SignificantNumber value)
- Determines whether the specified value is infinite.static bool IsInteger(SignificantNumber value)
- Determines whether the specified value is an integer.static bool IsNaN(SignificantNumber value)
- Determines whether the specified value is NaN.static bool IsNegative(SignificantNumber value)
- Determines whether the specified value is negative.static bool IsNegativeInfinity(SignificantNumber value)
- Determines whether the specified value is negative infinity.static bool IsNormal(SignificantNumber value)
- Determines whether the specified value is normal.static bool IsOddInteger(SignificantNumber value)
- Determines whether the specified value is an odd integer.static bool IsPositive(SignificantNumber value)
- Determines whether the specified value is positive.static bool IsPositiveInfinity(SignificantNumber value)
- Determines whether the specified value is positive infinity.static bool IsRealNumber(SignificantNumber value)
- Determines whether the specified value is a real number.static bool IsSubnormal(SignificantNumber value)
- Determines whether the specified value is subnormal.static bool IsZero(SignificantNumber value)
- Determines whether the specified value is zero.static SignificantNumber MaxMagnitude(SignificantNumber x, SignificantNumber y)
- Returns the larger of the magnitudes of two significant numbers.static SignificantNumber MaxMagnitudeNumber(SignificantNumber x, SignificantNumber y)
- Returns the larger of the magnitudes of two significant numbers.static SignificantNumber MinMagnitude(SignificantNumber x, SignificantNumber y)
- Returns the smaller of the magnitudes of two significant numbers.static SignificantNumber MinMagnitudeNumber(SignificantNumber x, SignificantNumber y)
- Returns the smaller of the magnitudes of two significant numbers.
Operators
static SignificantNumber operator -(SignificantNumber value)
- Negates a significant number.static SignificantNumber operator -(SignificantNumber left, SignificantNumber right)
- Subtracts one significant number from another.static bool operator !=(SignificantNumber left, SignificantNumber right)
- Determines whether two significant numbers are not equal.static SignificantNumber operator *(SignificantNumber left, SignificantNumber right)
- Multiplies two significant numbers.static SignificantNumber operator /(SignificantNumber left, SignificantNumber right)
- Divides one significant number by another.static SignificantNumber operator +(SignificantNumber value)
- Returns the unary plus of a significant number.static SignificantNumber operator +(SignificantNumber left, SignificantNumber right)
- Adds two significant numbers.static bool operator ==(SignificantNumber left, SignificantNumber right)
- Determines whether two significant numbers are equal.static bool operator >(SignificantNumber left, SignificantNumber right)
- Determines whether one significant number is greater than another.static bool operator <(SignificantNumber left, SignificantNumber right)
- Determines whether one significant number is less than another.static bool operator >=(SignificantNumber left, SignificantNumber right)
- Determines whether one significant number is greater than or equal to another.static bool operator <=(SignificantNumber left, SignificantNumber right)
- Determines whether one significant number is less than or equal to another.
Contributing
Contributions are welcome! Please feel free to submit a pull request or open an issue.
License
This project is licensed under the MIT License. See the LICENSE file for details.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net7.0 is compatible. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net7.0
- No dependencies.
-
net8.0
- No dependencies.
NuGet packages (1)
Showing the top 1 NuGet packages that depend on ktsu.io.SignificantNumber:
Package | Downloads |
---|---|
ktsu.io.PhysicalQuantity
Physical Quantity |
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
1.2.1 | 718 | 6/17/2024 |
1.2.0 | 100 | 6/17/2024 |
1.1.4 | 101 | 6/15/2024 |
1.1.3 | 94 | 6/14/2024 |
1.1.2 | 95 | 6/13/2024 |
1.1.1 | 88 | 6/13/2024 |
1.1.0 | 94 | 6/12/2024 |
1.0.1 | 95 | 6/11/2024 |
1.0.1-alpha.1 | 46 | 6/11/2024 |
1.0.0 | 93 | 6/11/2024 |
1.0.0-alpha.2 | 51 | 6/7/2024 |
1.0.0-alpha.1 | 55 | 6/7/2024 |