Table of Contents

Struct BinaryAmount

Namespace
Virtufin.Core.Position
Assembly
Virtufin.Core.dll

Fixed-point amount with base 2 (binary scaling), stored as a whole part, a fractional part, and a precision (number of binary fraction digits). The represented value is Whole + Fraction / 2^N.

public readonly record struct BinaryAmount : IFixedPointAmount<BinaryAmount>, IFixedPointAmount, IAmount, IComparable<BinaryAmount>, IAsCardinal<long>, IAdditionOperators<BinaryAmount, BinaryAmount, BinaryAmount>, ISubtractionOperators<BinaryAmount, BinaryAmount, BinaryAmount>, IMultiplyOperators<BinaryAmount, BinaryAmount, BinaryAmount>, IDivisionOperators<BinaryAmount, BinaryAmount, BinaryAmount>, IEquatable<BinaryAmount>
Implements
Inherited Members

Remarks

Exists alongside DecimalAmount to exercise and prove the base-agnosticism of IFixedPointAmount and FixedPointArithmetic. Arithmetic follows the same rules: addition/subtraction require a common base and precision and throw PrecisionMismatchException without it; ordering throws on a mismatched precision too, while equality returns false. See DecimalAmount for why those two differ.

Constructors

BinaryAmount(long, ulong, int)

Fixed-point amount with base 2 (binary scaling), stored as a whole part, a fractional part, and a precision (number of binary fraction digits). The represented value is Whole + Fraction / 2^N.

public BinaryAmount(long Whole, ulong Fraction, int N)

Parameters

Whole long
Fraction ulong
N int

Remarks

Exists alongside DecimalAmount to exercise and prove the base-agnosticism of IFixedPointAmount and FixedPointArithmetic. Arithmetic follows the same rules: addition/subtraction require a common base and precision and throw PrecisionMismatchException without it; ordering throws on a mismatched precision too, while equality returns false. See DecimalAmount for why those two differ.

Fields

DefaultPrecision

Default precision (binary fraction digits) for newly constructed amounts.

public const int DefaultPrecision = 8

Field Value

int

MaxPrecision

Largest precision a BinaryAmount can express: 2^62 fits in a long, 2^63 overflows into the sign bit.

public const int MaxPrecision = 62

Field Value

int

Radix

Radix of the fractional representation.

public const int Radix = 2

Field Value

int

Properties

Base

Radix of the fractional representation (e.g. 10 or 2). Always >= 2.

public int Base { get; }

Property Value

int

BaseValue

The type's fixed base, usable in generic code without an instance. Mirrors the instance Base.

public static int BaseValue { get; }

Property Value

int

Fraction

The fractional part, a magnitude in [0, Base^Precision).

public ulong Fraction { get; init; }

Property Value

ulong

IsZero

true when this amount equals the additive identity.

public bool IsZero { get; }

Property Value

bool

N 

public int N { get; init; }

Property Value

int

Precision

Number of fractional digits carried by this amount.

public int Precision { get; }

Property Value

int

Whole

The whole (integral) part.

public long Whole { get; init; }

Property Value

long

Zero

A zero amount at DefaultPrecision precision.

public static BinaryAmount Zero { get; }

Property Value

BinaryAmount

Methods

CompareTo(BinaryAmount)

Compares the current instance with another object of the same type and returns an integer that indicates whether the current instance precedes, follows, or occurs in the same position in the sort order as the other object.

public int CompareTo(BinaryAmount other)

Parameters

other BinaryAmount

An object to compare with this instance.

Returns

int

A value that indicates the relative order of the objects being compared. The return value has these meanings:

Value Meaning
Less than zero This instance precedes other in the sort order.
Zero This instance occurs in the same position in the sort order as other.
Greater than zero This instance follows other in the sort order.

Exceptions

PrecisionMismatchException

Precisions differ.

CompareTo(IAmount)

Compare with another amount. Implementations reject differing scales (base/precision) at runtime via PrecisionMismatchException.

public int CompareTo(IAmount other)

Parameters

other IAmount

Amount to compare against.

Returns

int

Create(long, ulong, int)

Construct an instance from decomposed parts at the given precision.

public static BinaryAmount Create(long whole, ulong fraction, int precision)

Parameters

whole long

Whole part.

fraction ulong

Fractional magnitude in [0, Base^precision).

precision int

Number of fractional digits.

Returns

BinaryAmount

Equals(BinaryAmount)

Indicates whether the current object is equal to another object of the same type.

public bool Equals(BinaryAmount other)

Parameters

other BinaryAmount

An object to compare with this object.

Returns

bool

true if the current object is equal to the other parameter; otherwise, false.

Remarks

Precision is part of identity: an amount at a different N is a different value, never an equal one. It returns false rather than throwing, unlike CompareTo(BinaryAmount) -- that asymmetry is deliberate and mirrors the BCL, where a type mismatch makes Equals(object) return false but CompareTo(object) throw. Equality is called implicitly by dictionaries, Contains, Distinct and by the generated equality of any record holding an amount, where a throw cannot be caught.

From(decimal, int)

Construct a BinaryAmount from a decimal, rounding half away from zero to n binary fraction digits.

public static BinaryAmount From(decimal value, int n)

Parameters

value decimal

Source value.

n int

Precision (number of binary fractional digits).

Returns

BinaryAmount

From(double, int)

Construct a BinaryAmount from a double, rounding half away from zero to n binary fraction digits.

public static BinaryAmount From(double value, int n)

Parameters

value double

Source value.

n int

Precision (number of binary fractional digits).

Returns

BinaryAmount

FromCardinal(long)

Recover whole and fractional parts from a cardinal value at this amount's precision.

public (long Whole, ulong Fraction) FromCardinal(long cardinal)

Parameters

cardinal long

Returns

(long Whole, ulong Fraction)

FromCardinal(long, int)

Recover whole and fractional parts from a cardinal value at an explicit precision.

public static (long Whole, ulong Fraction) FromCardinal(long cardinal, int n)

Parameters

cardinal long
n int

Returns

(long Whole, ulong Fraction)

GetHashCode()

Returns the hash code for this instance.

public override int GetHashCode()

Returns

int

A 32-bit signed integer that is the hash code for this instance.

ToCardinal()

The value as a single checked integer scaled by Base^Precision: Whole * Base^Precision + Fraction.

public long ToCardinal()

Returns

long

ToDouble()

Convert to double.

public double ToDouble()

Returns

double

ToString()

Format the amount as whole.bbbb with N binary fraction digits.

public override string ToString()

Returns

string

Operators

operator +(BinaryAmount, BinaryAmount)

Add two amounts. Throws OverflowException on overflow.

public static BinaryAmount operator +(BinaryAmount left, BinaryAmount right)

Parameters

left BinaryAmount
right BinaryAmount

Returns

BinaryAmount

operator /(BinaryAmount, BinaryAmount)

Divide two amounts, carrying the dividend's precision, rounded half away from zero. Throws DivideByZeroException when the divisor is zero.

public static BinaryAmount operator /(BinaryAmount left, BinaryAmount right)

Parameters

left BinaryAmount
right BinaryAmount

Returns

BinaryAmount

operator *(BinaryAmount, BinaryAmount)

Multiply two amounts, carrying the summed precision of the operands.

public static BinaryAmount operator *(BinaryAmount left, BinaryAmount right)

Parameters

left BinaryAmount
right BinaryAmount

Returns

BinaryAmount

operator -(BinaryAmount, BinaryAmount)

Subtract two amounts. Throws OverflowException on overflow.

public static BinaryAmount operator -(BinaryAmount left, BinaryAmount right)

Parameters

left BinaryAmount
right BinaryAmount

Returns

BinaryAmount