New vs Create, and other API cleanups, and Instantiating Numbers

[pascallouisperez]

Renames

• Remove NewValue and replace it instead by a NewNumber of some sort -- see below. Right now, because we have NewUndefined, NewText, and NewBool, the generic helper NewValue is used only to create numbers;
• Rename NewDefinitions to ParseDefinitions to more clearly indicate what's involved;
• Rename NewWorksheet to CreateWorksheet to differentiate it from creating new values: worksheets can be mutated and have a lifecycle, whereas undefined/text/bool/number are immutable values.
• Rename NewStore to NewDbStore because it creates a *DbStore. (We could imagine having a FileStore at some point, or similar.)

Instantiating Numbers
Provide two constructors which are guaranteed not to panic, plus the constructor from string:

1. func NewNumberFromInt(int64) *Number
2. func NewNumberFromFloat(float64) *Number
3. func NewNumberFromString(string) (*Number, error)

Here is a quick survey of the Golang world of arbitrary-precision math libraries which informed the suggestion above:

• apd offers
  • func New(coeff int64, exponent int32) *Decimal
  • func NewFromString(s string) (*Decimal, Condition, error)
  • func NewWithBigInt(coeff *big.Int, exponent int32) *Decimal
• math/big offers
  • func NewFloat(x float64) *Float
  • func NewInt(x int64) *Int
  • func NewRat(a, b int64) *Rat
• decimal offers
  • func New(value int64, exp int32) Decimal
  • func NewFromBigInt(value *big.Int, exp int32) Decimal
  • func NewFromFloat(value float64) Decimal
  • func NewFromFloatWithExponent(value float64, exp int32) Decimal
  • func NewFromString(value string) (Decimal, error)

[cbelsole]

For the func NewInt(int64) *Number consider func NewNumberFromInt64(int64) *Number since you are returning a Number and it shares a package with multiple types and FromInt64 since that leaves you open to create func NewNumber(int) *Number as a default. That also sets the func NewNumber(string) (*Number, error) to be func NewNumberFromString(string) (*Number, error) and func NewNumberFromFloat64(float64) *Number respectively.

[pascallouisperez]

+1 @cbelsole thanks!

[pascallouisperez]

Some updates:

• For the store related comments in this issue, see Cleanup Store, NewStore, Open, and Session #97 instead.
• And on the number side, see Cleanup: using NewNumberFromXxx vs the general NewValue #107 and Removing the last uses of NewValue which were too generic. #108 which addresses this fully.

[pascallouisperez]

Looking at this a few months later, not a fan of ParseDefinitions: it's not just parsing, it's also some level of semantic interpretation (e.g. no duplicate names, options wiring, some type checking, etc). Maybe LoadDefinitions, or CompileDefinitions?

Some inspirations

• regexp.Compile
• time.LoadLocation
• Hibernate uses 'configure' and 'build'

[pascallouisperez]

We're going to go with LoadDefinitions.