Class BirtDuration
The BirtDuration class provides functions to get parts of time periods, or durations, used in XML documents. The durations are specified in the following form:
PnYnMnDTnHnMnS
where
*P indicates the period (required).
*nY indicates the number of years.
*nM indicates the number of months.
*nD indicates the number of days.
*T indicates the start of a time section (required if the duration includes hours, minutes, or seconds).
*nH indicates the number of hours.
*nM indicates the number of minutes.
*nS indicates the number of seconds.
For example, the following value indicates a duration of 2 years, 3 months, and 5 days:
P2Y3M5D
The following value indicates a duration of 10 hours:
PT10H
The BirtDuration class is static. The application cannot create instances of the class.
BirtDuration.add
This function adds two durations together, and returns the sum.
Syntax
string BirtDuration.add(string lexicalDuration1, string lexicalDuration2)
Parameters
lexicalDuration1
String. The first duration to add.
lexicalDuration2
String. The second duration to add.
Returns
String. The sum of the two input durations.
Examples
The following example adds two durations:
BirtDuration.add("P1Y3M", "P13M") // returns P2Y4M
BirtDuration.addTo
This function adds a duration to a specified date object.
Syntax
Date BirtDuration.add(string lexicalDuration, Date date)
Parameters
lexicalDuration
String. The duration to add.
date
Date object. The date and time to modify.
Returns
Date object. The date advanced by the duration.
Examples
The following example adds one year to today’s date and time:
var today = new Date();
var annualDate = BirtDuration.addTo(today, "P1Y")
BirtDuration.compare
This function tests if a duration is the same, greater than, or less than another duration.
Syntax
integer BirtDuration.compare(string lexicalDuration1, string lexicalDuration2)
Parameters
lexicalDuration1
String. The first duration to use in the comparison.
lexicalDuration2
String. The second duration to use in the comparison.
Returns
Integer. Partial order relation between the two durations. Returns 1 if the first duration is greater, 0 if they are equal and -1 if the second duration is greater.
Examples
The following expressions compare the lengths of specific durations:
BirtDuration.compare("P1Y", "P12M"); // returns 0
BirtDuration.compare( "P3M" , "P100D" ) // returns -1
BirtDuration.compare( "PT25H" , "P1D" ) // returns 1
BirtDuration.day
This function returns the days value of a given duration.
Syntax
integer BirtDuration.day( string lexicalDuration )
Parameter
lexicalDuration
String. A duration from which to get the days value.
Returns
An integer that represents the days value of the specified duration.
Examples
The following examples show the day values returned for specific durations:
BirtDuration.day( "P1Y15DT12H" ) // returns 15
BirtDuration.day( "P5Y2M" ) // returns 0
BirtDuration.getSign
This function returns the sign of a duration.
Syntax
integer BirtDuration.getSign( string lexicalDuration )
Parameters
lexicalDuration
String. The duration to analyze.
Returns
Integer. The sign of the duration as a multiplier. Returns 1 for a positive duration, -1 for a negative duration, and 0 for null or 0 value.
Examples
The following expression analyzes the sings of a specific duration:
BirtDuration.getSign("P0Y"); // returns 0
BirtDuration.getSign("-P8Y2M3D"); // returns -1
BirtDuration.hour
This function returns the hours value of a given duration.
Syntax
integer BirtDuration.hour( string lexicalDuration )
Parameter
lexicalDuration
String. A duration from which to get the hours value.
Returns
An integer that represents the hours value of the specified duration.
Examples
The following examples show the hour values returned for specific durations:
BirtDuration.hour( "P1Y15DT12H" ) // returns 12
BirtDuration.hour( "P5Y2M" ) // returns 0
BirtDuration.isLongerThan
This function tests if a duration is longer than another duration. Sometimes the order relationship between certain durations cannot be determined, for example, one month (P1M) and 30 days (P30D), or one year (P1Y) and 365 days (P365D). In cases such as these, the function returns false.
Syntax
boolean BirtDuration.isLongerThan( string lexicalDuration1, string lexicalDuration2 )
Parameters
lexicalDuration1
String. The first duration to use in the comparison.
lexicalDuration2
String. The second duration to use in the comparison.
Returns
Boolean. True if the first duration is longer than the second duration; returns false otherwise.
Examples
The following expressions compare the lengths of specific durations:
BirtDuration.isLongerThan( "P1Y3M" , "P13M" ) // returns true
BirtDuration.isLongerThan( "P2M" , "P62D" ) // returns false
BirtDuration.isLongerThan( "PT25H" , "P1D" ) // returns true
BirtDuration.isShorterThan
This function tests if a duration is shorter than another duration. Sometimes the order relationship between certain durations cannot be determined, for example, one month (P1M) and 30 days (P30D), or one year (P1Y) and 365 days (P365D). In cases such as these, the function returns false.
Syntax
boolean BirtDuration.isShorterThan( string lexicalDuration1, string lexicalDuration2 )
Parameters
lexicalDuration1
String. The first duration to use in the comparison.
lexicalDuration2
String. The second duration to use in the comparison.
Returns
Boolean. True if the first duration is shorter than the second duration; returns false otherwise.
Examples
The following expressions compare the lengths of specific durations:
BirtDuration.isShorterThan( "P1Y3M" , "P13M" ) // returns false
BirtDuration.isShorterThan( "P2M" , "P62D" ) // returns false
BirtDuration.isShorterThan( "PT25H" , "P1D" ) // returns false
BirtDuration.isShorterThan( "P27D" , "P1M" ) // returns true
BirtDuration.minute
This function returns the minutes value of a given duration.
Syntax
integer BirtDuration.minute( string lexicalDuration )
Parameter
lexicalDuration
String. A duration from which to get the minutes value.
Returns
Integer. A number that represents the minutes value of the specified duration.
Examples
The following examples show the minutes values returned for specific durations:
BirtDuration.minute( "P1Y15DT12H30M45S" ) // returns 30
BirtDuration.minute( "P5Y2M8DT15H" ) // returns 0
BirtDuration.month
This function returns the months value of a given duration.
Syntax
integer BirtDuration.month( string lexicalDuration )
Parameter
lexicalDuration
String. A duration from which to get the months value.
Returns
Integer. A number that represents the months value of the specified duration.
Examples
The following examples show the month values returned for specific durations:
BirtDuration.month( "P1Y3M15DT12H30M45S" ) // returns 3
BirtDuration.month( "P5Y8DT15H" ) // returns 0
BirtDuration.multiply
This function returns the product of a duration and a regular number.
Syntax
string BirtDuration.multiply( string lexicalDuration, integer factor )
Parameter
lexicalDuration
String. A duration to multiply.
factor
Integer. A regular number to multiply.
Returns
String. The product of the input duration and the factor.
Examples
The following examples show the products returned for a specific duration and factor:
BirtDuration.multiply( "P1Y3M15DT12H30M45S", 1)
// returns P1Y3M15DT12H30M45S
BirtDuration.multiply( "P5Y8DT15H", 0) // returns P0Y0DT0H
BirtDuration.negate
This function returns the negative value of a duration.
Syntax
string BirtDuration.negate( string lexicalDuration )
Parameter
lexicalDuration
String. A duration to negate.
Returns
String. The negative value of the input duration.
Examples
The following examples show the negative result from a specific duration:
BirtDuration.negate( "P1Y3M15DT12H30M45S")
// returns -P1Y3M15DT12H30M45S
BirtDuration.second
This function returns the seconds value of a given duration.
Syntax
integer BirtDuration.second( string lexicalDuration )
Parameter
lexicalDuration
String. A duration from which to get the seconds value.
Returns
Integer. A number that represents the seconds value of the specified duration.
Examples
The following examples show the seconds values returned for specific durations:
BirtDuration.second( "P1Y3M15DT12H30M45S" ) // returns 5
BirtDuration.second( "P5Y8DT15H" ) // returns 0
BirtDuration.subtract
This function subtracts a duration from another duration.
Syntax
string BirtDuration.subtract( string lexicalDuration1, string lexicalDuration2 )
Parameters
lexicalDuration1
String. The duration to subtract from.
lexicalDuration2
String. The duration subtracted from lexicalDuration1.
Returns
String. The difference of the two input durations.
Examples
The following example subtracts two durations:
BirtDuration.subtract("P1Y3M", "P13M") // returns P0Y2M
BirtDuration.timeInMills
This function returns the number of milliseconds in a given duration, from a specified start date. The number of milliseconds in a duration can change depending on the start date. For example, a duration of one month can be 28, 29, 30, or 31 days, depending on the start date. If the start date is January 1, the function calculates the milliseconds between January 1 and February 1 (excluding February 1), which equals 2678400000 milliseconds or 31 days. If the start date is February 1, 2009 (a leap year), the function calculates the milliseconds between February 1 and March 1, which equals 2505600000 milliseconds or 29 days.
Syntax
Number BirtDuration.timeInMills( string lexicalDuration, Date startDate )
Parameters
lexicalDuration
String. A duration whose length in milliseconds to get.
startDate
Date object. Represents the start date.
Returns
Number object. The number of milliseconds in the specified duration.
Examples
The following examples show the number of milliseconds returned for specific durations and start dates:
BirtDuration.timeInMills( "P1Y3M10D" , "2009-01-01" ) // returns 40172400000
BirtDuration.timeInMills( "P1Y3M10D" , "2008-01-01" ) // returns 40258800000
BirtDuration.timeInMills( "PT6H45M20S" , "2009-01-01" ) // returns 24320000
BirtDuration.year
This function returns the year value of a given duration.
Syntax
integer BirtDuration.year( string lexicalDuration )
Parameter
lexicalDuration
String. A duration from which to get the year value.
Returns
Integer. A number that represents the year value of the specified duration.
Examples
The following examples show the year values returned for specific durations:
BirtDuration.year( "P1Y3M15DT12H30M45S" ) // returns 1
BirtDuration.year( "P8DT15H" ) // returns 0