# invest.dividend-yield

A share's or fund's dividend yield two ways, in basis points (10000 = 100%):

- **Trailing** (historic): the dividends actually paid in the last twelve
  months, added up, over today's price. It is what happened, and it includes
  any special dividend, which is why it can overstate what an investor will
  receive next year.
- **Forward** (indicated): the latest declared regular dividend, times the
  number of regular payments a year, over today's price. After a dividend cut
  it falls at once, while the trailing yield takes a year to catch up.

Both are rounded half-up to a whole basis point, from exact integer
arithmetic.

## Pence and fractions of a penny

`Money` holds whole minor units, but UK dividends are often declared in
fractions of a penny (11.8p). A yield is a ratio, so give the price and the
dividends for a lot instead: per 100 shares, 11.8p is 1180 and a price of
1,234.56p is 123456. The yields are the same; the annual amounts are per lot.

## What it does not do

It does not decide which dividends fall in the last twelve months (pass the
ones that do, by ex-dividend or payment date as your policy says), convert
currencies, or gross up for tax credits. Price and dividends must be in one
currency.

## Errors

A price of 0 or less, a negative or fractional dividend, `paymentsPerYear`
outside 1-52, and mixed currencies.

## Before you rely on this

**Not professional advice.** This capability calculates investment figures from published rules. It is a software component for developers, not 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 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 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.