Boxlang 1.x Stable Released
BoxLang : A Modern Dynamic JVM Language
LogoLogo
APIDocsDownloadTrySourceSupport
  • Introduction
    • Contributing Guide
    • Release History
      • 1.2.0
      • 1.1.0
      • 1.0.1
      • 1.0.0
      • RC Stage
        • 1.0.0-RC.1
        • 1.0.0-RC.2
        • 1.0.0-RC.3
      • Beta Stage
        • 1.0.0-Beta27
        • 1.0.0-Beta26
        • 1.0.0-Beta25
        • 1.0.0-Beta24
        • 1.0.0-Beta23
        • 1.0.0-Beta22
        • 1.0.0-Beta21
        • 1.0.0-Beta20
        • 1.0.0-Beta19
        • 1.0.0-Beta18
        • 1.0.0-Beta17
        • 1.0.0-Beta16
        • 1.0.0-Beta15
        • 1.0.0-Beta14
        • 1.0.0-Beta13
        • 1.0.0-Beta12
        • 1.0.0-Beta11
        • 1.0.0-Beta10
        • 1.0.0-Beta9
        • 1.0.0-Beta8
        • 1.0.0-Beta7
        • 1.0.0-Beta6
        • 1.0.0-Beta5
        • 1.0.0-Beta 4
        • 1.0.0-Beta3
        • 1.0.0-Beta2
    • About This Book
      • Authors
  • Getting Started
    • Overview
      • Multi-Runtime
      • Instructions & Interpreters
      • CommandBox CLI
      • Quick Syntax Guide
        • Differences From CFML
      • Frequently Asked Questions
      • Running ColdFusion/CFML Apps
        • Migrating from Adobe ColdFusion
        • Migrating From Lucee CFML
    • Installation
      • Modules
    • Running BoxLang
      • AWS Lambda
      • CommandBox
      • Chromebooks
      • CLI Scripting
      • Docker
      • GitHub Actions
      • JSR-223 Scripting
      • MiniServer
      • Try BoxLang!
    • BoxLang Cloud Servers
      • Microsoft Azure
      • Amazon Web Services
    • IDE & Tooling
      • BoxLang Debugger
        • MiniServer Debugging
        • CommandBox Debugging
      • BoxLang Compiler
      • CFML Feature Audit
      • CFML to BoxLang Transpiler
    • Runtime Configuration
      • Directives
      • Caches
      • Datasources
      • Experimental
      • Executors
      • Logging
      • Modules
      • Security
  • BoxLang Language
    • Program Structure
    • Syntax & Semantics
      • Comments
      • Variables
      • Variable Scopes
      • Operators
      • Null & Nothingness
      • Strings
      • Numbers
      • Dates & Times
      • JSON
      • Arrays
      • Structures
      • Queries
      • Datasources
      • Conditionals
      • Attempts
      • Data Navigators
      • Exception Management
      • Code Locking
      • Closures => Context Aware
      • Lambdas -> Pure Functions
      • Includes
      • Threading
    • Classes & O.O.
      • Properties
      • Functions
      • Static Constructs
      • Final Constructs
      • Abstract Constructs
      • Interfaces
    • Reference
      • API Docs
      • Lexical Elements
        • Scopes and Constants
        • Keywords
        • Operators
        • Literals
        • Comments
        • Tokens
        • Semicolons
        • Identifiers
        • Packages and Imports
        • Java Interoperability
        • Errors
      • Types
        • array
        • class
        • datetime
        • file
        • numeric
        • query
        • stream
        • string
        • struct
        • xml
      • Built-in Functions
        • array
          • ArrayAppend
          • ArrayAvg
          • ArrayClear
          • ArrayContains
          • ArrayContainsNoCase
          • ArrayDelete
          • ArrayDeleteAt
          • ArrayDeleteNoCase
          • ArrayEach
          • ArrayEvery
          • ArrayFilter
          • ArrayFind
          • ArrayFindAll
          • ArrayFindAllNoCase
          • ArrayFindNoCase
          • ArrayFirst
          • ArrayGetMetadata
          • ArrayIndexExists
          • ArrayInsertAt
          • ArrayIsDefined
          • ArrayLast
          • ArrayMap
          • ArrayMax
          • ArrayMedian
          • ArrayMerge
          • ArrayMid
          • ArrayMin
          • ArrayNew
          • ArrayPop
          • ArrayPrepend
          • ArrayPush
          • ArrayRange
          • ArrayReduce
          • ArrayReduceRight
          • ArrayResize
          • ArrayReverse
          • ArraySet
          • ArrayShift
          • ArraySlice
          • ArraySome
          • ArraySort
          • ArraySplice
          • ArraySum
          • ArraySwap
          • ArrayToList
          • ArrayToStruct
          • ArrayUnshift
        • async
          • ExecutorGet
          • ExecutorHas
          • ExecutorList
          • ExecutorNew
          • ExecutorShutdown
          • ExecutorStatus
          • FutureNew
          • IsInThread
          • isThreadAlive
          • IsThreadInterrupted
          • RunAsync
          • ThreadInterrupt
          • ThreadJoin
          • ThreadNew
          • ThreadTerminate
        • binary
          • BinaryDecode
          • BinaryEncode
          • BitAnd
          • BitMaskClear
          • BitMaskRead
          • BitMaskSet
          • BitNot
          • BitOr
          • bitShln
          • bitShrn
          • BitXor
        • cache
          • Cache
          • CacheFilter
          • CacheNames
          • CacheProviders
          • CacheService
        • cli
          • CLIClear
          • CLIExit
          • CLIGetArgs
          • CLIRead
        • conversion
          • DataNavigate
          • JSONDeserialize
          • JSONPrettify
          • JSONSerialize
          • LSParseNumber
          • ParseNumber
          • ToBase64
          • ToBinary
          • ToModifiable
          • ToNumeric
          • ToScript
          • ToString
          • ToUnmodifiable
        • decision
          • ArrayIsEmpty
          • arrayIsEmpty
          • Attempt
          • IsArray
          • IsBinary
          • IsBoolean
          • IsClosure
          • IsCustomFunction
          • IsDate
          • IsDateObject
          • IsDebugMode
          • IsDefined
          • IsEmpty
          • IsFileObject
          • IsIPv6
          • IsJSON
          • IsLeapYear
          • IsLocalHost
          • IsNull
          • IsNumeric
          • IsNumericDate
          • IsObject
          • IsQuery
          • IsSimpleValue
          • IsStruct
          • IsValid
          • IsXML
          • IsXmlAttribute
          • IsXMLDoc
          • IsXMLElem
          • IsXMLNode
          • IsXMLRoot
          • LSIsNumeric
          • structIsEmpty
        • encryption
          • Decrypt
          • DecryptBinary
          • Encrypt
          • EncryptBinary
          • GeneratePBKDFKey
          • GenerateSecretKey
          • Hash
          • Hash40
          • Hmac
        • format
          • BooleanFormat
          • DecimalFormat
          • LSNumberFormat
          • NumberFormat
        • i18n
          • ClearLocale
          • CurrencyFormat
          • GetLocale
          • GetLocaleDisplayName
          • GetLocaleInfo
          • IsCurrency
          • LSCurrencyFormat
          • LSIsCurrency
          • LSParseCurrency
          • ParseCurrency
          • SetLocale
        • io
          • ContractPath
          • CreateTempDirectory
          • CreateTempFile
          • DirectoryCopy
          • DirectoryCreate
          • DirectoryDelete
          • DirectoryExists
          • DirectoryList
          • DirectoryMove
          • DirectoryRename
          • ExpandPath
          • FileAppend
          • FileClose
          • FileCopy
          • FileDelete
          • FileExists
          • FileGetMimeType
          • FileInfo
          • FileIsEOF
          • FileMove
          • FileOpen
          • FileRead
          • FileReadBinary
          • FileReadLine
          • FileSeek
          • FileSetAccessMode
          • FileSetAttribute
          • FileSetLastModified
          • FileSkipBytes
          • FileWrite
          • FileWriteLine
          • GetCanonicalPath
          • GetDirectoryFromPath
          • GetFileInfo
          • getTempFile
        • java
          • CreateDynamicProxy
        • jdbc
          • IsInTransaction
          • IsWithinTransaction
          • PreserveSingleQuotes
          • QueryExecute
          • TransactionCommit
          • TransactionRollback
          • TransactionSetSavepoint
        • list
          • GetToken
          • ListAppend
          • ListAvg
          • ListChangeDelims
          • ListCompact
          • ListContains
          • ListContainsNoCase
          • ListDeleteAt
          • ListEach
          • ListEvery
          • ListFilter
          • ListFind
          • ListFindNoCase
          • ListFirst
          • ListGetAt
          • ListIndexExists
          • ListInsertAt
          • ListItemTrim
          • ListLast
          • ListLen
          • ListMap
          • ListPrepend
          • ListQualify
          • ListReduceRight
          • ListRemoveDuplicates
          • ListRest
          • ListSetAt
          • ListSome
          • ListSort
          • ListToArray
          • ListTrim
          • ListValueCount
          • ListValueCountNoCase
        • math
          • Abs
          • Acos
          • Asin
          • Atn
          • Ceiling
          • Cos
          • DecrementValue
          • Exp
          • Fix
          • Floor
          • FormatBaseN
          • IncrementValue
          • InputBaseN
          • Int
          • Log
          • Log10
          • Max
          • Min
          • Pi
          • PrecisionEvaluate
          • Rand
          • Randomize
          • RandRange
          • Round
          • Sgn
          • Sin
          • Sqr
          • Tan
        • query
          • QueryAddColumn
          • QueryAddRow
          • QueryAppend
          • QueryClear
          • QueryColumnArray
          • QueryColumnCount
          • QueryColumnData
          • QueryColumnExists
          • QueryColumnList
          • QueryCurrentRow
          • QueryDeleteColumn
          • QueryDeleteRow
          • QueryEach
          • QueryEvery
          • QueryFilter
          • QueryGetCell
          • QueryGetResult
          • QueryInsertAt
          • QueryKeyExists
          • QueryMap
          • QueryNew
          • QueryPrepend
          • QueryRecordCount
          • QueryReduce
          • QueryRegisterFunction
          • QueryReverse
          • QueryRowData
          • QueryRowSwap
          • QuerySetCell
          • QuerySetRow
          • QuerySlice
          • QuerySome
          • QuerySort
        • runtime
          • BoxLangBIFProxy
        • scheduler
          • SchedulerGet
          • SchedulerGetAll
          • SchedulerList
          • SchedulerRestart
          • SchedulerShutdown
          • SchedulerStart
          • SchedulerStats
        • string
          • Ascii
          • CamelCase
          • Char
          • CharsetDecode
          • CharsetEncode
          • Compare
          • CompareNoCase
          • Find
          • FindNoCase
          • FindOneOf
          • Insert
          • JSStringFormat
          • KebabCase
          • LCase
          • Left
          • ListReduce
          • LJustify
          • LTrim
          • Mid
          • ParagraphFormat
          • PascalCase
          • QueryStringToStruct
          • ReEscape
          • ReFind
          • reFindNoCase
          • ReMatch
          • reMatchNoCase
          • RemoveChars
          • RepeatString
          • Replace
          • ReplaceList
          • ReplaceListNoCase
          • ReplaceNoCase
          • ReReplace
          • reReplaceNoCase
          • Reverse
          • Right
          • RJustify
          • RTrim
          • Slugify
          • SnakeCase
          • SpanExcluding
          • SpanIncluding
          • SQLPrettify
          • StringBind
          • StringEach
          • StringEvery
          • StringFilter
          • StringMap
          • StringReduce
          • StringReduceRight
          • StringSome
          • StringSort
          • StripCR
          • Trim
          • TrueFalseFormat
          • UCase
          • UCFirst
          • Val
          • Wrap
          • YesNoFormat
        • struct
          • StructAppend
          • StructClear
          • StructCopy
          • StructDelete
          • StructEach
          • StructEquals
          • StructEvery
          • StructFilter
          • StructFind
          • StructFindKey
          • StructFindValue
          • StructGet
          • StructGetMetadata
          • StructInsert
          • StructIsCaseSensitive
          • StructIsOrdered
          • StructKeyArray
          • StructKeyExists
          • StructKeyList
          • StructKeyTranslate
          • StructMap
          • StructNew
          • StructReduce
          • StructSome
          • StructSort
          • StructToQueryString
          • StructToSorted
          • StructUpdate
          • StructValueArray
        • system
          • ApplicationRestart
          • ApplicationStartTime
          • ApplicationStop
          • BoxAnnounce
          • BoxAnnounceAsync
          • BoxModuleReload
          • BoxRegisterInterceptionPoints
          • BoxRegisterInterceptor
          • BoxRegisterRequestInterceptor
          • BoxUnregisterInterceptor
          • BoxUnregisterRequestInterceptor
          • CallStackGet
          • CreateGUID
          • CreateObject
          • CreateUUID
          • DE
          • DebugBoxContexts
          • Dump
          • Duplicate
          • echo
          • EncodeForHTML
          • GetApplicationMetadata
          • GetBaseTagData
          • GetBaseTagList
          • GetBaseTemplatePath
          • GetBoxContext
          • GetBoxRuntime
          • GetBoxVersionInfo
          • GetClassMetadata
          • GetComponentList
          • GetContextRoot
          • GetCurrentTemplatePath
          • GetFileFromPath
          • GetFunctionCalledName
          • GetFunctionList
          • GetModuleInfo
          • GetModuleList
          • GetRequestClassLoader
          • GetSemver
          • GetSystemSetting
          • GetTempDirectory
          • GetTickCount
          • htmlEditFormat
          • IIF
          • Invoke
          • IsInstanceOf
          • JavaCast
          • ObjectDeserialize
          • ObjectSerialize
          • PagePoolClear
          • Print
          • Println
          • RunThreadInContext
          • SessionInvalidate
          • SessionRotate
          • SessionStartTime
          • Sleep
          • SystemCacheClear
          • SystemExecute
          • SystemOutput
          • Throw
          • Trace
          • URLDecode
          • URLEncodedFormat
          • writeDump
          • WriteLog
          • WriteOutput
        • temporal
          • ClearTimezone
          • CreateDate
          • CreateDateTime
          • CreateODBCDate
          • CreateODBCDateTime
          • CreateODBCTime
          • CreateTime
          • CreateTimeSpan
          • DateAdd
          • DateCompare
          • DateConvert
          • DateDiff
          • DateFormat
          • DatePart
          • DateTimeFormat
          • Day
          • DayOfWeek
          • DayOfWeekAsString
          • DayOfWeekShortAsString
          • DayOfYear
          • DaysInMonth
          • DaysInYear
          • FirstDayOfMonth
          • GetNumericDate
          • GetTime
          • GetTimezone
          • GetTimezoneInfo
          • Hour
          • Millisecond
          • Minute
          • Month
          • MonthAsString
          • MonthShortAsString
          • Nanosecond
          • Now
          • Offset
          • ParseDateTime
          • Quarter
          • Second
          • SetTimezone
          • TimeFormat
          • Week
          • Year
        • type
          • ArrayLen
          • GetMetaData
          • Len
          • NullValue
          • StringLen
          • StructCount
        • xml
          • XMLChildPos
          • XMLElemNew
          • XMLFormat
          • XMLGetNodeType
          • XMLNew
          • XMLParse
          • XMLSearch
          • XMLTransform
          • XMLValidate
        • zip
          • Compress
          • Extract
          • IsZipFile
      • Components
        • async
          • Thread
        • cache
          • Cache
        • debug
          • Timer
        • io
          • Directory
          • File
        • jdbc
          • ProcParam
          • StoredProc
          • DBInfo
          • ProcResult
          • Query
          • QueryParam
          • Transaction
        • net
          • HTTPParam
          • HTTP
        • system
          • Throw
          • InvokeArgument
          • Application
          • Invoke
          • Abort
          • Include
          • Component
          • Execute
          • Flush
          • SaveContent
          • Output
          • Log
          • Sleep
          • Setting
          • Param
          • Lock
          • Associate
          • Silent
          • ProcessingDirective
          • Trace
          • Exit
          • Dump
          • Loop
        • xml
          • XML
        • zip
          • Zip
      • Exceptions
  • BoxLang Framework
    • Application.bx
    • Asynchronous Programming
    • Caching
      • Cache Service
      • BoxCache Provider
      • Custom Cache Providers
      • Custom Object Stores
      • Custom Eviction Policies
    • File Handling
    • Interceptors
      • Core Interception Points
        • Application Events
        • Cache Service Events
        • Cache Provider Events
        • Cache Object Store Events
        • Datasource Service Events
        • Dump Events
        • Dynamic Object Events
        • Function Invocations
        • HTTP Events
        • Life-cycle Events
        • Logging Events
        • Module Events
        • Module Service Events
        • Object Marshalling Events
        • Query Invocations
        • Runtime Events
        • Request Context Events
        • Scheduler Events
        • Scheduler Service Events
        • Template Invocations
        • Transaction Events
      • Request Interception Points
    • HTTP/S Calls
    • Java Interop
    • JDBC Transactions
    • Modules
      • AI
      • Compat CFML
        • Reference
          • Types
            • array
            • datetime
            • numeric
            • string
            • struct
          • Built-in Functions
            • cache
              • CacheCount
              • CacheGetAsAttempt
              • CacheRegionRemove
              • CacheRemoveAll
              • CachePut
              • CacheRegionExists
              • CacheGetSession
              • CacheGetEngineProperties
              • CacheGet
              • CacheGetDefaultCacheName
              • CacheGetProperties
              • CacheSetProperties
              • CacheGetAllIds
              • CacheIdExists
              • cacheKeyExists
              • CacheRemove
              • cacheDelete
              • CacheGetAll
              • CacheGetMetadata
              • CacheGetOrFail
              • CacheClear
              • CacheRegionNew
            • conversion
              • JSONDeserialize
            • encryption
              • Hash
              • Hash40
            • format
              • HTMLCodeFormat
              • DollarFormat
            • struct
              • DeleteClientVariable
            • system
              • Throw
              • ObjectSave
              • GetFunctionData
              • GetComponentMetadata
              • GetVariable
              • GetTagData
              • GetClientVariablesList
              • GetContextRoot
              • ObjectLoad
              • SetVariable
            • temporal
              • LSWeek
              • LSDayOfWeek
              • LSIsDate
              • DateCompare
              • GetHTTPTimestring
              • LSDateTimeFormat
              • LSDateFormat
              • LSTimeFormat
              • DayOfWeekAsString
              • DayOfWeekShortAsString
              • MonthAsString
              • MonthShortAsString
              • ToLegacyDate
              • createDate
              • LSParseDateTime
              • DateTimeFormat
              • DateFormat
              • TimeFormat
            • type
              • GetMetaData
          • Components
            • net
              • HTTP
      • CSRF
      • ESAPI
      • Evaluating Code
      • FTP
      • Image Manipulation
      • INI Files
      • JDBC
      • Jython
      • Mail
      • Markdown
      • ORM
      • OSHI - Operating System + Hardware
      • Password Encryption
      • PDF
      • Redis
      • UI Forms
      • WDDX
      • Web Support
      • Yaml
  • Extra Credit
    • MVC
    • Dependency Injection
Powered by GitBook
LogoLogo

Social Media

  • X
  • FaceBook
  • LinkedIn
  • YouTube

Bug Tracking

  • Runtimes
  • IDE
  • Modules

Support

  • Professional
  • Community
  • Slack

Copyright & Register Trademark by Ortus Solutions, Corp

On this page
  • Working with Dates in BoxLang
  • The DateTime Object
  • Creating DateTime Objects
  • Date Time Format Masks
  • Basic Date and Time Components
  • Time Components
  • Week Components
  • Predefined Full Date/Time Formats
  • Formatting Dates
  • Using Built-in Functions
  • Timezone Support
  • Working with Timezones
  • Request-Level Timezone Management
  • Formatting with Timezones
  • Supported Timezone Formats
  • DateTime Member Methods
  • Comparison and Equality Methods
  • Cloning and Copying
  • Conversion and Output Methods
  • Date/Time Component Access
  • Date Manipulation Methods
  • Timezone Operations
  • Formatting Methods
  • Advanced Member Method Usage
  • Working with Temporal Units
  • Range and Validation
  • Date Arithmetic and Mathematical Operations
  • Addition and Subtraction
  • Multiplication and Division
  • Using DateAdd for Precision
  • Date Comparison and Differences
  • Extracting Date Parts
  • Utility Functions
  • Validation and Information
  • Creating Time Spans
  • Common Patterns and Examples
  • Performance Considerations

Was this helpful?

Edit on GitHub
Export as PDF
  1. BoxLang Language
  2. Syntax & Semantics

Dates & Times

The power of now!

Working with Dates in BoxLang

BoxLang provides comprehensive date and time functionality through its DateTime object and extensive collection of temporal Built-in Functions (BIFs). All date and time operations in BoxLang work with the unified DateTime type, which internally wraps Java's ZonedDateTime to provide robust timezone and formatting support.

The DateTime Object

The DateTime object is the cornerstone of all temporal operations in BoxLang. It represents a specific moment in time with timezone information and provides methods for formatting, manipulation, and comparison. DateTime objects are created using BoxLang's temporal BIFs and provide member methods for advanced operations.

Creating DateTime Objects

BoxLang provides several Built-in Functions (BIFs) for creating DateTime objects:

Current Date and Time

// Get current date and time in system timezone
now = now()

From String Representations

// Parse from various string formats
dt = parseDateTime("December 25, 2023")
dt = parseDateTime("2023-12-25T15:30:00Z")
dt = parseDateTime("25-Dec-2023 3:30 PM")

// Parse with specific locale and timezone
dt = parseDateTime("25/12/2023", "en_US", "America/New_York")

From Numeric Components

// Create specific date (year, month, day)
dt = createDate(2023, 12, 25)

// Create date with time (year, month, day, hour, minute, second)
dt = createDateTime(2023, 12, 25, 15, 30, 45)

// Create time only (hour, minute, second)
timeObj = createTime(15, 30, 45)

Creating Time Spans

// Create timespan for durations (days, hours, minutes, seconds)
span = createTimeSpan(1, 2, 30, 45)  // 1 day, 2 hours, 30 min, 45 sec

Date Time Format Masks

BoxLang supports extensive formatting options through format masks:

Basic Date and Time Components

Mask
Description
Example

d

Day of month, no leading zero

5, 25

dd

Day of month, leading zero

05, 25

EEE

Day of week, three-letter abbreviation

Mon, Tue

EEEE

Day of week, full name

Monday, Tuesday

m

Month, no leading zero

1, 12

mm

Month, leading zero

01, 12

mmm

Month, three-letter abbreviation

Jan, Dec

mmmm

Month, full name

January, December

M

Month in year

1, 12

D

Day in year

1, 365

yy

Year, last two digits

23

yyyy

Year, four digits

2023

YYYY

Week year, four digits

2023

Y

Week year

2023

YY

Week year, last two digits

23

G

Period/era string

BC, AD

Time Components

Mask
Description
Example

h

Hours (12-hour), no leading zero

3, 11

hh

Hours (12-hour), leading zero

03, 11

H

Hours (24-hour), no leading zero

15, 23

HH

Hours (24-hour), leading zero

15, 23

n

Minutes, no leading zero

5, 30

nn

Minutes, leading zero

05, 30

s

Seconds, no leading zero

5, 45

ss

Seconds, leading zero

05, 45

l or L

Milliseconds, no leading zeros

123

t

One-character time marker

A, P

tt

Time marker string

AM, PM

Week Components

Mask
Description
Example

w

Week of year, single digit

1, 52

ww

Week of year, leading zero

01, 52

W

Week of month, single digit

1, 5

WW

Week of month, leading zero

01, 05

Predefined Full Date/Time Formats

These masks format the complete date and time and cannot be combined with other masks:

Mask
Equivalent Format
Example

short

"m/d/y h:nn tt"

12/25/23 3:30 PM

medium

"mmm d, yyyy h:nn:ss tt"

Dec 25, 2023 3:30:45 PM

long

Medium with full month and timezone

December 25, 2023 3:30:45 PM EST

full

"EEEE, mmmm d, yyyy h:mm:ss tt EST"

Monday, December 25, 2023 3:30:45 PM EST

iso

ISO8601 format

2023-12-25T15:30:45-05:00

Formatting Dates

Using Built-in Functions

dt = now()

// Combined date and time formatting
formatted = dateTimeFormat(dt, "yyyy-mm-dd HH:nn:ss")
formatted = dateTimeFormat(dt, "medium")  // Dec 25, 2023 3:30:45 PM
formatted = dateTimeFormat(dt, "iso")     // 2023-12-25T15:30:45-05:00

// Date only formatting
dateString = dateFormat(dt, "mm/dd/yyyy")
dateString = dateFormat(dt, "mmmm d, yyyy")  // December 25, 2023

// Time only formatting  
timeString = timeFormat(dt, "HH:nn:ss")
timeString = timeFormat(dt, "h:nn tt")       // 3:30 PM

// With timezone specification
formatted = dateTimeFormat(dt, "yyyy-mm-dd HH:nn:ss", "UTC")
formatted = dateTimeFormat(dt, "medium", "America/New_York")

Timezone Support

BoxLang supports timezone specification using:

  • 3-letter codes: "EST", "UTC", "PST"

  • Full timezone names: "America/New_York", "Europe/London", "Asia/Tokyo"

dt = now()

// Format with specific timezone
utcFormatted = dateTimeFormat(dt, "yyyy-mm-dd HH:nn:ss", "UTC")
nyFormatted = dateTimeFormat(dt, "full", "America/New_York")

Working with Timezones

BoxLang provides timezone support at two levels: request-level and formatting-level.

Request-Level Timezone Management

These BIFs set the timezone for the current request only. If not set, BoxLang uses the runtime configuration timezone.

// Set timezone for current request
setTimezone("America/New_York")
setTimezone("EST")

// Get current request timezone
currentTZ = getTimezone()

// Clear request timezone (reverts to runtime default)
clearTimezone()

// Get timezone information
info = getTimezoneInfo()

Formatting with Timezones

When formatting dates, you can specify a timezone without affecting the request timezone:

dt = now()

// Format with specific timezone (doesn't change request timezone)
utcFormatted = dateTimeFormat(dt, "yyyy-mm-dd HH:nn:ss", "UTC")
nyFormatted = dateTimeFormat(dt, "full", "America/New_York")

// Convert between timezones for calculations
utcTime = dateConvert("local2utc", dt)
localTime = dateConvert("utc2local", utcTime)

// Get timezone offset using member methods
offsetObj = dt.getOffset()           // ZoneOffset object
offsetHours = offset(dt)             // Offset in hours (using BIF)

Supported Timezone Formats

  • 3-letter codes: "EST", "UTC", "PST", "CST"

  • Full timezone names: "America/New_York", "Europe/London", "Asia/Tokyo"

DateTime Member Methods

DateTime objects provide numerous member methods for manipulation, formatting, and information retrieval. These methods can be called directly on DateTime instances using dot notation.

Comparison and Equality Methods

dt1 = createDate(2023, 12, 25)
dt2 = createDate(2023, 12, 30)

// Equality comparison
isEqual = dt1.equals(dt2)          // false

// Temporal comparisons  
isAfter = dt2.isAfter(dt1)         // true
isBefore = dt1.isBefore(dt2)       // true
isEqualTime = dt1.isEqual(dt2)     // false

Cloning and Copying

dt = now()

// Clone with same timezone
dtCopy = dt.clone()

// Clone with different timezone
dtUTC = dt.clone("UTC")
dtNY = dt.clone("America/New_York")

Conversion and Output Methods

dt = now()

// Convert to various formats
isoString = dt.toISOString()         // "2023-12-25T15:30:45-05:00"
epochSeconds = dt.toEpoch()          // 1703534245
epochMillis = dt.toEpochMillis()     // 1703534245123
timeMillis = dt.getTime()            // 1703534245123 (same as toEpochMillis)
epochSecs = dt.toEpochSecond()       // 1703534245 (same as toEpoch)

// Convert to Java types
javaInstant = dt.toInstant()
javaLocalDate = dt.toLocalDate()
javaLocalTime = dt.toLocalTime()
javaDate = dt.toDate()               // java.util.Date
javaZonedDateTime = dt.getWrapped()  // Access underlying ZonedDateTime

Date/Time Component Access

dt = now()

// Date components
year = dt.getYear()                  // 2023
month = dt.getMonthValue()           // 12 (1-12)
day = dt.getDayOfMonth()             // 25
dayOfWeek = dt.getDayOfWeek()        // MONDAY (enum)
dayOfYear = dt.getDayOfYear()        // 359

// Time components  
hour = dt.getHour()                  // 15 (24-hour format)
minute = dt.getMinute()              // 30
second = dt.getSecond()              // 45
nano = dt.getNano()                  // 123000000 (nanoseconds)

// Timezone information
zone = dt.getZone()                  // ZoneId object
offset = dt.getOffset()              // ZoneOffset object

Date Manipulation Methods

dt = createDate(2023, 12, 25)

// Add/subtract time units
futureDate = dt.plusDays(5)          // Add 5 days
pastDate = dt.minusDays(10)          // Subtract 10 days
nextMonth = dt.plusMonths(1)         // Add 1 month
nextYear = dt.plusYears(1)           // Add 1 year

// Time additions
laterTime = dt.plusHours(3)          // Add 3 hours
earlierTime = dt.minusMinutes(30)    // Subtract 30 minutes
futureTime = dt.plusSeconds(45)      // Add 45 seconds

// Set specific components
newYear = dt.withYear(2024)          // Change year to 2024
newMonth = dt.withMonth(6)           // Change month to June
newDay = dt.withDayOfMonth(15)       // Change day to 15th
newHour = dt.withHour(9)             // Change hour to 9 AM

// Using modify method (similar to dateAdd BIF)
modified = dt.modify("d", 5)         // Add 5 days
modified = dt.modify("h", -3)        // Subtract 3 hours
modified = dt.modify("m", 2)         // Add 2 months
modified = dt.modify("yyyy", 1)      // Add 1 year

Timezone Operations

dt = now()

// Convert to different timezone
utcTime = dt.convertToZone("UTC")
nyTime = dt.convertToZone("America/New_York")

// Set timezone (changes zone, keeps local time)
withTZ = dt.setTimezone("Europe/London")

// Check if leap year
isLeap = dt.isLeapYear()             // true/false

Formatting Methods

dt = now()

// Custom formatting
formatted = dt.format("yyyy-mm-dd HH:nn:ss")
localized = dt.format("medium")

// Set default format for the DateTime object
dt.setFormat("yyyy-mm-dd HH:nn:ss")
defaultFormatted = dt.toString()     // Uses the set format

// With specific locale
import java.util.Locale
spanishFormat = dt.format(Locale.of("es", "ES"), "EEEE, mmmm d, yyyy")

Advanced Member Method Usage

dt = createDateTime(2023, 12, 25, 15, 30, 45)

// Chain operations
result = dt.plusDays(5)
           .withHour(9)
           .withMinute(0)
           .withSecond(0)

// Get first day of month
firstDay = dt.withDayOfMonth(1)

// Get last day of month  
lastDay = dt.withDayOfMonth(dt.getMonth().length(dt.isLeapYear()))

// Beginning of day
startOfDay = dt.withHour(0).withMinute(0).withSecond(0).withNano(0)

// End of day
endOfDay = dt.withHour(23).withMinute(59).withSecond(59).withNano(999999999)

Working with Temporal Units

dt1 = createDate(2023, 1, 1)
dt2 = createDate(2023, 12, 31)

// Calculate differences using member methods
daysBetween = dt1.until(dt2, ChronoUnit.DAYS)      // 364
monthsBetween = dt1.until(dt2, ChronoUnit.MONTHS)  // 11

Range and Validation

dt = now()

// Check if date supports certain operations
supportsNanos = dt.isSupported(ChronoField.NANO_OF_SECOND)  // true
supportsDay = dt.isSupported(ChronoUnit.DAYS)               // true

// Get valid range for a field
yearRange = dt.range(ChronoField.YEAR)          // ValueRange object
monthRange = dt.range(ChronoField.MONTH_OF_YEAR) // 1-12

These member methods provide direct access to the rich functionality of BoxLang's DateTime objects, allowing for fluent and expressive date manipulation code. Most operations return new DateTime instances, supporting method chaining for complex transformations.

Date Arithmetic and Mathematical Operations

timeNow = now();
// Addition casts the date to a numeric day value 
// ( example: 20241.89415408551756893278841047638 )
originalEpochDays = timeNow + 0;
// Add 2.5 days to the decimal days value
updatedEpochDays = timeNow + 2.5;

Addition and Subtraction

dt1 = createDate(2023, 12, 25)
dt2 = createDate(2023, 12, 30)

// Subtract dates to get difference in days
daysDiff = dt2 - dt1  // Returns 5.0

// Add days to a date
futureDate = dt1 + 10  // Adds 10 days

// Add fractional days (hours, minutes)
halfDay = dt1 + 0.5    // Adds 12 hours
quarterDay = dt1 + 0.25 // Adds 6 hours

Multiplication and Division

dt = createDate(2023, 1, 1)
timespan = createTimeSpan(5, 12, 30, 0) // 5 days, 12 hours, 30 minutes

// Multiply timespan
doubleSpan = timespan * 2

// Divide timespan
halfSpan = timespan / 2

// Add calculated timespan to date
newDate = dt + (timespan * 1.5)

Using DateAdd for Precision

dt = now()

// Add specific units
futureDate = dateAdd("d", 5, dt)     // Add 5 days
futureDate = dateAdd("h", 3, dt)     // Add 3 hours
futureDate = dateAdd("n", 30, dt)    // Add 30 minutes
futureDate = dateAdd("s", 45, dt)    // Add 45 seconds

// Date part units:
// "yyyy" - years
// "q" - quarters  
// "m" - months
// "d" - days
// "w" - weekdays
// "ww" - weeks
// "h" - hours
// "n" - minutes
// "s" - seconds
// "l" - milliseconds

Date Comparison and Differences

dt1 = createDate(2023, 12, 25)
dt2 = createDate(2023, 12, 30)

// Compare dates
result = dateCompare(dt1, dt2)  // Returns -1 (dt1 is earlier)

// Get specific differences
daysDiff = dateDiff("d", dt1, dt2)     // 5 days
hoursDiff = dateDiff("h", dt1, dt2)    // 120 hours
minutesDiff = dateDiff("n", dt1, dt2)  // 7200 minutes

// Boolean comparisons
isAfter = dt2.isAfter(dt1)    // true
isBefore = dt1.isBefore(dt2)  // true
isEqual = dt1.isEqual(dt2)    // false

Extracting Date Parts

BoxLang provides numerous BIFs to extract specific parts of dates:

dt = now()

// Basic parts
currentYear = year(dt)
currentMonth = month(dt)
currentDay = day(dt)
currentHour = hour(dt)
currentMinute = minute(dt)
currentSecond = second(dt)

// Advanced parts
dayOfWeek = dayOfWeek(dt)               // 1-7 (Sunday=1)
dayOfYear = dayOfYear(dt)               // 1-366
quarter = quarter(dt)                   // 1-4
week = week(dt)                         // Week of year

// String representations
monthName = monthAsString(dt)           // "December"
shortMonth = monthShortAsString(dt)     // "Dec"
dayName = dayOfWeekAsString(dt)         // "Tuesday"
shortDay = dayOfWeekShortAsString(dt)   // "Tue"

// Calculated values
daysInMonth = daysInMonth(dt)           // 28-31
daysInYear = daysInYear(dt)             // 365 or 366
firstDay = firstDayOfMonth(dt)          // First day of month

Utility Functions

Validation and Information

// Check if year is leap year
isLeap = dt.isLeapYear()

// Get numeric date (days since epoch)
numericDate = getNumericDate(dt)

// Get time in milliseconds since epoch
timeMillis = getTime(dt)
epochMillis = dt.toEpochMillis()
epochSeconds = dt.toEpoch()

Creating Time Spans

// Create timespan (days, hours, minutes, seconds)
span = createTimeSpan(1, 2, 30, 45)  // 1 day, 2 hours, 30 min, 45 sec

// Use timespan in calculations
futureDate = now() + span

Common Patterns and Examples

Working with Business Days

function addBusinessDays(date, days) {
    result = date
    remaining = days
    
    while (remaining > 0) {
        result = dateAdd("d", 1, result)
        // Skip weekends (Saturday=7, Sunday=1)
        if (dayOfWeek(result) != 1 && dayOfWeek(result) != 7) {
            remaining--
        }
    }
    
    return result
}

Date Range Generation

function getDateRange(startDate, endDate) {
    dates = []
    current = startDate
    
    while (dateCompare(current, endDate) <= 0) {
        arrayAppend(dates, current)
        current = dateAdd("d", 1, current)
    }
    
    return dates
}

Age Calculation

function calculateAge(birthDate) {
    today = now()
    age = dateDiff("yyyy", birthDate, today)
    
    // Adjust if birthday hasn't occurred this year
    birthdayThisYear = createDate(year(today), month(birthDate), day(birthDate))
    if (dateCompare(today, birthdayThisYear) < 0) {
        age--
    }
    
    return age
}

Timezone Conversion Utility

function convertTimezone(dt, fromTZ, toTZ) {
    // Use member methods for timezone conversion
    return dt.convertToZone(toTZ)
}

function formatInTimezone(dt, mask, timezone) {
    // Format date in specific timezone without changing request timezone
    return dateTimeFormat(dt, mask, timezone)
}

Performance Considerations

  • DateTime objects are immutable; operations return new instances

  • Use BIFs like dateAdd(), dateDiff(), dateFormat() for most operations

  • Cache formatted strings if formatting the same date multiple times with dateTimeFormat()

  • Be mindful of timezone conversions in loops

  • Use createTimeSpan() for duration calculations rather than manual arithmetic

PreviousNumbersNextJSON

Last updated 1 day ago

Was this helpful?

BoxLang supports mathematical operations on dates, converting them to fractional days for calculations. For basic arithmetic operations (addition, subtraction, multiplication, and division), dates and timespans can be cast as numeric values. In BoxLang, the numeric value of a object represents the decimal days since the Unix epoch time.

A or Java object is represented as decimal days for the purpose of mathematical operations.

DateTime
timespan
Duration