> For the complete documentation index, see [llms.txt](https://boxlang.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boxlang.ortusbooks.com/boxlang-language/reference/types/datetime.md).
# datetime
The primary DateTime class that represents a date and time object in BoxLang
All temporal methods in BoxLang operate on this class and all castable date/time representations are cast to this class
## Datetime Methods
add(datepart=[string], number=[number])
Modifies a date object by date part and integer time unit
### Method Signature
```
add(datepart=[string], number=[number])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | -------------------------------- | ------- |
| `datepart` | `string` | `true` | The date part to modify | |
| `number` | `number` | `true` | The number of units to modify by | |
bxDump(label=[string], depth=[numeric], maxRows=[numeric], top=[numeric], expand=[boolean], abort=[boolean], output=[string], format=[string], showUDFs=[boolean])
Outputs the contents of a variable (simple or complex) of any type for debugging purposes to a specific output location.
The available `output` locations are: - **buffer**: The output is written to the buffer, which is the default location. If running on a web server, the output is written to the browser. - **console**: The output is printed to the System console. - **Absolute File Path** The output is written to a file with the specified absolute file path.
The output `format` can be either HTML or plain text.
The default format is HTML if the output location is the buffer or a web server or a file, otherwise it is plain text for the console.
### Method Signature
```
bxDump(label=[string], depth=[numeric], maxRows=[numeric], top=[numeric], expand=[boolean], abort=[boolean], output=[string], format=[string], showUDFs=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `label` | `string` | `false` | A custom label to display above the dump (Only in HTML output) | |
| `depth` | `numeric` | `false` | The recursion depth to display when dumping nested collections. 1-based: -1 (default) is unlimited, 0 shows nothing,
1 shows the top level with no recursion, 2 recurses once, etc. (Only in HTML output)
| |
| `maxRows` | `numeric` | `false` | The maximum number of keys/rows/items to display per level of a collection, array, or query. 1-based: -1 (default)
is unlimited, 0 shows nothing, 1 shows a single row, etc. (Only in HTML output)
| |
| `top` | `numeric` | `false` | Deprecated: use maxRows instead. When maxRows is not also passed, top's value is used as maxRows.
Kept for backwards compatibility with existing BoxLang code. (Only in HTML output)
| |
| `expand` | `boolean` | `false` | Whether to expand the dump. Be default, we try to expand as much as possible. (Only in HTML output) | `true` |
| `abort` | `boolean` | `false` | Whether to do a hard abort the request after dumping. Default is false | `false` |
| `output` | `string` | `false` | The output format which can be "buffer", "console", or "{absolute file path}". The default is "buffer". | |
| `format` | `string` | `false` | The format of the output to a **filename**. Can be "html" or "text". The default is according to the output location. | |
| `showUDFs` | `boolean` | `false` | Show UDFs or not. Default is true. (Only in HTML output) | `true` |
clone()
No description available
### Method Signature
```
clone()
```
### Arguments
This function does not accept any arguments
compare(date2=[any], datepart=[string])
Compares the difference between two dates - returning 0 if equal, -1 if date2 is less than date1 and 1 if the inverse
### Method Signature
```
compare(date2=[any], datepart=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------- | ------- |
| `date2` | `any` | `true` | The date which to compare against date1 | |
| `datepart` | `string` | `false` | The precision to compare down to. Accepts y, yyyy, m, d, h, n, s (default). | |
dateFormat(mask=[string], timezone=[string], locale=[string])
Formats a datetime, date or time
### Method Signature
```
dateFormat(mask=[string], timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `mask` | `string` | `false` | Optional format mask, or common mask. If an explicit mask is used, it should use the mask characters specified in the
java.time.format.DateTimeFormatter class.
If a common mask is used, the following are supported:
- short: equivalent to "M/d/y h:mm tt"
- medium: equivalent to "MMM d, yyyy h🇲🇲ss tt"
- long: medium followed by three-letter time zone; i.e. "MMMM d, yyyy h🇲🇲ss tt zzz"
- full: equivalent to "dddd, MMMM d, yyyy H🇲🇲ss tt zz"
- ISO8601/ISO: equivalent to "yyyy-MM-dd'T'HH🇲🇲ssXXX"
- epoch: Total seconds of a given date (Example:1567517664)
- epochms: Total milliseconds of a given date (Example:1567517664000)
| |
| `timezone` | `string` | `false` | Optional specific timezone to apply to the date ( if not present in the date string ) | |
| `locale` | `string` | `false` | Optional ISO locale string which will be used to localize the resulting date/time string | |
dateTimeFormat(mask=[string], timezone=[string], locale=[string])
Formats a datetime, date or time
### Method Signature
```
dateTimeFormat(mask=[string], timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `mask` | `string` | `false` | Optional format mask, or common mask. If an explicit mask is used, it should use the mask characters specified in the
java.time.format.DateTimeFormatter class.
If a common mask is used, the following are supported:
- short: equivalent to "M/d/y h:mm tt"
- medium: equivalent to "MMM d, yyyy h🇲🇲ss tt"
- long: medium followed by three-letter time zone; i.e. "MMMM d, yyyy h🇲🇲ss tt zzz"
- full: equivalent to "dddd, MMMM d, yyyy H🇲🇲ss tt zz"
- ISO8601/ISO: equivalent to "yyyy-MM-dd'T'HH🇲🇲ssXXX"
- epoch: Total seconds of a given date (Example:1567517664)
- epochms: Total milliseconds of a given date (Example:1567517664000)
| |
| `timezone` | `string` | `false` | Optional specific timezone to apply to the date ( if not present in the date string ) | |
| `locale` | `string` | `false` | Optional ISO locale string which will be used to localize the resulting date/time string | |
day(timezone=[string], locale=[string])
Returns the day of the month of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
day(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
dayOfWeek(timezone=[string], locale=[string])
Returns the numeric day of the week of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
dayOfWeek(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
dayOfWeekAsString(timezone=[string], locale=[string])
Returns the full day of the week name of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
dayOfWeekAsString(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
dayOfWeekShortAsString(timezone=[string], locale=[string])
Returns the short day of the week name of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
dayOfWeekShortAsString(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
dayOfYear(timezone=[string], locale=[string])
Returns the numeric day of the year of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
dayOfYear(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
daysInMonth(timezone=[string], locale=[string])
Returns the number of days in the month of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
daysInMonth(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
daysInYear(timezone=[string], locale=[string])
Return the number of days in the year of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
daysInYear(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
diff(datepart=[string], date2=[any])
Returns the numeric difference in the requested date part between two dates
### Method Signature
```
diff(datepart=[string], date2=[any])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | ----------------------------------------------------------------------------------------------- | ------- |
| `datepart` | `string` | `true` | The datepart code in which to express the difference (yyyy, q, m, d, y, w, ww, wd, h, n, s, l). | |
| `date2` | `any` | `true` | The date which to compare against date1 | |
duplicate(deep=[boolean])
Duplicates an object - either shallow or deep
### Method Signature
```
duplicate(deep=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | --------- | -------- | ------------------------------------------------------------------------------------------------- | ------- |
| `deep` | `boolean` | `false` | Whether to deep copy the object or make a shallow copy (e.g. only the top level keys in a struct) | `true` |
equals(obj=[any])
Indicates whether some other object is "equal to" this one.
### Method Signature
```
equals(obj=[any])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | ----- | -------- | ----------- | ------- |
| `obj` | `any` | `true` | | |
firstDayOfMonth(timezone=[string], locale=[string])
Returns the first date of the month of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
firstDayOfMonth(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
format(mask=[string], timezone=[string], locale=[string])
Formats a datetime, date or time
### Method Signature
```
format(mask=[string], timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `mask` | `string` | `false` | Optional format mask, or common mask. If an explicit mask is used, it should use the mask characters specified in the
java.time.format.DateTimeFormatter class.
If a common mask is used, the following are supported:
- short: equivalent to "M/d/y h:mm tt"
- medium: equivalent to "MMM d, yyyy h🇲🇲ss tt"
- long: medium followed by three-letter time zone; i.e. "MMMM d, yyyy h🇲🇲ss tt zzz"
- full: equivalent to "dddd, MMMM d, yyyy H🇲🇲ss tt zz"
- ISO8601/ISO: equivalent to "yyyy-MM-dd'T'HH🇲🇲ssXXX"
- epoch: Total seconds of a given date (Example:1567517664)
- epochms: Total milliseconds of a given date (Example:1567517664000)
| |
| `timezone` | `string` | `false` | Optional specific timezone to apply to the date ( if not present in the date string ) | |
| `locale` | `string` | `false` | Optional ISO locale string which will be used to localize the resulting date/time string | |
getnumericdate(timezone=[string], locale=[string])
Returns the numeric date in days from epoch of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
getnumericdate(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
getTime()
Returns the number of milliseconds since January 1, 1970, 00:00:00 GMT represented by this Date object.
### Method Signature
```
getTime()
```
### Arguments
This function does not accept any arguments
hash(algorithm=[string], encoding=[string], numIterations=[integer])
Creates an algorithmic hash of an object
### Method Signature
```
hash(algorithm=[string], encoding=[string], numIterations=[integer])
```
### Arguments
| Argument | Type | Required | Description | Default |
| --------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------- | ------- |
| `algorithm` | `string` | `false` | The supported `java.security.MessageDigest` algorithm (case-insensitive) or "quick" for an insecure 64-bit hash | `MD5` |
| `encoding` | `string` | `false` | Applicable to strings ( default "utf-8" ) | `utf-8` |
| `numIterations` | `integer` | `false` | The number of iterations to re-digest the object ( default 1 ); | `1` |
hour(timezone=[string], locale=[string])
Returns the hour of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
hour(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
len()
Returns the absolute value of a number
### Method Signature
```
len()
```
### Arguments
This function does not accept any arguments
millisecond(timezone=[string], locale=[string])
Returns the millisecond of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
millisecond(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
minute(timezone=[string], locale=[string])
Returns the minute of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
minute(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
month(timezone=[string], locale=[string])
Returns the numeric month of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
month(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
monthAsString(timezone=[string], locale=[string])
Returns the full month name of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
monthAsString(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
monthShortAsString(timezone=[string], locale=[string])
Returns the short month name of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
monthShortAsString(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
nanosecond(timezone=[string], locale=[string])
Returns the nanosecond of adate object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
nanosecond(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
offset(timezone=[string], locale=[string])
Returns the timezone offset of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
offset(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
quarter(timezone=[string], locale=[string])
Returns the quarter of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
quarter(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
second(timezone=[string], locale=[string])
Returns the second of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
second(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
setDay(value=[integer])
Sets a single date/time unit on a date object, mutating it in place and returning it.
Out-of-range values roll over (e.g. `setDay( 50 )` advances into following months) while zero/negative values clamp to the first valid unit (e.g. `setDay( 0 )` becomes day 1).
### Method Signature
```
setDay(value=[integer])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | --------- | -------- | --------------------------------------------- | ------- |
| `value` | `integer` | `true` | The value to set for the given date/time unit | |
setHour(value=[integer])
Sets a single date/time unit on a date object, mutating it in place and returning it.
Out-of-range values roll over (e.g. `setDay( 50 )` advances into following months) while zero/negative values clamp to the first valid unit (e.g. `setDay( 0 )` becomes day 1).
### Method Signature
```
setHour(value=[integer])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | --------- | -------- | --------------------------------------------- | ------- |
| `value` | `integer` | `true` | The value to set for the given date/time unit | |
setMinute(value=[integer])
Sets a single date/time unit on a date object, mutating it in place and returning it.
Out-of-range values roll over (e.g. `setDay( 50 )` advances into following months) while zero/negative values clamp to the first valid unit (e.g. `setDay( 0 )` becomes day 1).
### Method Signature
```
setMinute(value=[integer])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | --------- | -------- | --------------------------------------------- | ------- |
| `value` | `integer` | `true` | The value to set for the given date/time unit | |
setMonth(value=[integer])
Sets a single date/time unit on a date object, mutating it in place and returning it.
Out-of-range values roll over (e.g. `setDay( 50 )` advances into following months) while zero/negative values clamp to the first valid unit (e.g. `setDay( 0 )` becomes day 1).
### Method Signature
```
setMonth(value=[integer])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | --------- | -------- | --------------------------------------------- | ------- |
| `value` | `integer` | `true` | The value to set for the given date/time unit | |
setSecond(value=[integer])
Sets a single date/time unit on a date object, mutating it in place and returning it.
Out-of-range values roll over (e.g. `setDay( 50 )` advances into following months) while zero/negative values clamp to the first valid unit (e.g. `setDay( 0 )` becomes day 1).
### Method Signature
```
setSecond(value=[integer])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | --------- | -------- | --------------------------------------------- | ------- |
| `value` | `integer` | `true` | The value to set for the given date/time unit | |
setYear(value=[integer])
Sets a single date/time unit on a date object, mutating it in place and returning it.
Out-of-range values roll over (e.g. `setDay( 50 )` advances into following months) while zero/negative values clamp to the first valid unit (e.g. `setDay( 0 )` becomes day 1).
### Method Signature
```
setYear(value=[integer])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | --------- | -------- | --------------------------------------------- | ------- |
| `value` | `integer` | `true` | The value to set for the given date/time unit | |
timeFormat(mask=[string], timezone=[string], locale=[string])
Formats a datetime, date or time
### Method Signature
```
timeFormat(mask=[string], timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `mask` | `string` | `false` | Optional format mask, or common mask. If an explicit mask is used, it should use the mask characters specified in the
java.time.format.DateTimeFormatter class.
If a common mask is used, the following are supported:
- short: equivalent to "M/d/y h:mm tt"
- medium: equivalent to "MMM d, yyyy h🇲🇲ss tt"
- long: medium followed by three-letter time zone; i.e. "MMMM d, yyyy h🇲🇲ss tt zzz"
- full: equivalent to "dddd, MMMM d, yyyy H🇲🇲ss tt zz"
- ISO8601/ISO: equivalent to "yyyy-MM-dd'T'HH🇲🇲ssXXX"
- epoch: Total seconds of a given date (Example:1567517664)
- epochms: Total milliseconds of a given date (Example:1567517664000)
| |
| `timezone` | `string` | `false` | Optional specific timezone to apply to the date ( if not present in the date string ) | |
| `locale` | `string` | `false` | Optional ISO locale string which will be used to localize the resulting date/time string | |
timezone(timezone=[string], locale=[string])
Provides the BIF and member functions for all time unit request with no arguments
### Method Signature
```
timezone(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
toEpoch()
Returns this date time in epoch time ( seconds )
### Method Signature
```
toEpoch()
```
### Arguments
This function does not accept any arguments
toEpochMillis()
Returns this date time in epoch milliseconds
### Method Signature
```
toEpochMillis()
```
### Arguments
This function does not accept any arguments
toEpochSecond()
No description available
### Method Signature
```
toEpochSecond()
```
### Arguments
This function does not accept any arguments
toISOString()
Returns the date time representation as a string in the specified format mask
### Method Signature
```
toISOString()
```
### Arguments
This function does not accept any arguments
toODBCDate(timezone=[string])
Creates a DateTime object with the format set to ODBC Implicit format
### Method Signature
```
toODBCDate(timezone=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | ----------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone to apply | |
toODBCDateTime(timezone=[string])
Creates a DateTime object with the format set to ODBC Implicit format
### Method Signature
```
toODBCDateTime(timezone=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | ----------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone to apply | |
toODBCTime(timezone=[string])
Creates a DateTime object with the format set to ODBC Implicit format
### Method Signature
```
toODBCTime(timezone=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | ----------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone to apply | |
week(timezone=[string], locale=[string])
Returns the numeric week within a year of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
week(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
year(timezone=[string], locale=[string])
Returns the year of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
year(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://boxlang.ortusbooks.com/boxlang-language/reference/types/datetime.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.