What the Class Is Used For

Use Chilkat.DtObj when a Chilkat method needs to pass or receive a date/time as a structured object instead of a formatted string. The class exposes the date/time fields directly, making it easy to inspect or set each part of the value.

Store Date Fields Use Year, Month, and Day to represent the calendar date.

Store Time Fields Use Hour, Minute, and Second to represent the time of day.

Track UTC vs Local Use Utc to indicate whether the date/time is UTC or local time.

Serialize and Restore Use Serialize and DeSerialize to save and reload the date/time fields.

Used by Other Chilkat Classes

Chilkat.DtObj is often used as a structured date/time argument by other Chilkat classes. In some methods, it may be passed as an input argument to provide a date/time value. In other methods, it may be used as an output argument that receives a date/time value populated by the method.

Class	How DtObj Is Used
CkDateTime	May use DtObj to get or set date/time values as individual fields such as year, month, day, hour, minute, second, and UTC/local status.
JsonObject	Some methods may use DtObj when reading, writing, or converting JSON date/time values.
JsonArray	Some methods may use DtObj when working with date/time values stored in JSON arrays.

Practical use: Treat DtObj as a small date/time transfer object. It is useful when another Chilkat method needs a date/time value broken into fields, or when a method returns a date/time by filling an object supplied by the caller.

Typical Workflow

Create a DtObj object.
Set the date fields: Year, Month, and Day.
Set the time fields: Hour, Minute, and Second.
Set Utc to true for UTC time or false for local time.
Pass the object to a Chilkat method, or inspect values populated by another Chilkat method.
Optionally call Serialize to save the value for later restoration.
Call DeSerialize to restore a value previously created by Serialize.
Check LastErrorText if behavior is unexpected.

Core Concepts

Concept	Meaning	Important Members
Date Components	The calendar portion of the date/time value.	Year, Month, Day
Time Components	The time-of-day portion of the date/time value.	Hour, Minute, Second
UTC Flag	Indicates whether the value is UTC or local time.	Utc
struct tm Compatibility	Alternate month and year forms compatible with C-style struct tm conventions.	StructTmMonth, StructTmYear
Internal Serialization	A Chilkat-specific space-separated integer format for saving and restoring the date/time fields.	Serialize, DeSerialize

Properties

Property	Valid Values	Meaning
Year	Calendar year, such as 2012	The full year.
Month	1 through 12	Calendar month, where 1 is January and 12 is December.
Day	1 through 31	Day of the month.
Hour	0 through 23	Hour of the day using a 24-hour clock.
Minute	0 through 59	Minute of the hour.
Second	0 through 59	Second of the minute.
Utc	true or false	True if the date/time is UTC. False if the date/time is local time.
StructTmMonth	0 through 11	Month using C struct tm convention, where 0 is January and 11 is December.
StructTmYear	Years since 1900	Year using C struct tm convention. For example, year 2026 is represented as 126.
LastErrorText	Read-only diagnostic text	Provides information about the last called method or property. Check after failures or unexpected behavior.

Calendar Fields vs struct tm Fields

Normal Calendar Property	struct tm-Style Property	Difference
Month	StructTmMonth	Month uses 1 through 12. StructTmMonth uses 0 through 11.
Year	StructTmYear	Year is the full calendar year. StructTmYear is the number of years since 1900.

Common source of mistakes: Month is 1-based, but StructTmMonth is 0-based. Use the property that matches the convention expected by your code.

Serialization

DtObj can serialize its date/time fields to a simple Chilkat-specific string and later restore from that string.

Method	Purpose	Format
Serialize	Converts the date/time object to a string that can be saved and restored later.	Space-separated integers: year month day hour minutes seconds utcFlag
DeSerialize	Loads the date/time fields from a string previously produced by Serialize.	Expects the same space-separated integer format produced by Serialize.

Not a public date/time standard: The serialized format is not intended to match ISO 8601, RFC 822, RFC 3339, or any other published standard. It is a Chilkat-specific format intended for restoring a DtObj later with DeSerialize.

UTC vs Local Time

Utc Value	Meaning	Use When
true	The date/time represents UTC time.	Use when the value should be interpreted as universal time.
false	The date/time represents local time.	Use when the value should be interpreted in the local time zone context.

Interpretation flag: Utc identifies whether the stored fields represent UTC or local time. The date and time fields themselves remain simple numeric fields.

Method Summary

Method	Direction	Purpose
Serialize	Object to string	Produces a US-ASCII string containing the date/time fields as space-separated integers.
DeSerialize	String to object	Loads the object from a string in the format produced by Serialize.

Diagnostics and Troubleshooting

Problem Area	Member	What to Check
Month appears one off	Month, StructTmMonth	Check whether your code expects normal calendar months 1 through 12, or struct tm months 0 through 11.
Year appears incorrect	Year, StructTmYear	Year is the full year. StructTmYear is years since 1900.
Date/time interpreted in wrong time basis	Utc	Verify whether the object should represent UTC time or local time.
Deserialization produces unexpected fields	Serialize, DeSerialize	Make sure the input string was produced by Serialize and has the expected order: year, month, day, hour, minutes, seconds, UTC flag.
Need operation details after unexpected behavior	LastErrorText	Check diagnostic text after failed or unexpected property or method behavior.

Common Pitfalls

Pitfall	Better Approach
Using StructTmMonth as if January were 1.	Use Month for normal 1-based calendar months. Use StructTmMonth only when 0-based struct tm month values are needed.
Using StructTmYear as if it were the full year.	Use Year for the full calendar year. StructTmYear is years since 1900.
Assuming Serialize returns a standard date/time string.	Treat it as a Chilkat-specific persistence format for DtObj, not as a public interchange format.
Forgetting to set Utc.	Set Utc deliberately so later code knows whether the value represents UTC or local time.
Setting invalid date or time component values.	Use the documented ranges for month, day, hour, minute, and second.
Ignoring diagnostics after unexpected behavior.	Check LastErrorText for details.

Best Practices

Recommendation	Reason
Use Year and Month for normal calendar values.	They use the familiar full-year and 1-based month convention.
Use StructTmYear and StructTmMonth only for struct-tm-style integrations.	These properties use C-style conventions that differ from normal calendar values.
Set Utc explicitly.	It avoids ambiguity when later code interprets the date/time value.
Use Serialize only for later DeSerialize.	The format is Chilkat-specific and not intended as a public date/time interchange format.
Validate component ranges before setting values from external input.	The properties have documented valid ranges for reliable date/time representation.
Check LastErrorText after unexpected behavior.	It provides useful diagnostic detail for the last method or property access.

Summary

Chilkat.DtObj is a compact date/time object with directly accessible fields for year, month, day, hour, minute, second, and UTC/local interpretation. It also provides struct tm-style year and month properties for compatibility with code that uses those conventions.

The most important practical guidance is to use Month and Year for normal calendar values, use StructTmMonth and StructTmYear only when 0-based month and years-since-1900 values are expected, set Utc deliberately, and treat Serialize as a Chilkat-specific persistence format rather than a public date/time standard.

Chilkat.DtObj Class Overview