3.1.0

Calculation Features

Non-decimal bases

• Do unit calculations using non-base 10 numbers, like "0xF days in μs"
• Added support for converting into other bases using the converter "as base x", like "0b101101 as base 16" (= 0x2D)
  • Base 2, 8, 10, and 16 are supported
• Support for hex(), bin() and oct() and int() functions (matching the format supported by Python)
• Support for "as oct" as a synonym for "as octal"

Rounding up/down to nearest x phrase functions

• "round 310 up to nearest hundred" (= 400)
• "round 390 down to nearest hundred" (= 300)

Time zone calculations

• Support for the use of "time" as a comment word, like "3pm Sydney time to London time"
• Implicit interpretation of "from here" in certain cases: "3pm to Chicago" (assumes a conversion of 3pm here to Chicago)
• Support for "time now" and "date today" phrases
• Added "Tampa, Florida" as a built-in timezone city

Unix timestamps

• Support for millisecond timestamps, like "1733823083000 ms to date"
• An expression like "1733823083000 to date" will also be interpreted as a ms (rather than second) timestamp, because this makes more sense.

Units

• Added barrels (bbl) unit, defined as 158.987 liters

Bug fixes

• Fixed a crash when inputting "1s + 1970 in date"
• Fixed a crash with the "moon phase" astrological function
• Fixed an issue where an expression like "523 bits/s ÷ 5 bits" was returning a bps/bits rate instead of resolving into hertz

API

New API: LineCollectionEditingHelper

Supports efficiently and concisely making Soulver-like "text view & answer column" calculation views

• The LineCollectionEditingHelper is a glue object that acts as a controller layer between your view (typically, but not limited to, UITextView or NSTextView), and a LineCollection model object (that handles the actual line-by-line calculation)
• Your job is to notify an instance of LineCollectionEditingHelper whenever the user makes an edit to your text view.
  • LineCollectionEditingHelper will do the hard work of figuring out which lines in yourLineCollection ultimately need adding/removing/updating
• A sample (AppKit) Mac app demonstrating how to use LineCollectionEditingHelper is included in this repository (with many comments)
• Check it out, and see how we built a calculating text view (with syntax highlighting) and answer table in <150 lines of Swift code (and most of that is view setup and updating)

New API: TokenListSemantics

Supports syntax coloring expressions

• A new TokenListSemantics class provides a semantic analysis layer on top of TokenList that tags the parts of a math expression with a semantic type (number, unit, timezone, etc)
• Get a semantics object from the metadata on a TokenList object (tokenList.metadata.semantics) and use it to enumerate through the semantic tokens in an expression (with ranges)
• We've built this API to make doing syntax coloring in a calculator or Soulver-like app easy. You might have been be tempted to use TokenList for this in the past, but its tree-like structure is optimized for evaluation (not syntax coloring), and concrete token types change between releases without notice
• In contrast, you can rely on the semantic token types from TokenListSemantics to remain fairly consistent across releases, and any changes to its semantic token types will be documented

Formatting API

• The unformatted static property on FormattingPreferences can be used for when you want most unformatted result (no thousands separator, rounding, and currency codes (USD) instead of symbols ($))

(Unlikely) breaking changes

• Much of the conversion system in SoulverCore has been rewritten in this release to be more flexible and powerful
• There have been been many changes to TokenType and TokenSubType as a result (for example, type name and converter subtypes are no longer available)
• A friendly reminder to never rely on the presence of particular token types when using SoulverCore: they change frequently as the framework evolves
  • Stability in this regard is not part of the SoulverCore API contract (and you shouldn't need it to be)