API Period

Period

Concepts first: read Civil and Exact Arithmetic before this page.

Signatures below are shown as the library declares them. From a script that imports it, every type and enum name takes your import alias: t.DateTime, t.Overflow.REJECT, t.Exchange.NYSE. A bare DateTime will not compile.

A Period is a calendar-flavoured amount of time in the sense of java.time's Period: years, months and days. It is not convertible to milliseconds without a reference date, because months and years have no fixed length.

The type

Period

type

A calendar-flavoured amount of time, in the sense of java.time's Period. It is not convertible to milliseconds without a reference date, because months and years have no fixed length.

Field	Declared as	Meaning
Years	int Years = 0	Whole years.
Months	int Months = 0	Whole months.
Days	int Days = 0	Whole days.

Members

	Summary
equals	Whether two periods have identical fields.
is_negative	Whether any field of this period is negative.
is_zero	Whether every field of this period is zero.
minus	The difference of two periods, field by field.
multiplied_by	This period with every field scaled.
negated	This period with every field's sign flipped.
normalized	This period with surplus months folded into years, as java.time's Period.normalized: 1 year 15 months becomes 2 years 3 months.
plus	The sum of two periods, field by field.
to_iso	This period in ISO-8601 form, e.g. "P1Y2M3D".
to_total_months	The years and months of this period expressed as a month count.

Reference

equals

Period.equals(Period other)

Whether two periods have identical fields. 12 months and 1 year are not equal under this test; normalise both first if that is what you meant.

Parameter	Meaning
other	The second Period.

Returns   true when the fields match..

is_negative

Period.is_negative()

Whether any field of this period is negative. A period can be mixed, e.g. 1 year minus 5 days, so this asks whether any component points backward.

Returns   true when some field is negative..

is_zero

Period.is_zero()

Whether every field of this period is zero.

Returns   true for a zero period..

minus

Period.minus(Period other)

The difference of two periods, field by field.

Parameter	Meaning
other	The Period to subtract.

Returns   A new Period..

multiplied_by

Period.multiplied_by(int n)

This period with every field scaled.

Parameter	Meaning
n	The multiplier.

Returns   A new Period..

negated

Period.negated()

This period with every field's sign flipped.

Returns   A new Period..

normalized

Period.normalized()

This period with surplus months folded into years, as java.time's Period.normalized: 1 year 15 months becomes 2 years 3 months. Days are left alone, because a day is not a fraction of a month.

Returns   A new Period..

plus

Period.plus(Period other)

The sum of two periods, field by field. Not normalised, because 1 month plus 30 days is not a fixed quantity; call normalized() if you want months folded into years.

Parameter	Meaning
other	The second Period.

Returns   A new Period..

to_iso

Period.to_iso()

This period in ISO-8601 form, e.g. "P1Y2M3D". A zero period is "P0D", as in java.time.

Returns   The ISO-8601 period string..

to_total_months

Period.to_total_months()

The years and months of this period expressed as a month count. Days are excluded, since they do not convert.

Returns   Total whole months..

---

API Index  ·  Task Index  ·  Glossary