COleDateTimeSpan 類別

發行項
10/12/2023

表示相對時間，時間範圍。

語法

class COleDateTimeSpan

成員

公用建構函式

名稱	描述
COleDateTimeSpan：：COleDateTimeSpan	建構 `COleDateTimeSpan` 物件。

公用方法

名稱	描述
COleDateTimeSpan：：Format	產生物件的格式化字串表示 `COleDateTimeSpan` 。
COleDateTimeSpan：：GetDays	傳回這個 `COleDateTimeSpan` 物件所代表之範圍的日期部分。
COleDateTimeSpan：：GetHours	傳回這個 `COleDateTimeSpan` 物件所代表之範圍中的小時部分。
COleDateTimeSpan：：GetMinutes	傳回這個 `COleDateTimeSpan` 物件所代表之範圍的分鐘部分。
COleDateTimeSpan：：GetSeconds	傳回這個 `COleDateTimeSpan` 物件所表示之範圍的第二個部分。
COleDateTimeSpan：：GetStatus	取得這個 `COleDateTimeSpan` 物件的狀態（有效性）。
COleDateTimeSpan：：GetTotalDays	傳回這個 `COleDateTimeSpan` 物件所代表的天數。
COleDateTimeSpan：：GetTotalHours	傳回這個 `COleDateTimeSpan` 物件所代表的時數。
COleDateTimeSpan：：GetTotalMinutes	傳回這個 `COleDateTimeSpan` 物件所代表的分鐘數。
COleDateTimeSpan：：GetTotalSeconds	傳回這個 `COleDateTimeSpan` 物件所代表的秒數。
COleDateTimeSpan：：SetDateTimeSpan	設定這個 `COleDateTimeSpan` 物件的值。
COleDateTimeSpan：：SetStatus	設定這個 `COleDateTimeSpan` 物件的狀態（有效性）。

公用運算子

名稱	描述
operator +， -	新增、減去和變更值的符號 `COleDateTimeSpan` 。
operator +=， -=	從這個`COleDateTimeSpan`值新增和減`COleDateTimeSpan`去值。
operator =	`COleDateTimeSpan`複製值。
operator ==，， <<=	比較兩個 `COleDateTimeSpan` 值。
operator double	將此值 `COleDateTimeSpan` 轉換為 `double`。

公用資料成員

名稱	描述
COleDateTimeSpan：：m_span	包含這個 `COleDateTimeSpan` 對象的基礎`double`。
COleDateTimeSpan：：m_status	包含這個 `COleDateTimeSpan` 物件的狀態。

備註

COleDateTimeSpan 沒有基類。

會 COleDateTimeSpan 以天為單位來保留時間。

COleDateTimeSpan 與隨附類別 COleDateTime 搭配使用。 COleDateTime 封裝 DATE OLE 自動化的數據類型。 COleDateTime 表示絕對時間值。所有 COleDateTime 計算都牽涉到 COleDateTimeSpan 值。這些類別之間的關聯類似於 CTime 與 CTimeSpan 之間的關聯。

如需和類別的詳細資訊COleDateTime，請參閱日期和時間：自動化支援一文。COleDateTimeSpan

需求

標頭： ATLComTime.h

COleDateTimeSpan 關係運算子

比較運算子。

bool operator==(const COleDateTimeSpan& dateSpan) const throw();
bool operator!=(const COleDateTimeSpan& dateSpan) const throw();
bool operator<(const COleDateTimeSpan& dateSpan) const throw();
bool operator>(const COleDateTimeSpan& dateSpan) const throw();
bool operator<=(const COleDateTimeSpan& dateSpan) const throw();
bool operator>=(const COleDateTimeSpan& dateSpan) const throw();

參數

dateSpan
要比較的 COleDateTimeSpan。

傳回值

這些運算符會比較兩個日期/時間範圍值，如果條件為 true，則傳回 TRUE;否則為 FALSE。

備註

注意

如果任一操作數無效，就會發生ATLASSERT。

範例

COleDateTimeSpan spanOne(3, 12, 0, 0); // 3 days and 12 hours
COleDateTimeSpan spanTwo(spanOne);     // 3 days and 12 hours
BOOL b;
b = spanOne == spanTwo;                // TRUE
b = spanOne < spanTwo;                 // FALSE, same value
b = spanOne > spanTwo;                 // FALSE, same value
b = spanOne <= spanTwo;                // TRUE, same value
b = spanOne >= spanTwo;                // TRUE, same value   

spanTwo.SetStatus(COleDateTimeSpan::invalid);
b = spanOne == spanTwo;                // FALSE, different status
b = spanOne != spanTwo;                // TRUE, different status

COleDateTimeSpan ts1(100.0);   // one hundred days
COleDateTimeSpan ts2(110.0);   // ten more days

ASSERT((ts1 != ts2) && (ts1 < ts2) && (ts1 <= ts2));

COleDateTimeSpan：：COleDateTimeSpan

建構 COleDateTimeSpan 物件。

COleDateTimeSpan() throw();
COleDateTimeSpan(double dblSpanSrc) throw();
COleDateTimeSpan(LONG lDays, int nHours, int nMins, int nSecs) throw();

參數

dblSpanSrc
要複製到新 COleDateTimeSpan 物件的天數。

lDays、 nHours、 nMins、 nSecs
指出要複製到新 COleDateTimeSpan 物件的日期和時間值。

備註

所有這些建構函式都會建立初始化為指定值的新 COleDateTimeSpan 物件。下列每個建構函式的簡短描述如下：

COleDateTimeSpan（） 建構 COleDateTimeSpan 初始化為 0 的物件。
COleDateTimeSpan（ dblSpanSrc ）從浮點值建構 COleDateTimeSpan 物件。
COleDateTimeSpan（lDays 、nHours 、 nMinsnSecs ） 建構COleDateTimeSpan初始化為指定數值的物件。

新 COleDateTimeSpan 物件的狀態會設定為有效。

如需值界限COleDateTimeSpan的詳細資訊，請參閱日期和時間：自動化支援一文。

範例

COleDateTimeSpan spanOne(2.75);          // 2 days and 18 hours
COleDateTimeSpan spanTwo(2, 18, 0, 0);   // 2 days and 18 hours
COleDateTimeSpan spanThree(3, -6, 0, 0); // 2 days and 18 hours

COleDateTimeSpan ts1;               // Uninitialized time value
COleDateTimeSpan ts2a(ts1);         // Copy constructor
COleDateTimeSpan ts2b = ts1;         // Copy constructor again
COleDateTimeSpan ts3(100.0);          // 100 days
COleDateTimeSpan ts4(0, 1, 5, 12);   // 1 hour, 5 minutes, and 12 seconds

COleDateTimeSpan：：Format

產生物件的格式化字串表示 COleDateTimeSpan 。

CString Format(LPCTSTR pFormat) const;
CString Format(UINT nID) const;

參數

pFormat
格式字串，類似於 printf 格式化字串。格式化程序代碼前面加上百分比（%）符號，會由對應的 COleDateTimeSpan 元件取代。格式化字串中的其他字元會保持不變地複製到傳回的字串。的格式化程序代碼 Format 的值和意義如下：

目前日期的 %H 小時
目前小時內的 %M 分鐘數
目前分鐘中的 %S 秒
%% 百分比符號

上述四個格式代碼是 Format 將接受的唯一程序代碼。

nID
格式控制字串的資源識別碼。

傳回值

CString，包含格式化的日期/時間範圍值。

備註

呼叫這些函式，以建立時間範圍值的格式化表示法。如果這個 COleDateTimeSpan 物件的狀態為 Null，則傳回值是空字串。如果狀態無效，則傳回字串是由字串資源IDS_INVALID_DATETIMESPAN指定。

此函式表單的簡短描述如下：

格式（pFormat ）
此窗體會使用格式字串來格式化值，其中包含前面加上百分比符號的特殊格式代碼，如中所示 printf。格式化字串會當做參數傳遞至函式。

Format（ nID ）
此窗體會使用格式字串來格式化值，其中包含前面加上百分比符號的特殊格式代碼，如中所示 printf。格式化字串是資源。此字串資源的識別碼會以參數的形式傳遞。

範例

// get the current time
COleDateTime tmStart = COleDateTime::GetCurrentTime();

// waste some time
CString str;
::Sleep(3000);

// get the current time again
COleDateTime tmFinish = COleDateTime::GetCurrentTime();

// find the difference
COleDateTimeSpan tmSpan = tmFinish - tmStart;

// tell the user
str = tmSpan.Format(_T("%S seconds elapsed"));
_tprintf_s(_T("%s\n"), (LPCTSTR) str);

COleDateTimeSpan：：GetDays

擷取此日期/時間範圍值的日期部分。

LONG GetDays() const throw();

傳回值

此日期/時間範圍值的日期部分。

備註

此函式的傳回值大約介於 3,615,000 和 3,615,000 之間。

如需查詢物件值 COleDateTimeSpan 的其他函式，請參閱下列成員函式：

GetHours
GetMinutes
GetSeconds
GetTotalDays
GetTotalHours
GetTotalMinutes
GetTotalSeconds

範例

COleDateTimeSpan ts(3, 1, 5, 12); // 3 days, 1 hour, 5 min, and 12 sec
ASSERT(ts.GetDays() == 3);

COleDateTimeSpan：：GetHours

擷取此日期/時間範圍值的小時部分。

LONG GetHours() const throw();

傳回值

這個日期/時間範圍值的時數部分。

備註

此函式的傳回值介於 - 23 和 23 之間。

如需查詢物件值 COleDateTimeSpan 的其他函式，請參閱下列成員函式：

GetDays
GetMinutes
GetSeconds
GetTotalDays
GetTotalHours
GetTotalMinutes
GetTotalSeconds

範例

COleDateTimeSpan ts(3, 1, 5, 12); // 3 days, 1 hour, 5 min, and 12 sec
ASSERT(ts.GetHours() == 1);

COleDateTimeSpan：：GetMinutes

擷取此日期/時間範圍值的分鐘部分。

LONG GetMinutes() const throw();

傳回值

這個日期/時間範圍值的分鐘部分。

備註

此函式的傳回值介於 - 59 和 59 之間。

如需查詢物件值 COleDateTimeSpan 的其他函式，請參閱下列成員函式：

GetDays
GetHours
GetSeconds
GetTotalDays
GetTotalHours
GetTotalMinutes
GetTotalSeconds

範例

COleDateTimeSpan ts(3, 1, 5, 12); // 3 days, 1 hour, 5 min, and 12 sec
ASSERT(ts.GetMinutes() == 5);

COleDateTimeSpan：：GetSeconds

擷取這個日期/時間範圍值的第二個部分。

LONG GetSeconds() const throw();

傳回值

這個日期/時間範圍值的秒部分。

備註

此函式的傳回值介於 - 59 和 59 之間。

如需查詢物件值 COleDateTimeSpan 的其他函式，請參閱下列成員函式：

GetDays
GetHours
GetMinutes
GetTotalDays
GetTotalHours
GetTotalMinutes
GetTotalSeconds

範例

COleDateTimeSpan ts(3, 1, 5, 12); // 3 days, 1 hour, 5 min, and 12 sec
ASSERT(ts.GetSeconds() == 12);

COleDateTimeSpan：：GetStatus

取得這個 COleDateTimeSpan 物件的狀態（有效性）。

DateTimeSpanStatus GetStatus() const throw();

傳回值

此值 COleDateTimeSpan 的狀態。

備註

傳回值是由 DateTimeSpanStatus 列舉型別所定義，該型別定義於 COleDateTimeSpan 類別內。

enum DateTimeSpanStatus{
   valid = 0,
   invalid = 1,
   null = 2,
};

如需這些狀態值的簡短描述，請參閱下列清單：

COleDateTimeSpan::valid 表示這個 COleDateTimeSpan 物件有效。
COleDateTimeSpan::invalid 表示這個 COleDateTimeSpan 物件無效，也就是說，其值可能不正確。
COleDateTimeSpan::null 表示此 COleDateTimeSpan 物件為 null，也就是說，此物件未提供任何值。（這是資料庫意義上的“null”，與C++ NULL 相反。

在下列情況下，物件的狀態 COleDateTimeSpan 無效：

如果這個物件在算術指派作業期間發生溢位或下溢，即 += 或 -=。
如果將無效的值指派給這個物件。
如果這個物件的狀態已明確設定為無效，請使用 SetStatus。

如需可能將狀態設定為無效之作業的詳細資訊，請參閱 COleDateTimeSpan：：operator +， - 和 COleDateTimeSpan：：operator +=， -=。

如需值界限COleDateTimeSpan的詳細資訊，請參閱日期和時間：自動化支援一文。

COleDateTimeSpan：：GetTotalDays

擷取以天表示的這個日期/時間範圍值。

double GetTotalDays() const throw();

傳回值

以天表示的這個日期/時間範圍值。雖然此函式是以原型傳回雙精度浮點數，但一律會傳回整數值。

備註

此函式的傳回值大約介於 - 3.65e6 和 3.65e6 之間。

如需查詢物件值 COleDateTimeSpan 的其他函式，請參閱下列成員函式：

GetDays
GetHours
GetMinutes
GetSeconds
GetTotalHours
GetTotalMinutes
GetTotalSeconds

範例

COleDateTimeSpan ts(3, 1, 5, 12); // 3 days, 1 hour, 5 min, and 12 sec
ASSERT(ts.GetTotalDays() == 3);
ASSERT(ts.GetTotalHours() == 73);
ASSERT(ts.GetTotalMinutes() == 4385);
ASSERT(ts.GetTotalSeconds() == 263112);

COleDateTimeSpan：：GetTotalHours

擷取以小時表示的這個日期/時間範圍值。

double GetTotalHours() const throw();

傳回值

以小時表示的這個日期/時間範圍值。雖然此函式是以原型傳回雙精度浮點數，但一律會傳回整數值。

備註

此函式的傳回值介於大約 - 8.77e7 和 8.77e7 之間。

如需查詢物件值 COleDateTimeSpan 的其他函式，請參閱下列成員函式：

GetDays
GetHours
GetMinutes
GetSeconds
GetTotalDays
GetTotalMinutes
GetTotalSeconds

範例

請參閱 GetTotalDays 的範例。

COleDateTimeSpan：：GetTotalMinutes

擷取以分鐘為單位表示的這個日期/時間範圍值。

double GetTotalMinutes() const throw();

傳回值

以分鐘為單位表示的這個日期/時間範圍值。雖然此函式是以原型傳回雙精度浮點數，但一律會傳回整數值。

備註

此函式的傳回值介於大約 - 5.26e9 和 5.26e9 之間。

如需查詢物件值 COleDateTimeSpan 的其他函式，請參閱下列成員函式：

GetDays
GetHours
GetMinutes
GetSeconds
GetTotalDays
GetTotalHours
GetTotalSeconds

範例

請參閱 GetTotalDays 的範例。

COleDateTimeSpan：：GetTotalSeconds

擷取以秒為單位表示的這個日期/時間範圍值。

double GetTotalSeconds() const throw();

傳回值

這個以秒為單位表示的日期/時間範圍值。雖然此函式是以原型傳回雙精度浮點數，但一律會傳回整數值。

備註

此函式的傳回值介於大約 - 3.16e11 到 3.16e11 之間。

如需查詢物件值 COleDateTimeSpan 的其他函式，請參閱下列成員函式：

GetDays
GetHours
GetMinutes
GetSeconds
GetTotalDays
GetTotalHours
GetTotalMinutes

範例

請參閱 GetTotalDays 的範例。

COleDateTimeSpan：：m_span

這個COleDateTime物件的基礎double值。

double m_span;

備註

此值以天為單位表示日期/時間範圍。

警告

變更數據成員中的 double 值將會變更這個 COleDateTimeSpan 物件的值。它不會變更這個 COleDateTimeSpan 物件的狀態。

COleDateTimeSpan：：m_status

這個數據成員的型別是列舉型 DateTimeSpanStatus別，定義於 COleDateTimeSpan 類別內。

DateTimeSpanStatus m_status;

備註

enum DateTimeSpanStatus{
   valid = 0,
   invalid = 1,
   null = 2,
   };

如需這些狀態值的簡短描述，請參閱下列清單：

COleDateTimeSpan::valid 表示這個 COleDateTimeSpan 物件有效。
COleDateTimeSpan::invalid 表示這個 COleDateTimeSpan 物件無效，也就是說，其值可能不正確。
COleDateTimeSpan::null 表示此 COleDateTimeSpan 物件為 null，也就是說，此物件未提供任何值。（這是資料庫意義上的“null”，與C++ NULL 相反。

在下列情況下，物件的狀態 COleDateTimeSpan 無效：

如果這個物件在算術指派作業期間發生溢位或下溢，即 += 或 -=。
如果將無效的值指派給這個物件。
如果使用 SetStatus 明確將此物件的狀態設定為無效。

如需可能將狀態設定為無效之作業的詳細資訊，請參閱 COleDateTimeSpan：：operator +， - 和 COleDateTimeSpan：：operator +=， -=。

警告

此數據成員適用於進階程式設計情況。您應該使用內嵌成員函式 GetStatus 和 SetStatus。如需明確設定此資料成員的進一步注意事項，請參閱 SetStatus 。

如需值界限COleDateTimeSpan的詳細資訊，請參閱日期和時間：自動化支援一文。

COleDateTimeSpan：：operator =

COleDateTimeSpan複製值。

COleDateTimeSpan& operator=(double dblSpanSrc) throw();

備註

這個多載指派運算符會將來源日期/時間範圍值複製到這個 COleDateTimeSpan 物件中。

COleDateTimeSpan：：operator +， -

新增、減去和變更值的符號 COleDateTimeSpan 。

COleDateTimeSpan operator+(const COleDateTimeSpan& dateSpan) const throw();
COleDateTimeSpan operator-(const COleDateTimeSpan& dateSpan) const throw();
COleDateTimeSpan operator-() const throw();

備註

前兩個運算符可讓您新增和減去日期/時間範圍值。第三個可讓您變更日期/時間範圍值的符號。

如果其中一個操作數為 Null，則結果 COleDateTimeSpan 值的狀態為 Null。

如果任一操作數無效，另一個操作數不是 Null，則產生的 COleDateTimeSpan 值狀態無效。

如需有效、無效和 Null 狀態值的詳細資訊，請參閱 m_status 成員變數。

範例

COleDateTimeSpan ts1(3, 1, 5, 12); // 3 days, 1 hour, 5 min, and 12 sec
COleDateTimeSpan ts2(100.0 / (24 * 3600.0)); // 100 seconds
COleDateTimeSpan ts3 = ts1 + ts2;
ASSERT(ts3.GetSeconds() == 52); // 6 mins, 52 secs

COleDateTimeSpan：：operator +=， -=

從這個COleDateTimeSpan值新增和減COleDateTimeSpan去值。

COleDateTimeSpan& operator+=(const COleDateTimeSpan dateSpan) throw();
COleDateTimeSpan& operator-=(const COleDateTimeSpan dateSpan) throw();

備註

這些運算子可讓您從這個 COleDateTimeSpan 物件新增和減去日期/時間範圍值。如果其中一個操作數為 Null，則結果 COleDateTimeSpan 值的狀態為 Null。

如果任一操作數無效，另一個操作數不是 Null，則產生的 COleDateTimeSpan 值狀態無效。

如需有效、無效和 Null 狀態值的詳細資訊，請參閱 m_status 成員變數。

範例

COleDateTimeSpan ts1(10.0); // 10 days
COleDateTimeSpan ts2(100.0); // 100 days
ts2 -= ts1;
ASSERT(ts2.GetTotalDays() == 90);

COleDateTimeSpan：：operator double

將此值 COleDateTimeSpan 轉換為 double。

operator double() const throw();

備註

這個運算子會將此值 COleDateTimeSpan 的值當做浮點數傳回。

COleDateTimeSpan：：SetDateTimeSpan

設定這個日期/時間範圍值的值。

void SetDateTimeSpan(LONG lDays, int nHours, int nMins, int nSecs) throw();

參數

lDays、 nHours、 nMins、 nSecs
指出要複製到這個 COleDateTimeSpan 物件的日期範圍和時間範圍值。

備註

如需查詢物件值的 COleDateTimeSpan 函式，請參閱下列成員函式：

GetDays
GetHours
GetMinutes
GetSeconds
GetTotalDays
GetTotalHours
GetTotalMinutes
GetTotalSeconds

範例

COleDateTimeSpan spanOne;
COleDateTimeSpan spanTwo;
spanOne.SetDateTimeSpan(0, 2, 45, 0);  // 2 hours and 45 seconds
spanTwo.SetDateTimeSpan(0, 3, -15, 0); // 2 hours and 45 seconds

COleDateTimeSpan：：SetStatus

設定這個 COleDateTimeSpan 物件的狀態（有效性）。

void SetStatus(DateTimeSpanStatus status) throw();

參數

status
這個 COleDateTimeSpan 物件的新狀態值。

備註

Status 參數值是由DateTimeSpanStatus列舉型別所定義，其定義於 COleDateTimeSpan 類別內。

enum DateTimeSpanStatus{
   valid = 0,
   invalid = 1,
   null = 2,
   };

如需這些狀態值的簡短描述，請參閱下列清單：

COleDateTimeSpan::valid 表示這個 COleDateTimeSpan 物件有效。
COleDateTimeSpan::invalid 表示這個 COleDateTimeSpan 物件無效，也就是說，其值可能不正確。
COleDateTimeSpan::null 表示此 COleDateTimeSpan 物件為 null，也就是說，此物件未提供任何值。（這是資料庫意義上的“null”，與C++ NULL 相反。

警告

此函式適用於進階程式設計情況。此函式不會改變這個物件中的數據。它最常用來將狀態設定為 Null 或無效。請注意，指派運算符（operator =）和 SetDateTimeSpan 會根據來源值來設定物件的狀態。

範例

// if the person is not still in school, set days to graduation to null
if (!m_bStillInSchool || m_dtDateOfGraduation.GetStatus() == COleDateTime::null)
   m_dtsDaysToGraduation.SetStatus(COleDateTimeSpan::null);

另請參閱

COleDateTime 類別
 CTime 類別
 CTimeSpan 類別
 階層架構圖表
 ATL/MFC 共享類別

共用方式為

COleDateTimeSpan 類別

語法

成員

公用建構函式

公用方法

公用運算子

公用資料成員

備註

需求

COleDateTimeSpan 關係運算子

參數

傳回值

備註

範例

COleDateTimeSpan：：COleDateTimeSpan

參數

備註

範例

COleDateTimeSpan：：Format

參數

傳回值

備註

範例

COleDateTimeSpan：：GetDays

傳回值

備註

範例

COleDateTimeSpan：：GetHours

傳回值

備註

範例

COleDateTimeSpan：：GetMinutes

傳回值

備註

範例

COleDateTimeSpan：：GetSeconds

傳回值

備註

範例

COleDateTimeSpan：：GetStatus

傳回值

備註

COleDateTimeSpan：：GetTotalDays

傳回值

備註

範例

COleDateTimeSpan：：GetTotalHours

傳回值

備註

範例

COleDateTimeSpan：：GetTotalMinutes

傳回值

備註

範例

COleDateTimeSpan：：GetTotalSeconds

傳回值

備註

範例

COleDateTimeSpan：：m_span

備註

COleDateTimeSpan：：m_status

備註

COleDateTimeSpan：：operator =

備註

COleDateTimeSpan：：operator +， -

備註

範例

COleDateTimeSpan：：operator +=， -=

備註

範例

COleDateTimeSpan：：operator double

備註

COleDateTimeSpan：：SetDateTimeSpan

參數

備註

範例

COleDateTimeSpan：：SetStatus

參數

備註