Standard-Bibliothek — `geld`

Verfügbar — implementiert in Phase B.6.4. Vollständige Spec in docs/geld.md.

Geld ist überall in echten Programmen: Preise, Rechnungen, Buchhaltung, Wechselkurse. Kiste hat dafür einen eigenen Wert-Typ Geld — kein Karten-Hack, keine Klasse, sondern erste-Klasse-Sprach-Bürger.

20.1 Aktivieren und Konstruieren

nutze geld

nimm preis  = geld.neu(19.95, "CHF")
nimm yen    = geld.neu(1000, "JPY")
nimm btc    = geld.neu(0.00125, "BTC")

sag preis              // 19.95 CHF
sag typ(preis)         // Geld
sag typ(preis) == Geld // wahr

Konvention: geld.neu(betrag, währung). Währung ist beliebiger Text — keine Validierung, keine ISO-4217-Tabelle hartcodiert. CHF, EUR, USD, GBP, JPY, BTC oder dein eigenes Token: alles erlaubt.

20.2 Operatoren funktionieren direkt

Die Standard-Operatoren + - * / < > <= >= == != funktionieren auf Geld-Werten — mit klaren Regeln, was geht und was nicht:

nimm a = geld.neu(50, "CHF")
nimm b = geld.neu(20, "CHF")

sag a + b           // 70.00 CHF
sag a - b           // 30.00 CHF
sag a * 2           // 100.00 CHF       ← Skalar-Multiplikation
sag 2 * a           // 100.00 CHF       ← kommutativ
sag a / 4           // 12.50 CHF        ← Skalar-Division
sag a / b           // 2.5              ← Verhältnis (dezimal, einheitenlos)
sag -a              // -50.00 CHF
sag a > b           // wahr
sag a == geld.neu(50, "CHF")    // wahr

20.3 Was bewusst NICHT geht (mit lehrreichen Fehlern)

geld.neu(50, "CHF") + geld.neu(20, "EUR")
// Geldbeträge in verschiedenen Währungen können nicht direkt addiert
//    werden — bekam CHF und EUR. Nutze geld.in_währung(...) für eine
//    explizite Konvertierung.

geld.neu(50, "CHF") + 20
// Geld kann nicht direkt mit ganz addiert werden — Geldbeträge brauchen
//    eine Währung. Nutze geld.neu(20, "CHF") um die Zahl zu Geld zu machen.

geld.neu(50, "CHF") * geld.neu(20, "CHF")
// Geld * Geld ergibt keine sinnvolle Einheit (CHF² gibt's nicht).

geld.neu(50, "CHF") < 60
// Geld kann nicht direkt mit ganz verglichen werden.

Prinzip: keine versteckte Magie. Wenn du verschiedene Währungen mischst, willst du das wahrscheinlich nicht stillschweigend (Wechselkurs vergessen, falsche Zahl). Kiste zwingt dich zur expliziten Konvertierung.

20.4 Equality ist immer sicher (kein Fehler)

geld.neu(50, "CHF") == geld.neu(50, "CHF")    // wahr
geld.neu(50, "CHF") == geld.neu(50, "EUR")    // falsch (kein Fehler!)
geld.neu(50, "CHF") == geld.neu(50, "chf")    // falsch (case-sensitive)
geld.neu(50, "CHF") == 50                     // falsch (Zahl ist nicht Geld)
geld.neu(50, "CHF") == geld.neu(50.00, "CHF") // wahr (Skala ignoriert)

== und != sind die EINZIGEN Operatoren, die zwischen verschiedenen Geld-Werten erlaubt sind und nie einen Fehler werfen — sie geben einfach falsch. Das ist konsistent mit Kistes strikter Equality (E-041).

20.5 Konvertierung mit explizitem Wechselkurs

nimm chf_betrag = geld.neu(100, "CHF")
nimm eur_betrag = geld.in_währung(chf_betrag, "EUR", 1.06)
sag eur_betrag          // 106.00 EUR

Kein Live-Kurs in geld. Kurse liefert dein Code (oder später ein netz-Modul) — geld selbst ist offline und stateless. So bleibt das Modul testbar und vorhersagbar.

20.6 Rundung — international, generisch

nimm rohpreis = geld.neu(12.473, "CHF")

sag geld.gerundet_auf(rohpreis, 0.05)   // 12.45 CHF   (Schweizer 5-Rappen)
sag geld.gerundet_auf(rohpreis, 0.01)   // 12.47 CHF   (EUR/USD Cent)
sag geld.gerundet_auf(rohpreis, 1)      // 12.00 CHF   (auf ganze Franken)

sag geld.gerundet_auf(geld.neu(1234.5, "JPY"), 1)
// 1234.00 JPY   ← Banker's: zur geraden Ziffer

Generisch über alle Währungen, keine Hartcodierung. Der schritt-Parameter ist ein normaler dezimal/ganz — wer Bitcoin-Satoshis runden will: geld.gerundet_auf(g, 0.00000001).

20.7 Custom-Formatierung

nimm gross = geld.neu(1234567.89, "CHF")

sag gross
// 1234567.89 CHF                   ← Default: keine Trenner

sag geld.formatiert(gross, {"trenner": "'"})
// 1'234'567.89 CHF                 ← Schweizer Apostroph

sag geld.formatiert(gross, {
    "trenner": ".",
    "dezimal_zeichen": ",",
})
// 1.234.567,89 CHF                 ← deutsche Notation

sag geld.formatiert(geld.neu(99.99, "EUR"), {
    "währung_position": "vorne",
    "symbol": "€",
    "währung_lücke": "",
})
// €99.99

Optionen-Schlüssel im Detail in docs/geld.md §4.4.

20.8 Negative Beträge sind erlaubt

Geld kann negativ sein — Schulden, Rückzahlungen, Korrekturen.

nimm rückerstattung = geld.neu(-50, "CHF")
sag rückerstattung                       // -50.00 CHF
sag -geld.neu(50, "CHF")                 // -50.00 CHF
sag geld.neu(100, "CHF") + rückerstattung   // 50.00 CHF

20.9 Was nicht in geld ist

• Live-Wechselkurse — geld ist offline. Kurse holen ist Aufgabe von netz (kommt später).
• ISO-4217-Validierung der Währung — würde lokalisiertes Wissen einbacken.
• Locale-Formatierung im Default — nutze geld.formatiert mit Optionen.
• Modulo / Potenz auf Geld — semantisch sinnlos.
• geld * komma — komma ist näherungsweise, Geld ist exakt. Konvertiere vorher mit als_dezimal(...).

---