Date & Time Functions¶

Functions for date and time creation, manipulation, component extraction, and calculations.

Current Date & Time¶

$Now¶

Returns the current UTC date and time.

Signature:

$Now();

Returns: (DateTime) Current UTC date and time with time component

Examples:

currentTime = $Now();
timestamp = $Now();

// Use in calculations
hoursAgo = $AddHours($Now(), -2);

Notes:

Always returns UTC time
Includes date and time components
Use $Today() for date-only values

$Today¶

Returns the current date at midnight (no time component).

Signature:

$Today();

Returns: (DateTime) Current date at 00:00:00

Examples:

today = $Today();

// Calculate future dates
nextWeek = $AddDays($Today(), 7);
nextMonth = $AddMonths($Today(), 1);

// Age calculation
age = $DifferenceInYears($Today(), birthDate);

Notes:

Time component is 00:00:00
Useful for date-only comparisons
Based on system local time

Date Creation & Conversion¶

$ToDate¶

Converts a string to DateTime.

Signature:

$ToDate(value);

Parameters:

value (string or DateTime): Date string or DateTime value

Returns: (DateTime) Parsed date

Examples:

date1 = $ToDate("2024-01-15");
date2 = $ToDate("01/15/2024");
date3 = $ToDate("2024-01-15 14:30:00");

// Already DateTime - returns as-is
existing = $Now();
same = $ToDate(existing);

// Use in comparisons
effectiveDate = $ToDate("2024-06-01");
if ($Today() >= effectiveDate) {
  // Policy is effective
}

Notes:

Accepts various date string formats
Throws error if parsing fails
Returns input unchanged if already DateTime

$ToDateOnly¶

Converts to DateOnly (date without time).

Signature:

value.ToDateOnly();

Parameters: None (instance method)

Returns: (DateOnly) Date without time component

Examples:

dateTime = $Now();
dateOnly = dateTime.ToDateOnly();

// From string
dateStr = "2024-01-15";
date = $ToDate(dateStr).ToDateOnly();

Notes:

Instance method on DateTime values
DateOnly type has no time component
Useful when only date matters

Adding Time¶

$AddDays¶

Adds days to a date.

Signature:

$AddDays(date, days);

Parameters:

date (DateTime or string): Starting date
days (decimal): Number of days (can be negative)

Returns: (DateTime) New date

Examples:

today = $Today();
tomorrow = $AddDays(today, 1);
yesterday = $AddDays(today, -1);
nextWeek = $AddDays(today, 7);
lastMonth = $AddDays(today, -30);

// Policy expiration
policyStart = $ToDate("2024-01-01");
policyEnd = $AddDays(policyStart, 365);

$AddHours¶

Adds hours to a date/time.

Signature:

$AddHours(date, hours);

Parameters:

date (DateTime or string): Starting date/time
hours (decimal): Number of hours (can be negative)

Returns: (DateTime) New date/time

Examples:

now = $Now();
inTwoHours = $AddHours(now, 2);
twoHoursAgo = $AddHours(now, -2);

// Business hours
startTime = $ToDate("2024-01-15 09:00:00");
endTime = $AddHours(startTime, 8); // 5 PM

$AddMinutes¶

Adds minutes to a date/time.

Signature:

$AddMinutes(date, minutes);

Parameters:

date (DateTime or string): Starting date/time
minutes (decimal): Number of minutes (can be negative)

Returns: (DateTime) New date/time

Examples:

now = $Now();
soon = $AddMinutes(now, 30);
earlier = $AddMinutes(now, -15);

// Meeting times
meetingStart = $ToDate("2024-01-15 14:00:00");
meetingEnd = $AddMinutes(meetingStart, 60);

$AddSeconds¶

Adds seconds to a date/time.

Signature:

$AddSeconds(date, seconds);

Parameters:

date (DateTime or string): Starting date/time
seconds (decimal): Number of seconds (can be negative)

Returns: (DateTime) New date/time

Examples:

now = $Now();
future = $AddSeconds(now, 30);
past = $AddSeconds(now, -10);

// Timeout calculation
requestTime = $Now();
timeout = $AddSeconds(requestTime, 300); // 5 minutes

$AddMonths¶

Adds months to a date.

Signature:

$AddMonths(date, months);

Parameters:

date (DateTime or string): Starting date
months (decimal): Number of months (can be negative)

Returns: (DateTime) New date

Examples:

today = $Today();
nextMonth = $AddMonths(today, 1);
lastQuarter = $AddMonths(today, -3);
nextYear = $AddMonths(today, 12);

// Policy renewal
startDate = $ToDate("2024-01-15");
renewalDate = $AddMonths(startDate, 12);

Notes:

Handles month-end edge cases (e.g., Jan 31 + 1 month = Feb 28/29)
Preserves time component

$AddYears¶

Adds years to a date.

Signature:

$AddYears(date, years);

Parameters:

date (DateTime or string): Starting date
years (decimal): Number of years (can be negative)

Returns: (DateTime) New date

Examples:

today = $Today();
nextYear = $AddYears(today, 1);
fiveYearsAgo = $AddYears(today, -5);

// Long-term policy
policyStart = $ToDate("2024-01-01");
policyEnd = $AddYears(policyStart, 20);

// Age milestone
birthDate = $ToDate("1990-05-15");
age18 = $AddYears(birthDate, 18);

Notes:

Handles leap year edge cases
Preserves time component

Date Differences¶

$DifferenceInDays¶

Calculates days between two dates.

Signature:

$DifferenceInDays(date1, date2);

Parameters:

date1 (DateTime or string): First date
date2 (DateTime or string): Second date

Returns: (decimal) Number of days (floored to integer)

Examples:

start = $ToDate("2024-01-01");
end = $ToDate("2024-01-15");
days = $DifferenceInDays(end, start); // 14

today = $Today();
futureDate = $AddDays(today, 30);
diff = $DifferenceInDays(futureDate, today); // 30

// Negative if date1 < date2
past = $AddDays(today, -10);
negativeDiff = $DifferenceInDays(past, today); // -10

// Days until expiration
expirationDate = $ToDate("2024-12-31");
daysRemaining = $DifferenceInDays(expirationDate, $Today());

Notes:

Returns floor(days) as integer
Can be negative
Ignores time component

$DifferenceInHours¶

Calculates hours between two date/times.

Signature:

$DifferenceInHours(date1, date2);

Parameters:

date1 (DateTime or string): First date/time
date2 (DateTime or string): Second date/time

Returns: (decimal) Number of hours (floored to integer)

Examples:

start = $ToDate("2024-01-15 09:00:00");
end = $ToDate("2024-01-15 17:00:00");
hours = $DifferenceInHours(end, start); // 8

now = $Now();
inTwoHours = $AddHours(now, 2);
diff = $DifferenceInHours(inTwoHours, now); // 2

$DifferenceInMinutes¶

Calculates minutes between two date/times.

Signature:

$DifferenceInMinutes(date1, date2);

Parameters:

date1 (DateTime or string): First date/time
date2 (DateTime or string): Second date/time

Returns: (decimal) Number of minutes (floored to integer)

Examples:

start = $ToDate("2024-01-15 14:00:00");
end = $ToDate("2024-01-15 14:45:00");
minutes = $DifferenceInMinutes(end, start); // 45

now = $Now();
later = $AddMinutes(now, 30);
diff = $DifferenceInMinutes(later, now); // 30

$DifferenceInSeconds¶

Calculates seconds between two date/times.

Signature:

$DifferenceInSeconds(date1, date2);

Parameters:

date1 (DateTime or string): First date/time
date2 (DateTime or string): Second date/time

Returns: (decimal) Number of seconds (floored to integer)

Examples:

start = $ToDate("2024-01-15 14:00:00");
end = $ToDate("2024-01-15 14:00:30");
seconds = $DifferenceInSeconds(end, start); // 30

now = $Now();
future = $AddSeconds(now, 120);
diff = $DifferenceInSeconds(future, now); // 120

$DifferenceInYears¶

Calculates years between two dates.

Signature:

$DifferenceInYears(date1, date2);

Parameters:

date1 (DateTime or string): First date
date2 (DateTime or string): Second date

Returns: (decimal) Number of complete years

Examples:

birthDate = $ToDate("1990-05-15");
today = $Today();
age = $DifferenceInYears(today, birthDate);

policyStart = $ToDate("2020-01-01");
yearsActive = $DifferenceInYears($Today(), policyStart);

// Customer tenure
joinDate = $ToDate("2018-03-20");
tenure = $DifferenceInYears($Today(), joinDate);

Notes:

Returns complete years only
Does not round up
Useful for age calculations

Date Component Extraction¶

$Year¶

Extracts the year component.

Signature:

$Year(date);

Parameters:

date (DateTime or string): Date value

Returns: (decimal) Year as integer

Examples:

date = $ToDate("2024-06-15");
year = $Year(date); // 2024

currentYear = $Year($Today());
birthYear = $Year(birthDate);

$Month¶

Extracts the month component.

Signature:

$Month(date);

Parameters:

date (DateTime or string): Date value

Returns: (decimal) Month as integer (1-12)

Examples:

date = $ToDate("2024-06-15");
month = $Month(date); // 6

currentMonth = $Month($Today());

// Month-based logic
if ($Month(effectiveDate) == 1) {
  // January processing
}

$Day¶

Extracts the day component.

Signature:

$Day(date);

Parameters:

date (DateTime or string): Date value

Returns: (decimal) Day of month as integer (1-31)

Examples:

date = $ToDate("2024-06-15");
day = $Day(date); // 15

currentDay = $Day($Today());

// Day-based logic
if ($Day(paymentDate) == 1) {
  // First of month
}

Date Boundaries¶

$StartOfDay¶

Returns date at 00:00:00 (midnight).

Signature:

$StartOfDay(date);

Parameters:

date (DateTime or string): Date value

Returns: (DateTime) Date at 00:00:00

Examples:

now = $Now(); // 2024-01-15 14:30:45
startOfDay = $StartOfDay(now); // 2024-01-15 00:00:00

// Compare dates ignoring time
date1Start = $StartOfDay(date1);
date2Start = $StartOfDay(date2);
if (date1Start == date2Start) {
  // Same day
}

$EndOfDay¶

Returns date at 23:59:59 (end of day).

Signature:

$EndOfDay(date);

Parameters:

date (DateTime or string): Date value

Returns: (DateTime) Date at 23:59:59

Examples:

now = $Now(); // 2024-01-15 14:30:45
endOfDay = $EndOfDay(now); // 2024-01-15 23:59:59

// Check if before end of day
if ($Now() < $EndOfDay($Today())) {
  // Still today
}

// Date range (full day)
dayStart = $StartOfDay(date);
dayEnd = $EndOfDay(date);

Timezone Functions¶

$ConvertTimeFromUtc¶

Converts UTC time to a specific timezone.

Signature:

$ConvertTimeFromUtc(utcDateTime, timeZoneId);

Parameters:

utcDateTime (DateTime): UTC date/time
timeZoneId (string): Timezone identifier

Returns: (DateTime) Converted date/time

Examples:

utcNow = $Now();
eastern = $ConvertTimeFromUtc(utcNow, "Eastern Standard Time");
pacific = $ConvertTimeFromUtc(utcNow, "Pacific Standard Time");
central = $ConvertTimeFromUtc(utcNow, "Central Standard Time");

// Common timezone IDs (Windows)
// "Eastern Standard Time"
// "Central Standard Time"
// "Mountain Standard Time"
// "Pacific Standard Time"
// "UTC"

Notes:

Requires valid Windows timezone ID
Handles daylight saving time
Input must be UTC

Common Patterns¶

Pattern 1: Age Calculation¶

function calculateAge(birthDate) {
  return $DifferenceInYears($Today(), birthDate);
}

age = calculateAge($ToDate("1990-05-15"));

Pattern 2: Date Range Check¶

function isInDateRange(date, startDate, endDate) {
  return date >= startDate && date <= endDate;
}

effectiveDate = $ToDate("2024-06-15");
policyStart = $ToDate("2024-01-01");
policyEnd = $ToDate("2024-12-31");

isActive = isInDateRange(effectiveDate, policyStart, policyEnd);

Pattern 3: Days Until Event¶

expirationDate = $ToDate("2024-12-31");
daysRemaining = $DifferenceInDays(expirationDate, $Today());

if (daysRemaining < 30) {
  status = "Expiring soon";
} else if (daysRemaining < 90) {
  status = "Active";
} else {
  status = "Long-term";
}

Pattern 4: Date Formatting¶

date = $Today();
year = $Year(date);
month = $Month(date);
day = $Day(date);

// Custom format
formatted = $ToString(year) + "-" + $ToString(month) + "-" + $ToString(day);

Pattern 5: Tenure Calculation¶

function calculateTenure(joinDate) {
  years = $DifferenceInYears($Today(), joinDate);

  if (years < 1) {
    return "New";
  } else if (years < 5) {
    return "Standard";
  } else if (years < 10) {
    return "Senior";
  } else {
    return "Veteran";
  }
}

Pattern 6: Business Days¶

// Add business days (simplified - excludes weekends only)
function addBusinessDays(startDate, days) {
  current = startDate;
  addedDays = 0;

  while (addedDays < days) {
    current = $AddDays(current, 1);
    // Note: EverSharp doesn't have day-of-week function
    // This is simplified
    addedDays++;
  }

  return current;
}

Best Practices¶

1. Use $Today() for Date-Only Comparisons¶

// Good
if (effectiveDate >= $Today()) {
  // Future or today
}

// Less ideal (includes time)
if (effectiveDate >= $Now()) {
  // May miss same-day dates
}

2. Store Dates in ISO Format¶

// Good
dateStr = "2024-01-15";
date = $ToDate(dateStr);

// Works but less portable
dateStr = "01/15/2024";

3. Handle Timezone Consistently¶

// Good: Always use UTC internally
utcTime = $Now();
// Convert for display
localTime = $ConvertTimeFromUtc(utcTime, timeZoneId);

4. Extract Components for Logic¶

// Good
month = $Month(date);
if (month >= 4 && month <= 6) {
  quarter = "Q2";
}

// Less clear
if (date >= $ToDate("2024-04-01") && date < $ToDate("2024-07-01")) {
  quarter = "Q2";
}

Advanced Examples¶

Example 1: Policy Term Calculator¶

function calculatePolicyTerm(startDate, termYears) {
  endDate = $AddYears(startDate, termYears);
  totalDays = $DifferenceInDays(endDate, startDate);
  remainingDays = $DifferenceInDays(endDate, $Today());

  percentComplete = (1 - remainingDays / totalDays) * 100;

  return {
    startDate: startDate,
    endDate: endDate,
    termYears: termYears,
    totalDays: totalDays,
    remainingDays: remainingDays,
    percentComplete: $Round(percentComplete, 1),
    isActive: $Today() >= startDate && $Today() <= endDate,
  };
}

policyInfo = calculatePolicyTerm($ToDate("2024-01-01"), 10);

Example 2: Age-Based Premium¶

function calculateAgePremium(birthDate, basePremium) {
  age = $DifferenceInYears($Today(), birthDate);

  if (age < 25) {
    return basePremium * 1.5;
  } else if (age < 35) {
    return basePremium * 1.2;
  } else if (age < 50) {
    return basePremium * 1.0;
  } else if (age < 65) {
    return basePremium * 1.3;
  } else {
    return basePremium * 1.5;
  }
}

Example 3: Payment Schedule¶

function generatePaymentSchedule(startDate, months, amount) {
  schedule = [];
  currentDate = startDate;

  i = 0;
  while (i < months) {
    payment = {
      number: i + 1,
      dueDate: currentDate,
      amount: amount,
      isPastDue: currentDate < $Today(),
    };

    schedule.Push(payment);
    currentDate = $AddMonths(currentDate, 1);
    i++;
  }

  return schedule;
}

payments = generatePaymentSchedule($ToDate("2024-01-01"), 12, 100);

Next Steps¶

Explore other categories:
String Functions
Array Functions
Conversion Functions
See practical examples:
Working with Dates
Business Rules