UTIL_Date
Class · Group: Utilities
global inherited sharing class UTIL_DateProvides date and datetime helper operations such as business day arithmetic, weekday/weekend checks, ISO 8601 serialization, cron generation, and date formatting.
Example
Date nextBusinessDay = UTIL_Date.addBusinessDays(Date.today(), 5);
Boolean weekend = UTIL_Date.isWeekend(Date.today());
String cron = UTIL_Date.getCronExpression(Datetime.now().addHours(1));
String iso = UTIL_Date.toIso8601(Date.today());Methods
| Method | Description |
|---|---|
| global static Date addBusinessDays(Date origin, Integer workingDaysToAdd) | Advances or retreats a date by the given number of business days, skipping weekends. |
| global static Date dateFromIso8601(String isoText) | Parses an ISO 8601 string into a Date instance. |
| global static Datetime dateTimeFromIso8601(String isoText) | Parses an ISO 8601 string into a Datetime instance via JSON deserialization. |
| global static Date firstWeekDay(Date referenceDate) | Resolves the next weekday on or after the supplied date. |
| global static String formatDate(Date inputDate, String pattern) | Formats a Date according to a Java SimpleDateFormat pattern string. |
| global static String formatDuration(Long milliseconds) | Formats a duration in milliseconds to a human-readable string. |
| global static String getCronExpression(Datetime scheduledTime) | Builds a Salesforce-compatible cron expression from the supplied Datetime for use with System.schedule. |
| global static Boolean isWeekDay(Date inputDate) | Determines whether the supplied Date falls on a weekday (Monday through Friday). |
| global static Boolean isWeekDay(Datetime inputDatetime) | Determines whether the supplied Datetime falls on a weekday (Monday through Friday). |
| global static Boolean isWeekend(Date inputDate) | Determines whether the supplied Date falls on a Saturday or Sunday. |
| global static Boolean isWeekend(Datetime inputDatetime) | Determines whether the supplied Datetime falls on a Saturday or Sunday. |
| global static Date lastWeekDay() | Resolves the most recent weekday on or before today. |
| global static Date lastWeekDay(Date referenceDate) | Resolves the most recent weekday on or before the supplied date. |
| global static String toIso8601(Date inputDate) | Serializes a Date into its ISO 8601 string representation (date portion only). |
| global static String toIso8601(Datetime inputDatetime) | Serializes a Datetime into its ISO 8601 string representation, stripping surrounding quotes. |
addBusinessDays
global static Date addBusinessDays(Date origin, Integer workingDaysToAdd)Advances or retreats a date by the given number of business days, skipping weekends. Negative values move the date backwards.
Parameters
| Parameter | Type | Description |
|---|---|---|
origin | Date | The starting date. |
workingDaysToAdd | Integer | The number of business days to add (positive) or subtract (negative). |
Returns Date — The resulting date after traversing the specified business days.
Example
Date monday = Date.newInstance(2026, 2, 16);
Date result = UTIL_Date.addBusinessDays(monday, 5);dateFromIso8601
global static Date dateFromIso8601(String isoText)Parses an ISO 8601 string into a Date instance. When the string contains a time component, the local date is used; otherwise the GMT date is returned.
Parameters
| Parameter | Type | Description |
|---|---|---|
isoText | String | The ISO 8601 string to parse (e.g. 2026-02-18 or 2026-02-18T14:30:00.000Z). |
Returns Date — The parsed Date, or null when the input is blank.
Example
Date parsed = UTIL_Date.dateFromIso8601('2026-02-18');dateTimeFromIso8601
global static Datetime dateTimeFromIso8601(String isoText)Parses an ISO 8601 string into a Datetime instance via JSON deserialization.
Parameters
| Parameter | Type | Description |
|---|---|---|
isoText | String | The ISO 8601 string to parse (e.g. 2026-02-18T14:30:00.000Z). |
Returns Datetime — The parsed Datetime, or null when the input is blank.
Example
Datetime parsed = UTIL_Date.dateTimeFromIso8601('2026-02-18T14:30:00.000Z');firstWeekDay
global static Date firstWeekDay(Date referenceDate)Resolves the next weekday on or after the supplied date. If the date is already a weekday it is returned unchanged.
Parameters
| Parameter | Type | Description |
|---|---|---|
referenceDate | Date | The date to evaluate. |
Returns Date — The same date when it is a weekday, or the following Monday when it is a weekend.
Example
Date sunday = Date.newInstance(2026, 2, 22);
Date monday = UTIL_Date.firstWeekDay(sunday);formatDate
global static String formatDate(Date inputDate, String pattern)Formats a Date according to a Java SimpleDateFormat pattern string.
Parameters
| Parameter | Type | Description |
|---|---|---|
inputDate | Date | The date to format. |
pattern | String | The SimpleDateFormat pattern (e.g. yyyy-MM-dd, dd/MM/yyyy). |
Returns String — The formatted date string, or null when the input date is null.
Example
Date target = Date.newInstance(2026, 12, 25);
String formatted = UTIL_Date.formatDate(target, 'dd MMMM yyyy');formatDuration
global static String formatDuration(Long milliseconds)Formats a duration in milliseconds to a human-readable string. Returns compact labels: "500ms", "2.1s", "1m 30s", "1h 5m".
Parameters
| Parameter | Type | Description |
|---|---|---|
milliseconds | Long | The duration in milliseconds. Null returns null. |
Returns String — Formatted duration string, or null if input is null.
Example
String label = UTIL_Date.formatDuration(1500); // "1.5s"
String label = UTIL_Date.formatDuration(90000); // "1m 30s"
String label = UTIL_Date.formatDuration(500); // "500ms"getCronExpression
global static String getCronExpression(Datetime scheduledTime)Builds a Salesforce-compatible cron expression from the supplied Datetime for use with System.schedule.
Parameters
| Parameter | Type | Description |
|---|---|---|
scheduledTime | Datetime | The Datetime to convert into a cron string. |
Returns String — A cron expression such as 0 30 14 18 2 ? 2026, or null when the input is null.
Example
Datetime runAt = Datetime.newInstance(2026, 3, 1, 6, 0, 0);
String cron = UTIL_Date.getCronExpression(runAt);isWeekDay
global static Boolean isWeekDay(Date inputDate)Determines whether the supplied Date falls on a weekday (Monday through Friday).
Parameters
| Parameter | Type | Description |
|---|---|---|
inputDate | Date | The Date to inspect. |
Returns Boolean — true when the day is Monday through Friday; false for Saturday and Sunday.
Example
Date monday = Date.newInstance(2026, 2, 16);
Boolean weekday = UTIL_Date.isWeekDay(monday);global static Boolean isWeekDay(Datetime inputDatetime)Determines whether the supplied Datetime falls on a weekday (Monday through Friday).
Parameters
| Parameter | Type | Description |
|---|---|---|
inputDatetime | Datetime | The Datetime to inspect. |
Returns Boolean — true when the day is Monday through Friday; false for Saturday and Sunday.
Example
Datetime tuesday = Datetime.newInstance(2026, 2, 17, 12, 0, 0);
Boolean weekday = UTIL_Date.isWeekDay(tuesday);isWeekend
global static Boolean isWeekend(Date inputDate)Determines whether the supplied Date falls on a Saturday or Sunday.
Parameters
| Parameter | Type | Description |
|---|---|---|
inputDate | Date | The Date to inspect. |
Returns Boolean — true when the day is Saturday or Sunday; false for Monday through Friday.
Example
Date sunday = Date.newInstance(2026, 2, 22);
Boolean weekend = UTIL_Date.isWeekend(sunday);global static Boolean isWeekend(Datetime inputDatetime)Determines whether the supplied Datetime falls on a Saturday or Sunday.
Parameters
| Parameter | Type | Description |
|---|---|---|
inputDatetime | Datetime | The Datetime to inspect. |
Returns Boolean — true when the day is Saturday or Sunday; false for Monday through Friday.
Example
Datetime saturday = Datetime.newInstance(2026, 2, 21, 8, 0, 0);
Boolean weekend = UTIL_Date.isWeekend(saturday);lastWeekDay
global static Date lastWeekDay()Resolves the most recent weekday on or before today.
Returns Date — Today when it is a weekday, or the preceding Friday when today is a weekend.
Example
Date recentWeekday = UTIL_Date.lastWeekDay();global static Date lastWeekDay(Date referenceDate)Resolves the most recent weekday on or before the supplied date. If the date is already a weekday it is returned unchanged.
Parameters
| Parameter | Type | Description |
|---|---|---|
referenceDate | Date | The date to evaluate. |
Returns Date — The same date when it is a weekday, or the preceding Friday when it is a weekend.
Example
Date saturday = Date.newInstance(2026, 2, 21);
Date friday = UTIL_Date.lastWeekDay(saturday);toIso8601
global static String toIso8601(Date inputDate)Serializes a Date into its ISO 8601 string representation (date portion only).
Parameters
| Parameter | Type | Description |
|---|---|---|
inputDate | Date | The Date to serialize. When null, the epoch date is used. |
Returns String — An ISO 8601 date string such as 2026-02-18.
Example
Date invoiceDate = Date.newInstance(2026, 6, 1);
String iso = UTIL_Date.toIso8601(invoiceDate);global static String toIso8601(Datetime inputDatetime)Serializes a Datetime into its ISO 8601 string representation, stripping surrounding quotes.
Parameters
| Parameter | Type | Description |
|---|---|---|
inputDatetime | Datetime | The Datetime to serialize. When null, the epoch datetime is used. |
Returns String — An ISO 8601 formatted string such as 2026-02-18T10:00:00.000Z.
Example
Datetime scheduled = Datetime.newInstance(2026, 3, 15, 9, 0, 0);
String iso = UTIL_Date.toIso8601(scheduled);