XScript Manual · Chapter 33

DATE Object — Date / Time Utilities

The script keyword DATE provides date/time helpers. The internal representation is .NET Ticks (long) — lighter than DateTime and trivial to compare/compute on.

Form	Meaning
`long` (Ticks)	1 tick = 100 ns. Counted from `DateTime(0001-01-01)`.
`"yyyy-MM-dd HH:mm:ss"`	Standard human-readable format

One-liner for now — long now = DATE.GetNow();

Current time

long nowLocal = DATE.GetNow();      // Ticks in local TZ
long nowUtc   = DATE.GetUtcNow();   // Ticks in UTC
 
Log($"now local : {DATE.ConvertDateTimeString(nowLocal)}");
Log($"now utc   : {DATE.ConvertDateTimeString(nowUtc)}");

String ↔ Ticks

// Ticks → string
string d  = DATE.ConvertDateString(DATE.GetNow());                   // "2026-05-06"
string dt = DATE.ConvertDateTimeString(DATE.GetNow());                // "2026-05-06 09:31:02"
string dt2 = DATE.ConvertDateTimeString(DATE.GetNow(), "HH:mm:ss");  // custom format
 
// string → Ticks
long t1 = DATE.ConvertDateTimeLong("2026-05-06 09:30:00");
long t2 = DATE.ConvertUtcDateTimeLong("2026-05-06T00:30:00Z");
 
// Safe parse — false on failure
long t3;
if( DATE.TryParseDateTime("2026-13-99", t3) == false )
{
    LogError("invalid date input");
}

Format characters: yyyy MM dd HH mm ss fff (case-sensitive — MM month / mm minute).

Local ↔ UTC

long local = DATE.GetNow();
long utc   = DATE.ConvertLocalToUtc(local);
 
long backToLocal = DATE.ConvertUtcToLocal(utc);

Save UTC to DB, display Local in UI — those two conversions are all you need.

Encode / Decode

// Build from year-month-day-hour-minute-second-ms
long t = DATE.EncodeDate(2026, 5, 6);
long u = DATE.EncodeDateTime(2026, 5, 6, 9, 30, 0, 0);
 
// Split apart
int year, month, day;
DATE.DecodeDate(t, year, month, day);
 
int yy, mm, dd, hh, mi, ss, ms;
DATE.DecodeDateTime(u, yy, mm, dd, hh, mi, ss, ms);

DecodeDate / DecodeDateTime populate out parameters directly into your variables.

Differences (Between)

long start = DATE.EncodeDateTime(2026, 5, 1, 9, 0, 0, 0);
long end   = DATE.GetNow();
 
int years   = DATE.YearsBetween(end, start);
int months  = DATE.MonthsBetween(end, start);
int weeks   = DATE.WeeksBetween(end, start);
int days    = DATE.DaysBetween(end, start);
long hours  = DATE.HoursBetween(end, start);
long mins   = DATE.MinutesBetween(end, start);
long secs   = DATE.SecondsBetween(end, start);
long mss    = DATE.MilliSecondsBetween(end, start);
 
Log($"elapsed : {days}d {hours % 24}h {mins % 60}m");

Argument order doesn't matter — internally computed as absolute value.

Increment*

long now = DATE.GetNow();
 
long oneYearLater  = DATE.IncrementYears(now, 1);
long threeMonths   = DATE.IncrementMonths(now, 3);
long tomorrow      = DATE.IncrementDays(now, 1);
long inOneHour     = DATE.IncrementHours(now, 1);
long inFiveMinutes = DATE.IncrementMinutes(now, 5);
long inThirtySec   = DATE.IncrementSeconds(now, 30);
long inOneSecond   = DATE.IncrementMilliseconds(now, 1000);
 
// negative → past
long yesterday     = DATE.IncrementDays(now, -1);

Common patterns

Show elapsed work time

long workStart;
 
FUNCTION OnStart()
{
    workStart = DATE.GetNow();
}
 
FUNCTION OnTick()
{
    long now = DATE.GetNow();
    int sec = (int)DATE.SecondsBetween(now, workStart);
    Data::ElapsedText = $"{sec / 60}:{sec % 60:00}";
}

Wait until a deadline

long deadline = DATE.IncrementSeconds(DATE.GetNow(), 30);
 
while( DATE.GetNow() < deadline )
{
    if( SYS.IsHomeDone() ) return true;
    Sleep(50);
}
return false;     // timeout

Per-day folder

string today = DATE.ConvertDateString(DATE.GetNow());        // "2026-05-06"
string folder = $"D:/Logs/{today}";
SYS.CreateFolder(folder);

Quick reference

Function	Returns	Meaning
`GetNow()` / `GetUtcNow()`	long	Now (local / UTC)
`ConvertDateString(t)`	string	`"yyyy-MM-dd"`
`ConvertDateTimeString(t)` / `(t, fmt)`	string	Default / custom format
`ConvertDateTimeLong(s)`	long	string → Ticks
`ConvertUtcDateTimeLong(s)`	long	Treats input as UTC
`TryParseDateTime(s, ref t)`	bool	Safe parse
`ConvertLocalToUtc(t)` / `ConvertUtcToLocal(t)`	long	TZ conversion
`EncodeDate / EncodeDateTime`	long	Numbers → Ticks
`DecodeDate / DecodeDateTime`	void	Ticks → out variables
`YearsBetween / Months / Weeks / Days / Hours / Minutes / Seconds / MilliSeconds`	int / long	Diff between two times
`IncrementYears / Months / Days / Hours / Minutes / Seconds / Milliseconds`	long	Add (negative = subtract)