DOCSEARCHbyAlgolia
Submit Docs

SoulverCore Documentation

repository·master·Indexed 22 days ago

https://github.com/soulverteam/soulvercore

A natural language math engine written in Swift for macOS, iOS, iPadOS, and Mac Catalyst. SoulverCore enables complex calculations using human-readable strings, supporting unit conversions, date math, currency rates via CurrencyRateProvider, and variable substitution through the Calculator class.

Tokens
1.4K
Snippets
6
Records
8
Agent score
27%

What's inside SoulverCore

  1. Install SoulverCore via Swift Package Manager

    master

    To add SoulverCore to your Xcode project using SPM:

    1. In Xcode, go to File > Add Package Dependencies...
    2. Paste the following URL: https://github.com/soulverteam/SoulverCore
    https://github.com/soulverteam/SoulverCore

  2. Install SoulverCore manually

    master

    If you are not using SPM, you can install the .xcframework manually:

    1. Download SoulverCore.xcframework.zip from a tagged release.
    2. Unzip the archive.
    3. Drag SoulverCore.xcframework into the Frameworks, Libraries, and Embedded Content section of the General settings for your target (macOS, iOS, or Mac Catalyst).

  3. Handle international locales and separators

    master

    SoulverCore automatically respects the device's system locale for decimal and thousands separators. To explicitly use a different locale, convert the EngineCustomization using the convertTo(locale:) method.

    let europeanLocale = Locale(identifier: "de_DE")
let localizedCustomization = EngineCustomization.standard.convertTo(locale: europeanLocale)

let calculator = Calculator(customization: localizedCustomization)

/// In Germany a comma is used as a decimal separator
calculator.calculate("1,2 + 3,4") // 4,6

  4. Perform basic calculations with Calculator

    master

    The primary entry point for calculations is the Calculator class. You can initialize it with a customization (e.g., .standard) and use the calculate(_:) method to process natural language math strings. Results can be accessed via the stringValue property of the returned object.

    import SoulverCore

let calculator = Calculator(customization: .standard)
let result = calculator.calculate("123 + 456")
print("The answer is \(result.stringValue)") // prints 579

  5. Configure output formatting

    master

    Use FormattingPreferences to control how results are displayed. You can set properties like dp (decimal places) on a FormattingPreferences instance and assign it to the calculator.formattingPreferences property.

    var formattingPreferences = FormattingPreferences()
formattingPreferences.dp = 2 // decimal places
calculator.formattingPreferences = formattingPreferences

calculator.calculate("π") // 3.14

  6. Provide live currency rates using CurrencyRateProvider

    master

    The .standard customization uses hard-coded rates. To support live currency conversions, implement or use a CurrencyRateProvider and assign it to the currencyRateProvider property of an EngineCustomization.

    SoulverCore provides ECBCurrencyRateProvider out-of-the-box, which fetches rates from the European Central Bank.

    /// This is a currency rate provider that fetches 33 popular fiat currencies from the European Central Bank
let ecbCurrencyRateProvider = ECBCurrencyRateProvider()

/// Create a customization with this rate provider
var customizationWithLiveCurrencyRates = EngineCustomization.standard
customizationWithLiveCurrencyRates.currencyRateProvider = ecbCurrencyRateProvider

/// Create a calculator that uses this customization
let calculator = Calculator(customization: customizationWithLiveCurrencyRates)

/// Update to the latest rates...
ecbCurrencyRateProvider.updateRates { success in
    if success {
        let result = calculator.calculate("10 USD in EUR")
        print(result.stringValue)
    }
}

  7. Use variables in calculations

    master

    To use named variables in an expression, create a VariableList containing Variable objects. Pass this list to the calculate(_:with:) method.

    let variableList = VariableList(variables: [
    Variable(name: "variable 1", value: "123"),
    Variable(name: "variable 2", value: "456"),
])
calculator.calculate("variable 1 + variable 2", with: variableList) // 579