GlideDateTime.compareTo()

What It Does

The compareTo() method performs a chronological comparison between two GlideDateTime objects by converting both to their internal millisecond representations and performing integer subtraction. The method returns an integer indicating the relative temporal position of the two datetime objects.

ServiceNow internally converts both datetime objects to UTC milliseconds since epoch (January 1, 1970), then subtracts the other parameter's value from the calling object's value. This means timezone information is properly handled during comparison, as both objects are normalized to UTC before the mathematical operation occurs.

The return value follows standard comparison conventions: negative integers (typically -1) when the calling object represents an earlier time, zero when both objects represent the exact same moment, and positive integers (typically 1) when the calling object represents a later time. The method never returns null or undefined for valid GlideDateTime objects.

Edge cases occur when comparing datetime objects with different timezone contexts or when one object contains invalid date data. The method will throw a runtime error if the other parameter is not a GlideDateTime instance. Invalid dates within valid GlideDateTime objects may produce unpredictable comparison results.

This method is functionally similar to before() and after() but provides tri-state comparison results in a single method call. Unlike equals(), this method provides relative ordering information essential for sorting operations.

When to Use This

Use compareTo() when implementing custom sorting logic for datetime arrays, building comparison functions for Array.sort(), or creating three-way conditional logic where you need to know if a date is before, equal to, or after another date. This method is particularly valuable in scheduled jobs that process records chronologically or in business rules that implement complex date-based workflows.

Avoid using compareTo() for simple before/after checks where before() or after() methods provide clearer semantic meaning. For equality checks, use equals() instead. Never use this method to compare GlideDateTime objects with string dates or JavaScript Date objects without proper conversion first.

Return Value

Returns a JavaScript number representing the chronological relationship between the two datetime objects. Negative values (commonly -1) indicate the calling object is earlier than the parameter, zero indicates exact temporal equality, and positive values (commonly 1) indicate the calling object is later than the parameter. The exact integer value should not be relied upon for anything other than sign comparison.

The method cannot return failure values like null or undefined for valid inputs; instead, it throws runtime errors when given invalid parameters. Always use the return value in conditional statements checking for negative, zero, or positive values rather than testing for specific integers like -1 or 1.

Platform Behavior & Side Effects

• No database operations are performed - this is purely an in-memory comparison operation
• No business rules, ACLs, or notifications are triggered as no data modification occurs
• Performance is very fast as it only involves integer arithmetic on pre-calculated millisecond values
• Timezone conversions to UTC happen automatically and transparently during the comparison
• Works identically in all server-side contexts - business rules, script includes, and scheduled jobs
• Runtime errors are thrown immediately if the parameter is not a valid GlideDateTime object