CkDateTime Class Overview
CkDateTime represents a date/time value and provides
conversion methods for common date/time formats, including .NET
DateTime, DateTime ticks, RFC 822, RFC 3339 /
ISO 8601-style timestamps, Unix time, DOS date/time, OLE DATE, NTP time,
ULID timestamps, and Chilkat DtObj. It also supports
date arithmetic, age/expiration checks, serialization, and local/UTC conversion.
What the Class Is Used For
Use CkDateTime when an application needs a portable
date/time container that can move between multiple date/time representations.
It is especially useful when working with email dates, HTTP/API timestamps,
Unix timestamps, Windows/OLE dates, ZIP/DOS date fields, NTP time values,
ULIDs, or Chilkat classes that exchange dates through
CkDateTime or DtObj.
Convert Between Formats
Convert to and from RFC 822, RFC 3339 timestamps, Unix time, DOS date/time,
OLE DATE, .NET DateTime, DateTime ticks, and NTP time.
Local or UTC Output
Most getter methods accept bLocal to choose local
time or UTC/GMT output.
Date Arithmetic
Add or subtract days and seconds, compare date/time values, and check whether
a time is older than or expires within a given interval.
ULID Support
Extract a timestamp from a ULID, generate a ULID from the object’s date/time,
validate ULIDs, and increment a ULID string.
Typical Workflow
-
Create a CkDateTime object.
-
Set its value from the current system time, a string timestamp, Unix time,
.NET DateTime, ticks, DOS date, OLE DATE, NTP time,
ULID, serialized value, or DtObj.
-
Optionally adjust it with AddDays or
AddSeconds.
-
Convert it to the required output format with one of the
GetAs* methods or
ToDtObj.
-
Use comparison helpers such as DiffSeconds,
OlderThan, or
ExpiresWithin when checking age or expiration.
-
Check LastErrorText after failures or unexpected
results.
Core Concepts
| Concept |
Meaning |
Important Members |
| Internal Date/Time Value |
The object stores one date/time value that can be loaded from one format and
emitted in another.
|
SetFromCurrentSystemTime,
SetFromTimestamp,
GetAsTimestamp
|
| Local vs UTC |
Many methods accept bLocal. When true, the
method uses local time. When false, it uses UTC/GMT.
|
GetAsDateTime,
GetAsRfc822,
SetFromUnixTime64
|
| Offset and DST |
The class can report the UTC offset and daylight-saving status for the date
stored in the object.
|
UtcOffset,
IsDst
|
| Serialization |
A Chilkat-specific text format can preserve and reload the date/time value.
|
Serialize,
DeSerialize
|
| Age and Expiration |
The object can be compared to another date/time or to the current system
time.
|
DiffSeconds,
OlderThan,
ExpiresWithin
|
| ULID Timestamp |
A ULID includes an embedded timestamp that can be read or used to generate a
new ULID.
|
SetFromUlid,
UlidGenerate,
UlidValidate
|
Core Properties
| Property |
Purpose |
Important Detail |
| IsDst |
Indicates whether daylight saving time was in effect for the date/time
stored in the object.
|
Returns 1 for DST in effect,
0 for not in effect, or
-1 if unavailable. This is for the object’s
date/time, not necessarily the current system time.
|
| UtcOffset |
Returns the offset, in seconds, from UTC for the current system timezone at
this object’s date/time.
|
Includes daylight-saving adjustment. Local timezones west of UTC return a
negative value.
|
| LastErrorText |
Diagnostic text for the last method or property access.
|
Check this after failures or unexpected behavior. Information may be
available even when a method succeeds.
|
Setting the Date/Time Value
| Input Source |
Method |
Notes |
| Current system time |
SetFromCurrentSystemTime |
Sets the object from the current system date/time.
|
| .NET DateTime |
SetFromDateTime |
Pass bLocal to indicate whether the incoming
DateTime is local or UTC.
|
| .NET DateTime ticks |
SetFromDateTimeTicks |
Sets from a 64-bit DateTime tick value.
|
| RFC 822 string |
SetFromRfc822 |
Accepts email-style dates such as
Tue, 15 Nov 2022 22:00:58 +0000.
|
| RFC 3339 / ISO 8601-style timestamp |
SetFromTimestamp |
Accepts timestamps such as
1990-12-31T23:59:60Z. Starting in
v9.5.0.77, compact values such as
181221132225Z are also accepted.
|
| Unix time |
SetFromUnixTime,
SetFromUnixTime64,
SetFromUnixTimeDbl
|
Sets from seconds since 1970-01-01 00:00:00 UTC.
Prefer 64-bit or double variants for dates beyond the 32-bit Unix time
range.
|
| DOS date/time bitmask |
SetFromDosDate |
Sets from the 32-bit DOS date/time bitmask format.
|
| Windows OLE DATE |
SetFromOleDate |
Sets from a floating-point OLE automation date value.
|
| NTP server |
SetFromNtpServer |
Sets the date/time by sending a query to an NTP server using settings in a
JSON string.
|
| NTP 32-bit time |
SetFromNtpTime |
Sets from seconds since 1900-01-01 00:00:00 GMT.
|
| Chilkat DtObj |
SetFromDtObj |
Sets from a Chilkat DtObj.
|
| ULID timestamp |
SetFromUlid |
Extracts the embedded timestamp from a valid ULID. Returns false if the ULID
is invalid.
|
| Serialized Chilkat date/time |
DeSerialize |
Loads the non-standard string produced by
Serialize.
|
Getting the Date/Time in Other Formats
| Output Format |
Method |
Result |
| .NET DateTime |
GetAsDateTime |
Returns a native System.DateTime structure in
local time or UTC.
|
| .NET DateTime ticks |
GetAsDateTimeTicks |
Returns a 64-bit tick value, where ticks are 100-nanosecond intervals since
0001-01-01 00:00:00 in the Gregorian calendar.
|
| RFC 822 |
GetAsRfc822 |
Returns an email Date-header style string, such as
Wed, 18 Oct 2017 09:08:21 GMT.
|
| RFC 3339 timestamp |
GetAsTimestamp |
Returns a timestamp such as
1990-12-31T23:59:60Z.
|
| Custom ISO 8601-compatible string |
GetAsIso8601 |
Uses a format string such as
YYYY-MM-DD,
YYYY-MM-DDThh:mm:ssTZD, or a variant with
milliseconds.
|
| Unix time |
GetAsUnixTime,
GetAsUnixTime64,
GetAsUnixTimeDbl,
GetAsUnixTimeStr
|
Returns seconds since 1970-01-01 00:00:00 UTC
as unsigned int, 64-bit integer, double, or string.
|
| DOS date/time |
GetAsDosDate |
Returns the 32-bit DOS date/time bitmask.
|
| Windows OLE DATE |
GetAsOleDate |
Returns a floating-point OLE automation date value.
|
| Chilkat DtObj |
ToDtObj |
Copies the date/time to a DtObj in local time
or GMT.
|
| Serialized Chilkat string |
Serialize |
Returns a Chilkat-specific string containing year, month, day, hour,
minutes, seconds, and a UTC flag.
|
Local vs UTC
Many methods include a bLocal argument. This controls
whether the input or output is interpreted as local time or UTC/GMT.
| bLocal Value |
Meaning |
Typical Use |
| true |
Use or return the date/time in the local timezone.
|
Displaying dates to users, converting from local UI input, generating local
RFC 822 or timestamp strings.
|
| false |
Use or return the date/time in UTC/GMT.
|
API timestamps, server-side storage, Unix time, protocol fields, and
timezone-neutral comparisons.
|
DST and offset are date-specific:
IsDst and UtcOffset are
evaluated for the date/time contained in the object, not simply for the current
system time.
Date Arithmetic and Comparisons
| Task |
Method |
Behavior |
| Add or subtract days |
AddDays |
Adds an integer number of days. Pass a negative value to subtract days.
|
| Add or subtract seconds |
AddSeconds |
Adds an integer number of seconds. Pass a negative value to subtract seconds.
|
| Difference between two dates |
DiffSeconds |
Returns this object’s date/time minus the argument’s date/time, in seconds.
Positive means this object is more recent.
|
| Check whether a date is older than now |
OlderThan |
Returns true if the object’s date/time is older than the current system time
by the specified interval.
|
| Check whether a date expires soon |
ExpiresWithin |
Returns true if the object’s date/time is within the specified interval of
the current system date/time.
|
Units:
OlderThan and
ExpiresWithin accept
seconds, minutes,
hours, or days, singular
or plural.
Unix Time and the Y2038 Issue
| Need |
Method |
Guidance |
| 32-bit Unix time |
GetAsUnixTime,
SetFromUnixTime
|
Uses seconds since the Unix epoch as a 32-bit value.
|
| 64-bit Unix time |
GetAsUnixTime64,
SetFromUnixTime64
|
Use for dates after 2038-01-19 and for general
future-proofing.
|
| Double Unix time |
GetAsUnixTimeDbl,
SetFromUnixTimeDbl
|
Another option for avoiding 32-bit Unix time limitations.
|
| String Unix time |
GetAsUnixTimeStr |
Returns the Unix timestamp as a string.
|
Best practice:
Prefer GetAsUnixTime64 and
SetFromUnixTime64 for new code. The 64-bit variants
avoid the classic 32-bit Unix time overflow problem after January 19, 2038.
DOS, OLE, NTP, and .NET Formats
| Format |
Methods |
Description |
| DOS date/time |
GetAsDosDate,
SetFromDosDate
|
Uses a 32-bit bitmask. The year is stored as an offset from 1980, and
seconds are stored in two-second increments.
|
| OLE DATE |
GetAsOleDate,
SetFromOleDate
|
A floating-point value counting days since midnight on
1899-12-30. Fractional days represent time.
|
| NTP time |
SetFromNtpTime,
SetFromNtpServer
|
NTP seconds are counted from
1900-01-01 00:00:00 GMT. The server method
queries an NTP server.
|
| .NET DateTime |
GetAsDateTime,
SetFromDateTime
|
Converts to or from a native System.DateTime.
|
| .NET DateTime ticks |
GetAsDateTimeTicks,
SetFromDateTimeTicks
|
Uses 100-nanosecond intervals since
0001-01-01 00:00:00.
|
RFC 822, RFC 3339, and ISO 8601-Style Strings
| String Format |
Methods |
Example / Notes |
| RFC 822 |
SetFromRfc822,
GetAsRfc822
|
Email-style date strings, such as
Wed, 18 Oct 2017 09:08:21 GMT.
|
| RFC 3339 timestamp |
SetFromTimestamp,
GetAsTimestamp
|
Timestamp strings such as
1990-12-31T23:59:60Z.
|
| ISO 8601-compatible output |
GetAsIso8601 |
Uses a format string, such as
YYYY-MM-DD,
YYYY-MM-DDThh:mmTZD,
YYYY-MM-DDThh:mm:ssTZD, or
YYYY-MM-DDThh:mm:ss:sssTZD.
|
| Compact timestamp input |
SetFromTimestamp |
Starting in v9.5.0.77, compact strings such as
181221132225Z are accepted.
|
Serialization
| Task |
Method |
Format |
| Serialize |
Serialize |
Returns a Chilkat-specific ASCII string containing space-separated integers:
year, month, day, hour, minutes, seconds, and a UTC flag
1 or 0.
|
| Deserialize |
DeSerialize |
Loads a date/time from the exact format produced by
Serialize.
|
Not a public standard:
The serialized format is intended for Chilkat round-tripping with
Serialize and DeSerialize.
It is not intended to match a published date/time standard.
ULID Support
| Task |
Method |
Behavior |
| Set date/time from ULID |
SetFromUlid |
Extracts the timestamp embedded in a valid ULID. Returns false if the ULID
is invalid.
|
| Generate ULID |
UlidGenerate |
Generates a new ULID using this object’s date/time value.
|
| Increment ULID |
UlidIncrement |
Increments the ULID passed in a StringBuilder.
|
| Validate ULID |
UlidValidate |
Returns true if the supplied ULID is valid.
|
Diagnostics and Troubleshooting
| Problem Area |
Member |
What to Check |
| Parsing or conversion failure |
LastErrorText |
Check detailed diagnostic information after a method returns false or
produces an unexpected result.
|
| Unexpected local/UTC result |
bLocal arguments |
Confirm whether the method call is interpreting or returning local time or
UTC/GMT.
|
| Unexpected daylight-saving result |
IsDst |
Remember that IsDst applies to the date stored
in the object, not necessarily to the current date.
|
| Unix time overflow risk |
GetAsUnixTime64,
SetFromUnixTime64
|
Use 64-bit Unix time for dates after January 19, 2038.
|
| ULID did not set the date/time |
SetFromUlid,
UlidValidate
|
Validate the ULID first, or check the return value from
SetFromUlid.
|
| Serialized value cannot be read elsewhere |
Serialize,
DeSerialize
|
The serialized format is Chilkat-specific, not a general date/time standard.
|
Common Pitfalls
| Pitfall |
Better Approach |
| Assuming IsDst is for the current system time. |
It reports DST status for the date/time stored in the object.
|
| Mixing local and UTC values accidentally. |
Treat the bLocal argument as part of the data
contract. Be explicit and consistent.
|
| Using 32-bit Unix time for future dates. |
Use GetAsUnixTime64 and
SetFromUnixTime64 to avoid the Y2038 problem.
|
| Expecting Serialize to produce RFC 3339, ISO 8601, or RFC 822. |
Use GetAsTimestamp,
GetAsIso8601, or
GetAsRfc822 for standard text formats.
|
| Passing an invalid ULID to SetFromUlid. |
Use UlidValidate or check the method return
value before using the resulting date/time.
|
| Using date arithmetic without checking direction. |
AddDays and
AddSeconds subtract when passed negative values.
DiffSeconds returns this object minus the
argument.
|
Best Practices
| Recommendation |
Reason |
| Use UTC for storage and protocol values. |
UTC avoids ambiguity across machines, timezones, and daylight-saving
transitions.
|
| Use GetAsRfc822 for email-style date headers. |
RFC 822 format is the style used in email Date header fields.
|
| Use GetAsTimestamp or GetAsIso8601 for API-style timestamps. |
These produce widely used timestamp string formats.
|
| Prefer 64-bit Unix time in new code. |
It avoids the 2038 overflow problem associated with 32-bit Unix time.
|
| Use DtObj when individual date/time fields are needed. |
ToDtObj and SetFromDtObj
bridge between field-oriented date/time data and
CkDateTime.
|
| Use Serialize only for Chilkat round-tripping. |
For external systems, choose a standard format such as RFC 822, RFC 3339,
ISO 8601-style output, or Unix time.
|
| Check LastErrorText after failed conversions. |
It provides the most useful diagnostic detail for parsing, conversion, NTP,
ULID, and task-result operations.
|
Summary
CkDateTime is a flexible date/time conversion
and utility class. It can load date/time values from system time, .NET
DateTime, ticks, RFC 822, RFC 3339 timestamps,
Unix time, DOS date/time, OLE DATE, NTP time, DtObj,
ULIDs, and Chilkat’s serialized format. It can emit those values in many of the
same formats, perform simple arithmetic, compare dates, check expiration or age,
and report local UTC offset and daylight-saving status for the stored date/time.
The most important usage rule is to be explicit about local time vs UTC whenever
a method accepts bLocal. For durable storage and API
protocols, UTC and 64-bit Unix time are usually the safest choices.