year — Extract calendar year components from datetime values with MATLAB-compatible output shaping.
year(t) extracts year numbers from datetime values and retained legacy date inputs, returning double values with the input shape.
Syntax
X = year(t)
X = year(t, yearTypeOrFormat)Inputs
value- Type
Any- Required
- Yes
- Description
- Datetime input.
t- Type
Any- Required
- Yes
- Description
- Legacy serial date number or date text.
F- Type
StringScalar- Required
- Yes
- Description
- Legacy datestr input format.
Returns
X- Type
Any- Description
- Numeric scalar/tensor result.
Errors
RunMat:datetime:InvalidArgument- When
- Arguments or option grammar do not match supported datetime forms.
- Message
datetime: invalid argument
RunMat:datetime:InvalidInput- When
- Input values cannot be parsed, converted, or broadcast to a valid datetime result.
- Message
datetime: invalid input
RunMat:datetime:Internal- When
- Internal datetime state is invalid.
- Message
datetime: internal operation failed
Behavior and options
year(t) accepts datetime scalars and arrays. The optional year type is 'iso' or 'gregorian'.
For compatibility with existing code, serial date numbers and text dates are also accepted; an optional date format can be supplied for legacy input.
The output shape matches the input shape.
The returned values are numeric doubles, even when the years are mathematically integers.
RunMat mode additionally accepts single-precision and native integer legacy serial-date storage.
Host execution and residency
datetime values are host-side objects; year reads the stored serial-date data on the CPU.
No. year reads datetime objects on the CPU and returns ordinary host-side numeric arrays.
year does not dispatch GPU kernels. If the datetime was produced from gathered numeric data, the result still remains a CPU numeric array.
Owned calendar policy
Relative date text and timezone-aware text use the invocation-owned calendar service. Hosted execution uses the admitted local platform policy; deterministic deployment uses explicit calendar inputs and fails closed if conversion is unavailable. Numeric and datetime component reads do not acquire an ambient clock.
Finite execution frontier
Finite Managed calendar work is currently unsupported: the canonical host-allocation policy refuses before gathers, calendar scratch, or output publication. An initially unbounded call is checked again after suspension. Full managed scratch/output ownership remains an explicit implementation obligation; this safety fence is not Managed completion.
Examples
Extract the year from a scalar datetime
t = datetime(2024, 4, 9, 13, 30, 0);
y = year(t)Expected output:
y = 2024Extract years from a datetime array
t = datetime([2024 2025], [1 6], [15 20]);
y = year(t)Expected output:
y =
2024 2025Select ISO and Gregorian year modes
t = datetime(2024, 4, 9);
yIso = year(t, 'iso');
yGregorian = year(t, 'gregorian');Using year with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how year changes the result.
Run a small year example, explain the result, then change one input and compare the output.
FAQ
Does year preserve the input shape?⌄
Yes. A scalar datetime returns a scalar double, and datetime arrays return numeric arrays of the same size.
Does year return integers?⌄
It returns MATLAB-style doubles whose values are whole-number years.
Does year run on the GPU?⌄
No. datetime values are host-side objects, so year executes on the CPU.
Related Datetime functions
Calendar Duration
caldays · calendarDuration · calendarDuration.eq · calendarDuration.minus · calendarDuration.ne · calendarDuration.plus · calmonths · calquarters · calweeks · calyears · datetick · iscalendarduration · isdatetime
Datetime
Construction
Operators
datetime.eq · datetime.ge · datetime.gt · datetime.le · datetime.lt · datetime.minus · datetime.ne · datetime.plus
Indexing
Duration
days · duration · duration.eq · duration.ge · duration.gt · duration.le · duration.lt · duration.minus · duration.ne · duration.plus · duration.subsasgn · duration.subsref · hours · isduration · milliseconds · minutes · seconds · years
Source you can read
Every RunMat function's source is public. Read exactly how year is executed, line by line, in Rust.
- View the source for year in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.