C++Builder TDateTime 完全指南：日期時間運算、格式化、轉換與時區處理最佳實踐

C++Builder TDateTime 完全指南：日期時間運算、格式化、轉換與時區處理最佳實踐

TDateTime 是 VCL 核心類庫中日期時間運算的基石，以 double 為底層表示（整數部=日期，小數部=時間），提供豐富的運算子重載、格式化輸出、解碼/編碼、檔案時間互轉等功能。本文系統梳理其內存模型、核心 API、格式化語法、高性能運算模式與時區避坑指南。

內存模型與數值範例

class TDateTime : public TDateTimeBase {
    double val;  // 繼承自 TDateTimeBase
};

關鍵常數：1.0 = 1 天，1.0/24 = 1 小時，1.0/1440 = 1 分鐘，1.0/86400 = 1 秒。

構造函數全景

運算子重載（核心優勢）

// 日期時間運算直觀如數學
TDateTime now = TDateTime::CurrentDateTime();
TDateTime tomorrow = now + 1;              // +1 天
TDateTime nextWeek = now + 7;
TDateTime halfDay = now + 0.5;             // +12 小時
TDateTime diff = nextWeek - now;           // 差值為 TDateTime（7.0）
int days = int(diff);                      // 隱式轉 int 取整數天
double hours = diff * 24;                  // 隱式轉 double 精確小數

// 比較運算子完整支援
if (now < tomorrow) ...
if (now >= TDateTime::CurrentDate()) ...

複合賦值：+=、-=、++、--（前綴/後綴）均可用，-- 以天為單位遞減。

靜態工廠方法

解碼與編碼

// 解碼到離散分量
void DecodeDate(Word* y, Word* m, Word* d) const;
void DecodeTime(Word* h, Word* m, Word* s, Word* ms) const;
int DayOfWeek() const;  // 1=Sun ... 7=Sat

// 編碼由分量構造（靜態輔助函數，非成員）
TDateTime EncodeDate(Word y, Word m, Word d);
TDateTime EncodeTime(Word h, Word m, Word s, Word ms);

格式化輸出：FormatString 完整語法

AnsiString FormatString(const AnsiString& fmt) 支援下列格式字元（區分大小寫）：

範例：dt.FormatString("yyyy-mm-dd hh:nn:ss") → "2024-03-15 14:30:05"。

轉換運算子

operator AnsiString()  // 等同 FormatString("c")
operator double()      // 底層 val
operator int()         // 整數天數

檔案時間互轉

int FileDate() const;                    // TDateTime → DOS 時間戳
static TDateTime FileDateToDateTime(int); // DOS 時間戳 → TDateTime
// Win32 FILETIME 需自行轉換：
// FILETIME ft; SystemTimeToFileTime(&st, &ft); // 需中間轉 SYSTEMTIME

高性能運算模式

1. 批量運算用 double：double d = dt; d += 3.5; dt = d; 避免臨時對象構造。
2. 避免循環中呼叫 CurrentDateTime()：系統呼叫昂貴，循環外快取一次。
3. 跨時區運算：TDateTime 無時區感知，始終視為本地時間。跨時區請：
   　　① 轉 SYSTEMTIME → TzSpecificLocalTimeToSystemTime → SystemTimeToFileTime → FILETIME → ULARGE_INTEGER 運算 → 逆向轉回。
   　　② 或引入 ICU / date.h (Howard Hinnant) 等專業時區庫。

常見陷阱

TDateTime 以 double 為核心、運算子重載為介面，實現了極致易用的日期時間代數。掌握其底層表示、格式化語法與時區邊界，即可在 VCL 應用中構建健壯的時間業務邏輯。