The Interpretation enum captures the semantic meaning of a calculated price value, not just its numeric result. The same mathematical function can represent different economic concepts depending on its interpretation.
Average price per single unit.Description:"Average price per single unit"Mathematical Relations:
UnitAverage(q) = Total(q) / q - Total divided by quantity
Applicability:
⚠️ Only for 1-dimensional functions (quantity, time, weight, etc.)
❌ Ambiguous for multi-dimensional functions
Examples:
“PLN 10.00 per kilogram”
“PLN 150.00 per hour”
“Average price per item: PLN 9.33”
“EUR 0.05 per kWh”
Use Cases:
Unit pricing labels
Rate cards
Comparative shopping
Per-item costs
Why “Average”?
When prices vary by quantity (e.g., volume discounts), the unit price represents the average across all units, not the price of any specific unit.
// Unit price: PLN 10 per itemCalculator unitCalc = new SimpleFixedCalculator( "Unit Price", Money.pln(10), Interpretation.UNIT);// Convert to total priceCalculator totalCalc = UnitToTotalAdapter.wrap( "Total Price", unitCalc);Money total = totalCalc.calculate( Parameters.of("quantity", BigDecimal.valueOf(5)));// Returns: PLN 50.00 (10 × 5)// Interpretation changed from UNIT to TOTAL
TOTAL → UNIT
// Total price: PLN 150 for any quantityCalculator totalCalc = new SimpleFixedCalculator( "Fixed Total", Money.pln(150), Interpretation.TOTAL);// Convert to unit price (average)Calculator unitCalc = TotalToUnitAdapter.wrap( "Unit Price", totalCalc);Money unitPrice = unitCalc.calculate( Parameters.of("quantity", BigDecimal.valueOf(10)));// Returns: PLN 15.00 (150 / 10)// Interpretation changed from TOTAL to UNIT
TOTAL → MARGINAL
// Step function returning total priceCalculator totalCalc = new StepFunctionCalculator( "Volume Pricing", Money.pln(100), BigDecimal.valueOf(10), BigDecimal.valueOf(5), Interpretation.TOTAL);// Convert to marginal priceCalculator marginalCalc = TotalToMarginalAdapter.wrap( "Marginal Price", totalCalc);// What does the 15th unit cost?Money marginal15 = marginalCalc.calculate( Parameters.of("quantity", BigDecimal.valueOf(15)));// Returns: PLN 5.00// Calculation: Total(15) - Total(14) = PLN 105.00 - PLN 100.00
// Early bird pricing: total price increases dailyCalculator earlyBirdTotal = new DailyIncrementCalculator( "Early Bird Total", LocalDate.of(2024, 6, 1), Money.pln(1999), // start price Money.pln(100), // daily increment Interpretation.TOTAL);// Day 7: What's the total price?Money totalPrice = earlyBirdTotal.calculate( Parameters.of("date", LocalDate.of(2024, 6, 8)));// Returns: PLN 2699.00// Interpretation: "Total ticket price on June 8 is PLN 2699.00"// Convert to marginal: how much does waiting one more day cost?Calculator marginalWaitingCost = TotalToMarginalAdapter.wrap( "Waiting Cost", new DailyIncrementCalculator( "Daily Cost", LocalDate.of(2024, 6, 1), Money.pln(0), // marginal starts at 0 Money.pln(100), // daily marginal cost Interpretation.TOTAL // will be converted to MARGINAL ));// Note: For daily increment with constant rate,// marginal is constant at PLN 100/day
Important Constraint: All component calculators in a CompositeFunctionCalculator must have the same interpretation.The composite calculator’s interpretation() method returns the shared interpretation of its components.
Valid Composite:
// Both components return TOTAL priceCalculator smallOrders = new SimpleFixedCalculator( "Small Orders", Money.pln(50), Interpretation.TOTAL // ✅ TOTAL);Calculator largeOrders = new StepFunctionCalculator( "Large Orders", Money.pln(100), BigDecimal.valueOf(10), BigDecimal.valueOf(5), Interpretation.TOTAL // ✅ TOTAL);// Valid - both are TOTALCalculator composite = new CompositeFunctionCalculator( "Order Pricing", ranges, repository);composite.interpretation(); // Returns: TOTAL
Invalid Composite:
// Mixing TOTAL and UNIT - will throw exceptionCalculator calc1 = new SimpleFixedCalculator( "Total Price", Money.pln(100), Interpretation.TOTAL // ❌ TOTAL);Calculator calc2 = new SimpleFixedCalculator( "Unit Price", Money.pln(10), Interpretation.UNIT // ❌ UNIT);// Throws IllegalArgumentException:// "All component calculators must have the same interpretation"Calculator composite = new CompositeFunctionCalculator( "Mixed Pricing", ranges, repository);
Most calculators default to Interpretation.TOTAL when not specified:
// These are equivalent:Calculator calc1 = new SimpleFixedCalculator( "Monthly Fee", Money.pln(99));Calculator calc2 = new SimpleFixedCalculator( "Monthly Fee", Money.pln(99), Interpretation.TOTAL);calc1.interpretation(); // Returns: TOTAL (default)calc2.interpretation(); // Returns: TOTAL (explicit)
