Functional Weave
Code in TypeScript

invest.dividend-yield@1.0.0

README.md

1,377 bytes · view raw

# 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.