Currency Module

A comprehensive currency handling module for V that supports both fiat and cryptocurrency operations, currency conversion, and amount parsing.

Features

• Parse currency amounts from human-readable strings
• Support for fiat and cryptocurrencies
• Currency conversion and exchange rates
• USD value calculations
• Support for common currency symbols (€, $, £)
• Multiplier notation support (K for thousands, M for millions)

Basic Usage

Working with Amounts

import freeflowuniverse.crystallib.data.currency

// Parse amount from string
mut amount := currency.amount_get('20 USD')!
mut amount2 := currency.amount_get('1.5k EUR')!  // k for thousands
mut amount3 := currency.amount_get('2M TFT')!    // M for millions

// Using currency symbols
mut amount4 := currency.amount_get('€100')!      // Euro
mut amount5 := currency.amount_get('$50')!       // USD
mut amount6 := currency.amount_get('£75')!       // GBP

// Get USD value
usd_value := amount.usd()  // converts to USD based on currency's USD value

Currency Operations

// Get a currency
mut usd := currency.get('USD')!
mut eur := currency.get('EUR')!
mut tft := currency.get('TFT')!

// Create an amount with specific currency
mut amount := Amount{
    currency: usd
    val: 100.0
}

// Exchange to different currency
mut eur_amount := amount.exchange(eur)!

Amount String Format

The amount_get function supports various string formats:

// All these formats are valid
amount_get('10.3 USD')    // Space separated
amount_get('10.3USD')     // No space
amount_get('10.3 usd')    // Case insensitive
amount_get('$10.3')       // Currency symbol
amount_get('10.3')        // Defaults to USD if no currency specified
amount_get('5k USD')      // k multiplier for thousands
amount_get('1M EUR')      // M multiplier for millions

Multiplier Support

• K or k: Multiplies the amount by 1,000
• M or m: Multiplies the amount by 1,000,000

Examples:

amount_get('5k USD')!     // 5,000 USD
amount_get('2.5K EUR')!   // 2,500 EUR
amount_get('1M TFT')!     // 1,000,000 TFT

Currency Exchange

The module supports currency exchange operations based on USD values:

// Create amounts in different currencies
mut usd_amount := currency.amount_get('100 USD')!
mut eur_amount := currency.amount_get('100 EUR')!

// Exchange USD to EUR
mut in_eur := usd_amount.exchange(eur_amount.currency)!

// Exchange EUR to USD
mut back_to_usd := eur_amount.exchange(usd_amount.currency)!

USD Value Calculations

Every currency has a USD value that's used for conversions:

mut amount := currency.amount_get('100 EUR')!

// Get USD equivalent
usd_value := amount.usd()

// The calculation is: amount.val * amount.currency.usdval
// For example, if EUR.usdval is 1.1:
// 100 EUR = 100 * 1.1 = 110 USD

Error Handling

The module includes robust error handling:

// Handle parsing errors
amount := currency.amount_get('invalid') or {
    println('Failed to parse amount: ${err}')
    return
}

// Handle exchange errors
converted := amount.exchange(target_currency) or {
    println('Failed to exchange currency: ${err}')
    return
}

Currency Codes

• Standard 3-letter currency codes are used (USD, EUR, GBP, etc.)
• Special handling for cryptocurrency codes (TFT, BTC, etc.)
• Currency symbols (€, $, £) are automatically converted to their respective codes

Notes

• All decimal values use US notation (dot as decimal separator)
• Commas in numbers are ignored (both "1,000" and "1000" are valid)
• Whitespace is flexible ("100USD" and "100 USD" are both valid)
• Case insensitive ("USD" and "usd" are equivalent)

fn amount_get(amount_ string) !Amount

amount_get gets amount and currency from a string input ARGS:- amount_str string : a human-written string-decimals are done with US notation (.)- check in string for format e.g. 10.3usd or '10 usd' or '10 USD' or '10 usDC'allows £,$,€ to be used as special cases

fn get(name_ string) !Currency

get a currency object based on the name

fn rates_get(cur_array []string, crypto bool) !

// gets the latest currency exchange rates from an API on internet- an array of fiat codes e.g ['EUR', 'AED']

• an array of crypto codes e.g ['TERRA']e.g.

fn refresh() !

fn set_default(name_ string, val f64) !

struct Amount {
pub mut:
	currency Currency
	val      f64
}

fn (mut a0 Amount) exchange(target_currency_ Currency) !Amount

exchagen the amount to requested target currency

fn (a Amount) usd() f64

convert an Amount into usd ARGS:- Amount

struct Currency {
pub mut:
	name   string
	usdval f64
}