Add Compare method to enable smoother generic programming against decimal.Decimal

Hello!

I propose that the method

func (d Decimal) Compare(d2 Decimal) int

be added to this package, much like Equal was added along side Equals. I will prepare a PR to this end.

Rationale

In the context of generic programming, decimal.Decimal is comparable in the sense that values of type decimal.Decimal can be compared using the builtin ==, but using == on decimals is rarely the right thing to do, as this playground shows: https://go.dev/play/p/_9-qTJ3j26c

Instead, this package exports:

func (d Decimal) Equal(d2 Decimal) bool

Note also how this is similar to the story of time.Time, where comparing values with ==, though possible, is rarely the right thing to do, so time.Time exports:

func (t Time) Equal(u Time) bool

Generalising, when it comes to being method-level "comparable" rather than language-level comparable using ==:

type Comparable[T any] interface {
    Equal(T) bool
}

A generic function or type with the constraint T Comparable[T] works on time.Time and on decimal.Decimal today, when it comes to the question of equality. It seems like there is some level of consensus that the correct signature to use when expressing equality at the method level is func(T) Equal(T) bool.

The same cannot be said for ordering on decimals, however. Following the blueprint of time.Time, what I really wish I could write is:

type Ordered[T any] interface {
    Compare(T) int
}

However, Decimal only exports func (d Decimal) Cmp(d2 decimal) int, Cmp and Compare are different names, so I cannot write a generic function or type with constraint T Ordered[T] and have it work both with time.Time and decimal.Decimal on a generic ordering.

Workarounds from outside the decimal package are possible, but they are unpleasant, and they require dropping the otherwise powerful T Ordered[T] type constraint, and moving away from the completely static realm of writing T Ordered[T] and using T and []T, into a more dynamic realm of using interface values and a wrapper type.

I don't believe there is consensus in the community around what the name of this method should be, but I think following time.Time and the naming in https://pkg.go.dev/cmp cannot possibly be wrong, even if there are no prescriptions or guidelines on this particular topic yet.

Adding Compare would increase the API surface slightly, but it would enable programming against the T Ordered[T] constraint as described above, and would make generic programming against decimal.Decimal much smoother, so I think it is worth our while. If it turns out that Cmp(T) int (the signature for the equivalent method on *big.Int) emerges as the standard in the future, then not much will have been lost, but something new would have been enabled in the meantime.

shopspring / decimal

Add Compare method to enable smoother generic programming against decimal.Decimal #345

Rationale