Skip to content
Protos

std:datetime/Period

std:datetime/Period

Section titled “std:datetime/Period”

Canonical occurrence: protos/lib/datetime/Period.protos · Protos revision: e99b712ecf658a527b1fe82c8beba2c1286d8dc9.

Calendar-relative amounts made of signed Integer years, months, and days. A period is a frozen ordinary object with exactly those three slots. The components are structural and are never normalized: twelve months are not one year, and days are never converted to or from months, because those relations depend on the date a period is applied to. A period is not a fixed elapsed amount; elapsed amounts are std:datetime/Duration values.

Every period’s immediate delegation parent is this module, the canonical period factory and prototype. recognizes accepts exactly the periods of this family: objects whose immediate parent is this module and whose local slots are exactly the period state and behavior slots with Integer components. Matching slots under another parent are not a period.

Periods answer structural equality through ==: two periods are equal when both are periods and their years, their months, and their days are equal, so (1, 0, 0) and (0, 12, 0) are different periods. hash is coherent with that equality, so independently constructed equal periods work as the same Map key. === remains ordinary object identity. Periods have no natural total order, and this module deliberately provides no compare.

Applying a period to a civil date is pure proleptic Gregorian arithmetic, with no offset, zone, or clock authority:

  1. years and months are combined into one month displacement and applied to the date’s year and month;
  2. the day of month is clamped once to the last day of the resulting month, so 31 January plus one month is the last day of February;
  3. days are then added as whole calendar days.

Years and months are never clamped separately, and application is not repeated one-month steps: applying one month twice may differ from applying two months once. Only the final date must lie in std:datetime/Date’s supported years; a final date outside them signals an Error and is never wrapped or saturated.

Observable top-level slots

Section titled “Observable top-level slots”

This page lists the complete mechanically observable top-level slot inventory required by D067. Authored documentation, when present, is canonical D062 prose; mechanical presence alone does not create a stability or compatibility promise.

addToDate

Section titled “addToDate”

Answers the std:datetime/Date reached by applying period to date: the combined year and month displacement first, then one clamp of the day to the last day of the resulting month, then the day displacement. A final date outside the supported years, or an argument that is not a period or a date, signals an Error.

Mechanical facts

Section titled “Mechanical facts”

addToLocalDateTime

Section titled “addToLocalDateTime”

Answers a fresh std:datetime/LocalDateTime whose date is addToDate(period, dateTime.date) and whose time is the same dateTime.time object, unchanged. Arguments that are not a period and a local date-time, or a final date outside the supported years, signal an Error.

Mechanical facts

Section titled “Mechanical facts”

call

Section titled “call”

Answers a fresh frozen period of years, months, and days. Every argument must be an Integer and may be positive, zero, or negative; any other argument signals an Error. The components are stored as given.

Mechanical facts

Section titled “Mechanical facts”

negate

Section titled “negate”

Answers a fresh period with exactly the negated years, months, and days of period, without any other normalization. A non-period argument signals an Error.

Mechanical facts

Section titled “Mechanical facts”

recognizes

Section titled “recognizes”

Answers true exactly when value is a period of this family: its immediate delegation parent is this module, its local slots are exactly years, months, days, equals, ==, and hash, and every component is an Integer. Answers false for any other value.

Mechanical facts

Section titled “Mechanical facts”

subtractFromDate

Section titled “subtractFromDate”

Answers the std:datetime/Date reached by applying the negation of period to date; exactly addToDate(negate(period), date).

Mechanical facts

Section titled “Mechanical facts”

subtractFromLocalDateTime

Section titled “subtractFromLocalDateTime”

Answers the local date-time reached by applying the negation of period to dateTime; exactly addToLocalDateTime(negate(period), dateTime).

Mechanical facts

Section titled “Mechanical facts”

Exact module source · Standard-library API · Standard library overview