上一頁 下一頁

BirtDateTime 類別

BirtDateTime 類別提供一些函數,用來判斷兩個日期或時間相距的時間量、增加或扣除時間間距,以及取得日期中的某些部分。由於日期間距只是數字,因此,應用程式可以利用一般數學來處理它們:加、減、乘、除等等。這個類別是靜態的。 應用程式無法建立這個類別的實例。

BirtDateTime.addDay

這個函數會傳回日期加上給定的天數而得出的新日期。要增加的天數可以是負數。在這個情況下,結果如同從日期扣除該時間量。

語法

Date BirtDateTime.addDay( Date date, Number n )

參數

date

Date 物件。代表起始日期的日期物件。

n

Number 物件。加到日期上的天數。小數會視為整數,並向下捨入至最接近的整數。

傳回

Date 物件。起始日期加上指定的天數後而得出的日期。

範例

下列範例是對特定日期增加天數:

var startDate = "2008-12-31";
var endDate;
endDate = BirtDateTime.addDay( startDate, 1 ); // 傳回 2009-01-01
endDate = BirtDateTime.addDay( startDate, -1 ); // 傳回 2008-12-30

下列範例是在 InvoiceDate 欄位中,對每一個日期值增加 15 天:

BirtDateTime.addDay( row["InvoiceDate"], 15 )

BirtDateTime.addHour

這個函數會傳回日期加上給定的時數而得出的新日期。要增加的時數可以是負數。在這個情況下,結果如同從日期扣除該時間量。

語法

Date BirtDateTime.addHour( Date date, Number n )

參數

date

代表起始日期的日期物件。如果起始日期沒有時間值,函數會假設時間是午夜 (00:00:00)。

n

Number 物件。加到日期上的時數。

傳回

Date 物件。起始日期加上指定的時數後而得出的日期。

範例

下列範例是對特定的日期與時間增加時數:

var startDate = "2008-12-31 15:00:00";
var endDate;
endDate = BirtDateTime.addHour( startDate, 8 ); // 傳回 2008-12-31 11:00 PM
endDate = BirtDateTime.addHour( startDate, -8 ); // 傳回 2008-12-31 7:00 AM

下列範例是在 StartTime 欄位中,對每一個日期值增加 36 小時:

BirtDateTime.addHour( row["StartTime"], 36 )

BirtDateTime.addMinute

這個函數會傳回日期加上給定的分鐘數而得出的新日期。要增加的分鐘數可以是負數。在這個情況下,結果如同從日期扣除該時間量。

語法

Date BirtDateTime.addMinute( Date date, Number n )

參數

date

代表起始日期的日期物件。如果起始日期沒有時間值,函數會假設時間是午夜 (00:00:00)。

n

Number 物件。加到日期上的分數。

傳回

Date 物件。起始日期加上指定的分鐘數後而得出的日期。

範例

下列範例是對特定的日期與時間增加分鐘數:

var startDate = "2008-12-31 10:30:00";
var endDate;
endDate = BirtDateTime.addMinute( startDate, 45 );
// 傳回 2008-12-31 11:15 AM
endDate = BirtDateTime.addMinute( startDate, -30 );
// 傳回 2008-12-31 10:00 AM

下列範例是在 StartTime 欄位中,對每一個日期值增加 15 分鐘:

BirtDateTime.addMinute( row["StartTime"], 15 )

BirtDateTime.addMonth

這個函數會傳回日期加上給定的月數而得出的新日期。要增加的月數可以是負數。在這個情況下,結果如同從日期扣除該時間量。

這個函數一律會傳回有效日期。必要時,得出日期的日期部分,會往後調整成得出年份之得出月份的最後一天。例如,如果您對 2008-01-31 增加 1 個月,addMonth( ) 會傳回 2008-02-29(2008 年為閏年),而非 2008-02-31。

語法

Date BirtDateTime.addMonth( Date date, Number n )

參數

date

Date 物件。代表起始日期的日期物件。

n

Number 物件。加到日期上的月數。小數會視為整數,採無條件捨去小數。

傳回

Date 物件。起始日期加上指定的月數後而得出的日期。

範例

下列範例是對特定日期增加月數:

var startDate = "2008-12-31";
var endDate;
endDate = BirtDateTime.addMonth( startDate, 1 ); // 傳回 2009-01-31
endDate = BirtDateTime.addMonth( startDate, -1 ); // 傳回 2008-11-30
endDate = BirtDateTime.addMonth( startDate, 2 ); // 傳回 2009-02-28

下列範例是在 InvoiceDate 欄位中,對每一個日期值增加 10 個月:

BirtDateTime.addMonth( row["InvoiceDate"], 10 )

BirtDateTime.addQuarter

這個函數會傳回日期加上給定的季數而得出的新日期。一季等於三個月。例如,如果您對 2008-09-10 增加 2 季,函數會傳回 2009-03-10。 要增加的季數可以是負數。在這個情況下,結果如同從日期扣除該時間量。

語法

Date BirtDateTime.addQuarter( Date date, Number n )

參數

date

代表起始日期的日期物件。

n

Number 物件。加到日期上的季數。

傳回

Date 物件。起始日期加上指定的季數後而得出的日期。

範例

下列範例是對特定日期增加季數:

var startDate = "2008-12-15";
var endDate;
endDate = BirtDateTime.addQuarter( startDate, 1 ); // 傳回 2009-03-15
endDate = BirtDateTime.addQuarter( startDate, -2 ); // 傳回 2008-06-15

下列範例是在 ForecastClosing 欄位中,對每一個日期值增加 2 季:

BirtDateTime.addQuarter( row["ForecastClosing"], 2 )

BirtDateTime.addSecond

這個函數會傳回日期加上給定的秒數而得出的新日期。要增加的秒數可以是負數。在這個情況下,結果如同從日期扣除該時間量。

語法

Date BirtDateTime.addSecond( Date date, Number n )

參數

date

代表起始日期的日期物件。如果起始日期沒有時間值,函數會假設時間是午夜 (00:00:00)。

n

Number 物件。加到日期上的秒數。

傳回

Date 物件。起始日期加上指定的秒數後所得到的結果。

範例

下列範例是對特定的日期與時間增加秒數:

var startDate = "2008-12-31 10:30:00";
var endDate;
endDate = BirtDateTime.addSecond( startDate, 10000 );
// 傳回 2008-12-31 1:16:40 PM
endDate = BirtDateTime.addSecond( startDate, -10000 );
// 傳回 2008-12-31 7:43:20 AM

下列範例是在 StartTime 欄位中,對每一個日期值增加 6000 秒:

BirtDateTime.addSecond( row["StartTime"], 6000 )

BirtDateTime.addWeek

這個函數會傳回日期加上給定的週數而得出的新日期。要增加的週數可以是負數。在這個情況下,結果如同從日期扣除該時間量。

語法

Date BirtDateTime.addWeek( Date date, Number n )

參數

date

代表起始日期的日期物件。

n

Number 物件。加到日期上的週數。

傳回

Date 物件。起始日期加上指定的週數後而得出的日期。

範例

下列範例是對特定日期增加週數:

var startDate = "2008-12-31";
var endDate;
endDate = BirtDateTime.addWeek( startDate, 1 ); // returns Jan 07, 2009
endDate = BirtDateTime.addWeek( startDate, -1 ); // returns Dec 24, 2008

下列範例是在 InvoiceDate 欄位中,對每一個日期值增加 2 週:

BirtDateTime.addWeek( row["InvoiceDate"], 2 )

BirtDateTime.addYear

這個函數會傳回日期加上給定的年數而得出的新日期。要增加的年數可以是負數。在這個情況下,結果如同從日期扣除該時間量。

語法

Date BirtDateTime.addYear( Date date, Number n )

參數

date

代表起始日期的日期物件。

n

Number 物件。要加到日期的年數。小數會視為整數,採無條件捨去小數。

傳回

起始日期加上指定的年數後而得出的日期。

範例

下列範例是對特定日期增加年數:

var startDate = "2008-12-31";
var endDate;
endDate = BirtDateTime.addYear( startDate, 1 ); // 傳回 2009-12-31
endDate = BirtDateTime.addYear( startDate, -1 ); // 傳回 2007-12-31

下列範例是在 HireDate 欄位中,對每一個日期值增加 5 年:

BirtDateTime.addYear( row["HireDate"], 5 )

BirtDateTime.day

這個函數會傳回一個從 1 到 31 的數字,來代表該給定日期的月份日期。例如,如果日期是 2009-01-19,則函數會傳回 19。

語法

integer BirtDateTime.day( Date date )

參數

date

Date 物件。要從中取得日期的日期物件。

傳回

代表給定日期之月份日期的整數。

範例

下列範例傳回 ShipDate 欄位中每一個值的月份日期:

BirtDateTime.day( row["ShipDate"] )

下列範例傳回現行日期的月份日期:

BirtDateTime.day( (BirtDateTime.today())

BirtDateTime.diffDay

這個函數會傳回兩個日期間相距的天數。天的計算方式是從第二個日期的日期值扣除第一個日期的日期值。例如,如果第一個日期是 2008-12-30 23:59:59,第二個日期是 2008-12-31 00:00:00,函數會傳回 1 天,即使這兩個日期只相隔一秒。

語法

integer BirtDateTime.diffDay( Date date1, Date date2 )

參數

date1

代表時間間距開始的日期物件。

date2

代表時間間距結束的日期物件。

傳回

整數。兩個日期間相距的天數。

範例

下列範例傳回兩個特定日期間相距的天數:

BirtDateTime.diffDay( "2009-01-01", "2009-04-15" ) // 傳回 104

下列範例傳回現行日期至 2009 年結束相距的天數:

BirtDateTime.diffDay( BirtDateTime.today(), "2009-12-31" )

下列範例傳回 InvoiceDate 與 PaymentDate 欄位中的值相距的天數:

BirtDateTime.diffDay( row["InvoiceDate"], row["PaymentDate"] )

BirtDateTime.diffHour

這個函數會傳回兩個日期間相距的時數。小時的計算方式是從第二個日期的小時值扣除第一個日期的小時值。例如,如果第一個日期是 2009-01-31 1:30:00,第二個日期是 2009-01-31 2:00:00,函數會傳回 1 小時,即使這兩個日期只相隔 30 分鐘。如果日期沒有時間值,函數會假設時間是午夜 (00:00:00)。

語法

integer BirtDateTime.diffHour( Date date1, Date date2 )

參數

date1

代表時間間距開始的日期物件。

date2

代表時間間距結束的日期物件。

傳回

整數。兩個日期間相距的時數。

範例

下列範例傳回兩個特定日期間相距的時數:

BirtDateTime.diffHour( "2009-01-31 12:00:00", "2009-02-01 12:00:00")
// 傳回 24
BirtDateTime.diffHour( "2009-01-31", "2009-02-01 12:00:00")
// 傳回 36。由於第一個日期沒有時間,而假設為午夜。

下列範例傳回現行日期與時間至 2009 年結束相距的時數:

BirtDateTime.diffHour( BirtDateTime.now(), "2009-12-31" );

下列範例傳回 StartTime 與 FinishTime 欄位中的值相距的時數:

BirtDateTime.diffHour( row["StartTime"], row["FinishTime"] )

BirtDateTime.diffMinute

這個函數會傳回兩個日期間相距的分鐘數。分鐘的計算方式是從第二個日期的分鐘值扣除第一個日期的分鐘值。例如,如果第一個日期是 2009-01-31 1:30:59,第二個日期是 2009-01-31 1:31:00,函數會傳回 1 分鐘,即使這兩個日期只相隔一秒。如果日期沒有時間值,函數會假設時間是午夜 (00:00:00)。

語法

integer BirtDateTime.diffMinute( Date date1, Date date2 )

參數

date1

代表時間間距開始的日期物件。

date2

代表時間間距結束的日期物件。

傳回

整數。兩個日期間相距的分鐘數。

範例

下列範例傳回兩個特定日期間相距的分鐘數:

BirtDateTime.diffMinute( "2009-01-31 1:30:30", "2009-01-31 10:45:00")
// 傳回 555
BirtDateTime.diffMinute( "2009-01-31", "2009-01-31 12:00:00")
// 傳回 720。由於第一個日期沒有時間,而假設為午夜。

下列範例傳回現行日期與時間至 2010 年開始相距的分鐘數:

BirtDateTime.diffMinute( BirtDateTime.now(), "2010-01-01" )

下列範例傳回 StartTime 與 FinishTime 欄位中的值相距的分鐘數:

BirtDateTime.diffMinute( row["StartTime"], row["FinishTime"] )

BirtDateTime.diffMonth

這個函數會傳回兩個日期間相距的月數。月的計算方式是從第二個日期的月份值扣除第一個日期的月份值。例如,如果第一個日期是 2009-01-31,第二個日期是 2009-02-01,函數會傳回 1 個月,即使這兩個日期只相隔一天。

語法

integer BirtDateTime.diffMonth( Date date1, Date date2 )

參數

date1

代表時間間距開始的日期物件。

date2

代表時間間距結束的日期物件。

傳回

整數。兩個日期間相距的月數。

範例

下列範例傳回兩個特定日期間相距的月數:

BirtDateTime.diffMonth( "2009-01-31", "2009-04-15") // 傳回 3

下列範例傳回現行日期至 2010 年開始相距的月數:

BirtDateTime.diffMonth( BirtDateTime.today(), "2010-01-01" );

下列範例傳回 ProjectStart 與 ProjectComplete 欄位中的值相距的月數:

BirtDateTime.diffMonth( row["ProjectStart"], row["ProjectComplete"] )

BirtDateTime.diffQuarter

這個函數會傳回兩個日期間相距的季數。季的計算方式是從第二個日期的月份值扣除第一個日期的月份值。相差 3 個月就等於 1 季。例如,如果第一個日期是 2009-01-31,第二個日期是 2009-07-01,函數會傳回 2。如果第一個日期是 2009-01-01,第二個日期是 2009-09-30,函數同樣會傳回 2。

語法

integer BirtDateTime.diffQuarter( Date date1, Date date2 )

參數

date1

代表時間間距開始的日期物件。

date2

代表時間間距結束的日期物件。

傳回

整數。兩個日期間相距的季數。

範例

下列範例傳回兩個特定日期間相距的季數:

BirtDateTime.diffQuarter( "2009-01-31", "2009-04-15") // 傳回 1

下列範例傳回現行日期至 2010 年開始相距的季數:

BirtDateTime.diffQuarter( BirtDateTime.today(), "2010-01-01" );

下列範例傳回 ProjectStart 與 ProjectComplete 欄位中的值相距的季數:

BirtDateTime.diffQuarter( row["ProjectStart"], row["ProjectComplete"] )

BirtDateTime.diffSecond

這個函數會傳回兩個日期間相距的秒數。如果日期沒有時間值,函數會假設時間是午夜 (00:00:00)。

語法

integer BirtDateTime.diffSecond( date1, date2 )

參數

date1

代表時間間距開始的日期物件。

date2

代表時間間距結束的日期物件。

傳回

整數。兩個日期間相距的秒數。

範例

下列範例傳回兩個特定日期間相距的秒數:

BirtDateTime.diffSecond( "2009-01-31 11:30:30", "2009-01-31 12:00:00")
// 傳回 1770
BirtDateTime.diffSecond( "2009-01-31", "2009-01-31 1:00:00")
// 傳回 3600。由於第一個日期沒有時間,而假設為午夜。

下列範例傳回現行日期與時間至 2010 年開始相距的秒數:

BirtDateTime.diffSecond( BirtDateTime.now(), "2010-01-01" )

下列範例傳回 StartTime 與 FinishTime 欄位中的值相距的秒數:

BirtDateTime.diffSecond( row["StartTime"], row["FinishTime"] )

BirtDateTime.diffWeek

這個函數會傳回兩個日期間相距的週數。週的計算方式是將第二個日期的週數扣除第一個日期的週數。例如,如果第一個日期是 2009-01-02(該年度的第一週),第二個日期是 2009-01-05(該年度的第二週),函數會傳回 1 週,即使這兩個日期只相隔三天。

語法

integer BirtDateTime.diffWeek( Date date1, Date date2 )

參數

date1

代表時間間距開始的日期物件。

date2

代表時間間距結束的日期物件。

傳回

整數。兩個日期間相距的週數。

範例

下列範例傳回兩個特定日期間相距的週數:

BirtDateTime.diffWeek( "2009-01-01", "2009-02-01") // 傳回 5

下列範例傳回現行日期至 2010 年開始相距的週數:

BirtDateTime.diffWeek( BirtDateTime.today(), "2010-01-01" );

下列範例傳回 ProjectStart 與 ProjectComplete 欄位中的值相距的週數:

BirtDateTime.diffWeek( row["ProjectStart"], row["ProjectComplete"] )

BirtDateTime.diffYear

這個函數會傳回兩個日期間相距的年數。年的計算方式是從第二個日期的年份值扣除第一個日期的年份值。例如,如果第一個日期是 2009-01-01,第二個日期是 2009-12-31,函數會傳回 0。如果第一個日期是 2008-11-15,第二個日期是 2009-01-15,函數會傳回 1。

語法

integer BirtDateTime.diffYear( Date date1, Date date2 )

參數

date1

代表時間間距開始的日期物件。

date2

代表時間間距結束的日期物件。

傳回

整數。兩個日期間相距的年數。

範例

下列範例傳回兩個特定日期間相距的年數:

BirtDateTime.diffYear( "2005-01-01", "2009-06-01") // 傳回 4

下列範例傳回 HireDate 欄位與現行日期中每一個值相距的年數:

BirtDateTime.diffYear( row["HireDate"], BirtDateTime.today() )

BirtDateTime.diffYear

這個函數會傳回兩個日期間相距的年數。年的計算方式是從第二個日期的年份值扣除第一個日期的年份值。例如,如果第一個日期是 2009-01-01,第二個日期是 2009-12-31,函數會傳回 0。如果第一個日期是 2008-11-15,第二個日期是 2009-01-15,函數會傳回 1。

語法

integer BirtDateTime.diffYear( Date date1, Date date2 )

參數

date1

代表時間間距開始的日期物件。

date2

代表時間間距結束的日期物件。

傳回

整數。兩個日期間相距的年數。

範例

下列範例傳回兩個特定日期間相距的年數:

BirtDateTime.diffYear( "2005-01-01", "2009-06-01") // 傳回 4

下列範例傳回 HireDate 欄位與現行日期中每一個值相距的年數:

BirtDateTime.diffYear( row["HireDate"], BirtDateTime.today() )

BirtDateTime.firstDayOfMonth

這個函數會傳回輸入日期所屬的月份的第一天的日期。

語法

Date BirtDateTime.firstDayOfMonth( Date date)

參數

date

要從中取得月份的日期物件。

傳回

Date 物件。給定日期之月份的第一天。

範例

下列範例顯示針對特定日期所傳回的月份值:

BirtDateTime.firstDayOfMonth( "2009-02-15" ) // returns 2009-02-01

BirtDateTime.firstDayOfQuarter

這個函數會傳回輸入日期所屬季份的第一天的日期。

語法

Date BirtDateTime.firstDayOfQuarter( Date date)

參數

date

要從中取得季週份的日期物件。

傳回

Date 物件。給定日期之季份的第一天。

範例

下列範例顯示針對特定日期所傳回的季份值:

BirtDateTime.firstDayOfQuarter( "2009-02-15" ) // returns 2009-01-01

BirtDateTime.firstDayOfWeek

這個函數會傳回輸入日期所屬星期的第一天的日期,一律為星期日。

語法

Date BirtDateTime.firstDayOfWeek( Date date)

參數

date

要從中取得週份的日期物件。

傳回

Date 物件。給定日期之星期的第一天。

範例

下列範例顯示針對特定日期所傳回的週份值:

BirtDateTime.firstDayOfWeek( "2009-02-15" ) // returns 2009-02-15

BirtDateTime.firstDayOfYear

這個函數會傳回輸入日期所屬年份的第一天的日期。

語法

Date BirtDateTime.firstDayOfYear( Date date)

參數

date

要從中取得年份的日期物件。

傳回

Date 物件。給定日期之年份的第一天。

範例

下列範例顯示針對特定日期所傳回的年份值:

BirtDateTime.firstDayOfYear( "2009-02-15" ) // returns 2009-01-01

BirtDateTime.month

這個函數會傳回給定日期的月份。視您指定的選項而定,函數會以數字、完整月份名稱或縮寫月份名稱來傳回該月份。月份名稱會因語言環境而有區別。

語法

string BirtDateTime.month( Date date, integer option )

參數

date

要從中取得月份的日期物件。

option

整數。選用性的項目。代表要傳回之月份格式的一個數字。請使用下列其中一個值:

*
*
*

如果您省略這個引數,函數會以數字來傳回月份。

傳回

String。給定日期的月份。

範例

下列範例顯示針對特定日期所傳回的月份值:

BirtDateTime.month( "2009-02-15" ) // 傳回 2
BirtDateTime.month( "2009-02-15", 2 ) // 傳回 February
BirtDateTime.month( "2009-02-15", 3) // 傳回 Feb

下列範例傳回現行日期的月份:

BirtDateTime.month( (BirtDateTime.today() )

BirtDateTime.now

這個函數會傳回現行日期與時間,例如 2009-02-02 2:05 PM。

語法

Date BirtDateTime.now( )

傳回

Date 物件。現行日期與時間。

範例

下列範例傳回從現行日期與時間算起至聖誕節的時數:

BirtDateTime.diffHour( BirtDateTime.now(), "2009-12-25" )

BirtDateTime.quarter

這個函數會傳回一個 1 到 4 的數字,來代表該給定日期所屬的季份。第一季起自 1 月 1 日。

語法

integer BirtDateTime.quarter( Date date )

參數

date

要從中取得季份號碼的日期物件。

傳回

整數。給定日期的季份號碼。

範例

下列範例顯示針對特定日期傳回的季份號碼:

BirtDateTime.quarter( "2009-02-15" ) // 傳回 1
BirtDateTime.quarter( "2009-07-10" ) // 傳回 3

下列範例傳回 CloseDate 欄位中每一個值的季份號碼:

BirtDateTime.quarter( row["CloseDate"] )

下列範例傳回現行日期的季份號碼:

BirtDateTime.quarter( (BirtDateTime.today() )

BirtDateTime.today

這個函數會傳回現行日期,包括午夜的時間值,例如,2009-02-02 12:00 AM。

語法

Date BirtDateTime.today( )

傳回

Date 物件。內含午夜時間值的現行日期。

範例

下列範例傳回從現行日期算起至聖誕節的天數:

BirtDateTime.diffDay( BirtDateTime.today(), "2009-12-25" )

下列範例會計算 HireDate 資料欄位中的每一個值到現行日期的年數。

BirtDateTime.diffYear( [HireDate], BirtDateTime.today() )

BirtDateTime.week

這個函數會傳回一個從 1 到 52 的數字,來代表該給定日期的週數。

語法

integer BirtDateTime.week( date )

參數

date

要從中取得週數的日期物件。

傳回

整數。給定日期的週數。

範例

下列範例顯示針對特定日期傳回的週數:

BirtDateTime.week( "2009-02-15" ) // 傳回 8
BirtDateTime.week( "2009-10-12" ) // 傳回 42

下列範例傳回 CloseDate 欄位中每一個值的週數:

BirtDateTime.week( row["CloseDate"] )

下列範例傳回現行日期的週數:

BirtDateTime.week( (BirtDateTime.today() )

BirtDateTime.weekDay

這個函數會傳回給定日期的星期別。視您指定的選項而定,函數會以數字、完整星期名稱或縮寫星期名稱來傳回該星期別。星期名稱會因語言環境而有區別。

語法

string BirtDateTime.weekDay( Date date, integer option )

參數

date

要從中取得星期別的日期物件。

option

整數。選用性的項目。代表傳回格式的一個數字。請使用下列其中一個值:

*
*
*
*
*

如果您省略這個引數,函數會採用選項 1。

傳回

String。給定日期的星期別。

範例

下列範例顯示針對特定日期所傳回的星期值:

BirtDateTime.weekDay( "2009-02-02" ) // 傳回 2
BirtDateTime.weekDay( "2009-02-02", 2 ) // 傳回 1
BirtDateTime.weekDay( "2009-02-02", 4 ) // 傳回 Monday

下列範例傳回現行日期的星期別:

BirtDateTime.weekDay( (BirtDateTime.today() )

BirtDateTime.year

這個函數會傳回給定日期的四位數年份值。例如,如果日期是 2009-01-19,函數會傳回 2009。

語法

integer BirtDateTime.year( date )

參數

date

要從中取得年份的日期物件。

傳回

整數。給定日期的四位數年份值。

範例

下列範例傳回 HireDate 欄位中每一個值的年份:

BirtDateTime.year( row["HireDate"] )

下列範例傳回現行日期的年份:

BirtDateTime.year( (BirtDateTime.today())

© Copyright Actuate Corporation 2013