timezonecomplete
Version:
DateTime, TimeZone, Duration and Period library aimed at providing a consistent and complete date-time interface, away from the original JavaScript Date class.
422 lines (421 loc) • 14.7 kB
TypeScript
/**
* Copyright(c) 2014 ABB Switzerland Ltd.
*
* Time duration
*/
import { TimeUnit } from "./basics";
/**
* Construct a time duration
* @param n Number of years (may be fractional or negative)
* @return A duration of n years
* @throws timezonecomplete.Argument.Amount if n is not a finite number
*/
export declare function years(n: number): Duration;
/**
* Construct a time duration
* @param n Number of months (may be fractional or negative)
* @return A duration of n months
* @throws timezonecomplete.Argument.Amount if n is not a finite number
*/
export declare function months(n: number): Duration;
/**
* Construct a time duration
* @param n Number of days (may be fractional or negative)
* @return A duration of n days
* @throws timezonecomplete.Argument.Amount if n is not a finite number
*/
export declare function days(n: number): Duration;
/**
* Construct a time duration
* @param n Number of hours (may be fractional or negative)
* @return A duration of n hours
* @throws timezonecomplete.Argument.Amount if n is not a finite number
*/
export declare function hours(n: number): Duration;
/**
* Construct a time duration
* @param n Number of minutes (may be fractional or negative)
* @return A duration of n minutes
* @throws timezonecomplete.Argument.Amount if n is not a finite number
*/
export declare function minutes(n: number): Duration;
/**
* Construct a time duration
* @param n Number of seconds (may be fractional or negative)
* @return A duration of n seconds
* @throws timezonecomplete.Argument.Amount if n is not a finite number
*/
export declare function seconds(n: number): Duration;
/**
* Construct a time duration
* @param n Number of milliseconds (may be fractional or negative)
* @return A duration of n milliseconds
* @throws timezonecomplete.Argument.Amount if n is not a finite number
*/
export declare function milliseconds(n: number): Duration;
/**
* Time duration which is represented as an amount and a unit e.g.
* '1 Month' or '166 Seconds'. The unit is preserved through calculations.
*
* It has two sets of getter functions:
* - second(), minute(), hour() etc, singular form: these can be used to create string representations.
* These return a part of your string representation. E.g. for 2500 milliseconds, the millisecond() part would be 500
* - seconds(), minutes(), hours() etc, plural form: these return the total amount represented in the corresponding unit.
*/
export declare class Duration {
/**
* Allow not using instanceof
*/
kind: string;
/**
* Given amount in constructor
*/
private _amount;
/**
* Unit
*/
private _unit;
/**
* Construct a time duration
* @param amount Number of years (may be fractional or negative)
* @return A duration of n years
* @throws timezonecomplete.Argument.Amount if n is not a finite number
*/
static years(amount: number): Duration;
/**
* Construct a time duration
* @param amount Number of months (may be fractional or negative)
* @return A duration of n months
* @throws timezonecomplete.Argument.Amount if n is not a finite number
*/
static months(amount: number): Duration;
/**
* Construct a time duration
* @param amount Number of days (may be fractional or negative)
* @return A duration of n days
* @throws timezonecomplete.Argument.Amount if n is not a finite number
*/
static days(amount: number): Duration;
/**
* Construct a time duration
* @param amount Number of hours (may be fractional or negative)
* @return A duration of n hours
* @throws timezonecomplete.Argument.Amount if n is not a finite number
*/
static hours(amount: number): Duration;
/**
* Construct a time duration
* @param amount Number of minutes (may be fractional or negative)
* @return A duration of n minutes
* @throws timezonecomplete.Argument.Amount if n is not a finite number
*/
static minutes(amount: number): Duration;
/**
* Construct a time duration
* @param amount Number of seconds (may be fractional or negative)
* @return A duration of n seconds
* @throws timezonecomplete.Argument.Amount if n is not a finite number
*/
static seconds(amount: number): Duration;
/**
* Construct a time duration
* @param amount Number of milliseconds (may be fractional or negative)
* @return A duration of n milliseconds
* @throws timezonecomplete.Argument.Amount if n is not a finite number
*/
static milliseconds(amount: number): Duration;
/**
* Construct a time duration of 0 milliseconds
* @throws nothing
*/
constructor();
/**
* Construct a time duration from a string in one of two formats:
* 1) [-]hhhh[:mm[:ss[.nnn]]] e.g. '-01:00:30.501'
* 2) amount and unit e.g. '-1 days' or '1 year'. The unit may be in singular or plural form and is case-insensitive
* @throws timezonecomplete.Argument.S for invalid string
*/
constructor(s: string);
/**
* Construct a duration from an amount and a time unit.
* @param amount Number of units
* @param unit A time unit i.e. TimeUnit.Second, TimeUnit.Hour etc. Default Millisecond.
* @throws timezonecomplete.Argument.Amount if `amount` is not a finite number
* @throws timezonecomplete.Argument.Unit for invalid `unit`
*/
constructor(amount: number, unit?: TimeUnit);
/**
* @return another instance of Duration with the same value.
* @throws nothing
*/
clone(): Duration;
/**
* Returns this duration expressed in different unit (positive or negative, fractional).
* This is precise for Year <-> Month and for time-to-time conversion (i.e. Hour-or-less to Hour-or-less).
* It is approximate for any other conversion
* @throws nothing
*/
as(unit: TimeUnit): number;
/**
* Convert this duration to a Duration in another unit. You always get a clone even if you specify
* the same unit.
* This is precise for Year <-> Month and for time-to-time conversion (i.e. Hour-or-less to Hour-or-less).
* It is approximate for any other conversion
* @throws nothing
*/
convert(unit: TimeUnit): Duration;
/**
* The entire duration in milliseconds (negative or positive)
* For Day/Month/Year durations, this is approximate!
* @throws nothing
*/
milliseconds(): number;
/**
* The millisecond part of the duration (always positive)
* For Day/Month/Year durations, this is approximate!
* @return e.g. 400 for a -01:02:03.400 duration
* @throws nothing
*/
millisecond(): number;
/**
* The entire duration in seconds (negative or positive, fractional)
* For Day/Month/Year durations, this is approximate!
* @return e.g. 1.5 for a 1500 milliseconds duration
* @throws nothing
*/
seconds(): number;
/**
* The second part of the duration (always positive)
* For Day/Month/Year durations, this is approximate!
* @return e.g. 3 for a -01:02:03.400 duration
* @throws nothing
*/
second(): number;
/**
* The entire duration in minutes (negative or positive, fractional)
* For Day/Month/Year durations, this is approximate!
* @return e.g. 1.5 for a 90000 milliseconds duration
* @throws nothing
*/
minutes(): number;
/**
* The minute part of the duration (always positive)
* For Day/Month/Year durations, this is approximate!
* @return e.g. 2 for a -01:02:03.400 duration
* @throws nothing
*/
minute(): number;
/**
* The entire duration in hours (negative or positive, fractional)
* For Day/Month/Year durations, this is approximate!
* @return e.g. 1.5 for a 5400000 milliseconds duration
* @throws nothing
*/
hours(): number;
/**
* The hour part of a duration. This assumes that a day has 24 hours (which is not the case
* during DST changes).
* @throws nothing
*/
hour(): number;
/**
* The hour part of the duration (always positive).
* Note that this part can exceed 23 hours, because for
* now, we do not have a days() function
* For Day/Month/Year durations, this is approximate!
* @return e.g. 25 for a -25:02:03.400 duration
* @throws nothing
*/
wholeHours(): number;
/**
* The entire duration in days (negative or positive, fractional)
* This is approximate if this duration is not in days!
* @throws nothing
*/
days(): number;
/**
* The day part of a duration. This assumes that a month has 30 days.
* @throws nothing
*/
day(): number;
/**
* The entire duration in days (negative or positive, fractional)
* This is approximate if this duration is not in Months or Years!
* @throws nothing
*/
months(): number;
/**
* The month part of a duration.
* @throws nothing
*/
month(): number;
/**
* The entire duration in years (negative or positive, fractional)
* This is approximate if this duration is not in Months or Years!
* @throws nothing
*/
years(): number;
/**
* Non-fractional positive years
* @throws nothing
*/
wholeYears(): number;
/**
* Amount of units (positive or negative, fractional)
* @throws nothing
*/
amount(): number;
/**
* The unit this duration was created with
* @throws nothing
*/
unit(): TimeUnit;
/**
* Sign
* @return "-" if the duration is negative
* @throws nothing
*/
sign(): string;
/**
* Approximate if the durations have units that cannot be converted
* @return True iff (this < other)
* @throws nothing
*/
lessThan(other: Duration): boolean;
/**
* Approximate if the durations have units that cannot be converted
* @return True iff (this <= other)
* @throws nothing
*/
lessEqual(other: Duration): boolean;
/**
* Similar but not identical
* Approximate if the durations have units that cannot be converted
* @return True iff this and other represent the same time duration
* @throws nothing
*/
equals(other: Duration): boolean;
/**
* Similar but not identical
* Returns false if we cannot determine whether they are equal in all time zones
* so e.g. 60 minutes equals 1 hour, but 24 hours do NOT equal 1 day
*
* @return True iff this and other represent the same time duration
* @throws nothing
*/
equalsExact(other: Duration): boolean;
/**
* Same unit and same amount
* @throws nothing
*/
identical(other: Duration): boolean;
/**
* Returns true if this is a non-zero length duration
*/
nonZero(): boolean;
/**
* Returns true if this is a zero-length duration
*/
zero(): boolean;
/**
* Approximate if the durations have units that cannot be converted
* @return True iff this > other
* @throws nothing
*/
greaterThan(other: Duration): boolean;
/**
* Approximate if the durations have units that cannot be converted
* @return True iff this >= other
* @throws nothing
*/
greaterEqual(other: Duration): boolean;
/**
* Approximate if the durations have units that cannot be converted
* @return The minimum (most negative) of this and other
* @throws nothing
*/
min(other: Duration): Duration;
/**
* Approximate if the durations have units that cannot be converted
* @return The maximum (most positive) of this and other
* @throws nothing
*/
max(other: Duration): Duration;
/**
* Multiply with a fixed number.
* Approximate if the durations have units that cannot be converted
* @return a new Duration of (this * value)
* @throws nothing
*/
multiply(value: number): Duration;
/**
* Divide by a unitless number. The result is a Duration, e.g. 1 year / 2 = 0.5 year
* The result is approximate if this duration as a unit that cannot be converted to a number (e.g. 1 month has variable length)
* @return a new Duration of (this / value)
* @throws timezonecomplete.Argument.Value if value is 0 or non-finite
*/
divide(value: number): Duration;
/**
* Divide this Duration by a Duration. The result is a unitless number e.g. 1 year / 1 month = 12
* The result is approximate if this duration as a unit that cannot be converted to a number (e.g. 1 month has variable length)
* @return a new Duration of (this / value)
* @throws timezonecomplete.Argument.Value if the duration is 0
*/
divide(value: Duration): number;
/**
* Add a duration.
* @return a new Duration of (this + value) with the unit of this duration
* @throws nothing
*/
add(value: Duration): Duration;
/**
* Subtract a duration.
* @return a new Duration of (this - value) with the unit of this duration
* @throws nothing
*/
sub(value: Duration): Duration;
/**
* Return the absolute value of the duration i.e. remove the sign.
* @throws nothing
*/
abs(): Duration;
/**
* String in [-]hhhh:mm:ss.nnn notation. All fields are always present except the sign.
* @throws nothing
*/
toFullString(): string;
/**
* String in [-]hhhh:mm[:ss[.nnn]] notation.
* @param full If true, then all fields are always present except the sign. Otherwise, seconds and milliseconds
* are chopped off if zero
* @throws nothing
*/
toHmsString(full?: boolean): string;
/**
* String in ISO 8601 notation e.g. 'P1M' for one month or 'PT1M' for one minute
* @throws nothing
*/
toIsoString(): string;
/**
* String representation with amount and unit e.g. '1.5 years' or '-1 day'
* @throws nothing
*/
toString(): string;
/**
* The valueOf() method returns the primitive value of the specified object.
* @throws nothing
*/
valueOf(): number;
/**
* Return this % unit, always positive
* @throws nothing
*/
private _part;
}
/**
* Checks if a given object is of type Duration. Note that it does not work for sub classes. However, use this to be robust
* against different versions of the library in one process instead of instanceof
* @param value Value to check
* @throws nothing
*/
export declare function isDuration(value: any): value is Duration;