property.rental-yield Unreviewed

pub fn rental_yield(annual_rent: &Money, annual_costs: &Money, property_value: &Money) -> RentalYield

/// Both yields, and the net income behind the net one.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RentalYield {
    /// rent / value; 600 = 6.00%
    pub gross_basis_points: i64,
    /// (rent − costs) / value; negative when costs exceed rent
    pub net_basis_points: i64,
    /// rent − costs
    pub net_income: Money,
}

fune!(property.rental-yield@^1);  // then call rental_yield(…)

use super::funejson::Value;  ← the fune runtime: the JSON value the test vectors use; fune build keeps it only where a signature takes one
use super::math_round_div::round_div;  ← from math.round-div ^1.0.0 · built alongside by fune
use super::money_amount::{money, money_from_value, money_to_value, Money};  ← from money.amount ^1.0.0 · built alongside by fune

// Above this, amount * 10000 is no longer exact as a JavaScript number; the
// same limit applies here so every language refuses the same inputs.
const MAX_MINOR: i64 = 90_000_000_000;

/// Gross and net rental yield in basis points. Each is rounded once, half-up,
/// from the exact ratio, never from a rounded percentage.
///
/// # Panics
/// Panics on mismatched currencies, a value that is not positive, a negative
/// rent or cost, or an amount beyond the exact range.
pub fn rental_yield(annual_rent: &Money, annual_costs: &Money, property_value: &Money) -> RentalYield {
    let currency = property_value.currency.as_str();
    for other in [annual_rent, annual_costs] {
        if other.currency != currency {
            panic!("currency mismatch: {} and {}", other.currency, currency);
        }
    }
    if property_value.minor <= 0 {
        panic!("propertyValue must be greater than zero, received {}", property_value.minor);
    }
    if annual_rent.minor < 0 {
        panic!("annualRent must not be negative, received {}", annual_rent.minor);
    }
    if annual_costs.minor < 0 {
        panic!("annualCosts must not be negative, received {}", annual_costs.minor);
    }
    for m in [annual_rent.minor, annual_costs.minor, property_value.minor] {
        if m > MAX_MINOR {
            panic!("amounts must be at most {} minor units", MAX_MINOR);
        }
    }
    let net = annual_rent.minor - annual_costs.minor;
    RentalYield {
        gross_basis_points: round_div(annual_rent.minor * 10000, property_value.minor, "half-up"),
        net_basis_points: round_div(net * 10000, property_value.minor, "half-up"),
        net_income: money(net, currency),
    }
}

pub fn rental_yield_to_value(result: &RentalYield) -> Value {
    Value::obj(vec![
        ("grossBasisPoints", Value::Int(result.gross_basis_points)),
        ("netBasisPoints", Value::Int(result.net_basis_points)),
        ("netIncome", money_to_value(&result.net_income)),
    ])
}

pub fn fune_vector(args: &[Value]) -> Value {
    rental_yield_to_value(&rental_yield(
        &money_from_value(&args[0]),
        &money_from_value(&args[1]),
        &money_from_value(&args[2]),
    ))
}

Install

fune build

With that line in your source, in a Rust project (language rust in fune.project), fune build resolves it and its 2 dependencies, pins them in fune.lock, downloads only the Rust package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. A crate’s build.rs runs it before every compile. Or pin a range in fune.project and build in one step:

fune add property.rental-yield

The manifest, vectors and README with only the Rust implementation. Install it without the registry with fune add ./property.rental-yield-1.0.1-rust.fune, or fetch it from a terminal with fune pull property.rental-yield@1.0.1:rust.

The whole function, every language, is one file too: property.rental-yield-1.0.1.fune, 15,991 bytes, sha256 3e882f7973bc1f8825bfd157c4753a5bf3177593459909e2f106244e03404142. It installs into a project of any language.

// fune: before property.rental-yield

// fune: after property.rental-yield

// fune: replace math.round-div in property.rental-yield
// fune: replace money.amount in property.rental-yield

// fune: step property.rental-yield after <n|label>

More from the author

Both are integer basis points (600 = 6.00%), rounded half-up (a half basis point away from zero), once, from the exact ratio. The net income behind the net yield is returned too, so a caller never recomputes it.

## Edge cases

- Costs above the rent give a negative net yield and a negative net income; that is an answer, not an error. - A zero rent gives a zero gross yield. - All three amounts must be in one currency, and the value must be greater than zero.

## What it does not do

Mortgage interest, tax, voids and capital growth are the caller's to fold into the costs (or not). "Net yield" has no statutory definition; this is the plain (rent − costs) / value that letting agents quote. Rent and value up to £900 million keep the arithmetic exact in every language.

## Before you rely on this

**Not professional advice.** This capability calculates property figures from published rules. It is a software component for developers, not legal or financial advice. Rules change and every rate here has an effective date. Check that the dates cover your case. Verify results against the official sources listed above, and have a conveyancer or tax adviser review how you use it, before anyone relies on the output. Provided "as is" under its licence, without warranty.

**Unreviewed.** This capability's implementations agree in every language and pass its published test vectors, which were worked out from the official sources cited. But no qualified conveyancer or tax adviser has yet checked those vectors, or confirmed that the capability covers the cases it claims. Treat it as a draft. Do not use it for real people, money or decisions without your own expert review. Once a qualified reviewer signs off, this notice is replaced with their name, qualification and the date. Each new version needs fresh sign-off.

1.0.1 marks it unreviewed. The code and the tests are unchanged.

Files