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) • 15.1 kB
TypeScript
/**
* Copyright(c) 2014 ABB Switzerland Ltd.
*
* Olsen Timezone Database container
*/
import { DateFunctions } from "./javascript";
/**
* Used for methods that take a timestamp as separate year/month/... components
*/
export interface TimeComponentOpts {
/**
* Year, default 1970
*/
year?: number;
/**
* Month 1-12, default 1
*/
month?: number;
/**
* Day of month 1-31, default 1
*/
day?: number;
/**
* Hour of day 0-23, default 0
*/
hour?: number;
/**
* Minute 0-59, default 0
*/
minute?: number;
/**
* Second 0-59, default 0
*/
second?: number;
/**
* Millisecond 0-999, default 0
*/
milli?: number;
}
/**
* Timestamp represented as separate year/month/... components
*/
export interface TimeComponents {
/**
* Year
*/
year: number;
/**
* Month 1-12
*/
month: number;
/**
* Day of month 1-31
*/
day: number;
/**
* Hour 0-23
*/
hour: number;
/**
* Minute
*/
minute: number;
/**
* Second
*/
second: number;
/**
* Millisecond 0-999
*/
milli: number;
}
/**
* Day-of-week. Note the enum values correspond to JavaScript day-of-week:
* Sunday = 0, Monday = 1 etc
*/
export declare enum WeekDay {
Sunday = 0,
Monday = 1,
Tuesday = 2,
Wednesday = 3,
Thursday = 4,
Friday = 5,
Saturday = 6
}
/**
* Time units
*/
export declare enum TimeUnit {
Millisecond = 0,
Second = 1,
Minute = 2,
Hour = 3,
Day = 4,
Week = 5,
Month = 6,
Year = 7,
/**
* End-of-enum marker, do not use
*/
MAX = 8
}
/**
* Approximate number of milliseconds for a time unit.
* A day is assumed to have 24 hours, a month is assumed to equal 30 days
* and a year is set to 360 days (because 12 months of 30 days).
*
* @param unit Time unit e.g. TimeUnit.Month
* @returns The number of milliseconds.
* @throws timezonecomplete.Argument.Unit for invalid unit
*/
export declare function timeUnitToMilliseconds(unit: TimeUnit): number;
/**
* Time unit to lowercase string. If amount is specified, then the string is put in plural form
* if necessary.
* @param unit The unit
* @param amount If this is unequal to -1 and 1, then the result is pluralized
* @throws timezonecomplete.Argument.Unit for invalid time unit
*/
export declare function timeUnitToString(unit: TimeUnit, amount?: number): string;
/**
* Convert a string to a numeric TimeUnit. Case-insensitive; time units can be singular or plural.
* @param s
* @throws timezonecomplete.Argument.S for invalid string
*/
export declare function stringToTimeUnit(s: string): TimeUnit;
/**
* @return True iff the given year is a leap year.
* @throws timezonecomplete.Argument.Year if year is not integer
*/
export declare function isLeapYear(year: number): boolean;
/**
* The days in a given year
* @throws timezonecomplete.Argument.Year if year is not integer
*/
export declare function daysInYear(year: number): number;
/**
* @param year The full year
* @param month The month 1-12
* @return The number of days in the given month
* @throws timezonecomplete.Argument.Year if year is not integer
* @throws timezonecomplete.Argument.Month for invalid month number
*/
export declare function daysInMonth(year: number, month: number): number;
/**
* Returns the day of the year of the given date [0..365]. January first is 0.
*
* @param year The year e.g. 1986
* @param month Month 1-12
* @param day Day of month 1-31
* @throws timezonecomplete.Argument.Year for invalid year (non-integer)
* @throws timezonecomplete.Argument.Month for invalid month
* @throws timezonecomplete.Argument.Day for invalid day of month
*/
export declare function dayOfYear(year: number, month: number, day: number): number;
/**
* Returns the last instance of the given weekday in the given month
*
* @param year The year
* @param month the month 1-12
* @param weekDay the desired week day 0-6
* @return the last occurrence of the week day in the month
* @throws timezonecomplete.Argument.Year for invalid year (non-integer)
* @throws timezonecomplete.Argument.Month for invalid month
* @throws timezonecomplete.Argument.WeekDay for invalid week day
*/
export declare function lastWeekDayOfMonth(year: number, month: number, weekDay: WeekDay): number;
/**
* Returns the first instance of the given weekday in the given month
*
* @param year The year
* @param month the month 1-12
* @param weekDay the desired week day
* @return the first occurrence of the week day in the month
* @throws timezonecomplete.Argument.Year for invalid year (non-integer)
* @throws timezonecomplete.Argument.Month for invalid month
* @throws timezonecomplete.Argument.WeekDay for invalid week day
*/
export declare function firstWeekDayOfMonth(year: number, month: number, weekDay: WeekDay): number;
/**
* Returns the nth instance of the given weekday in the given month; throws if not found
*
* @param year The year
* @param month the month 1-12
* @param weekDay the desired week day
* @param dayInstance the desired week day instance, n
* @return the first occurrence of the week day in the month
* @throws timezonecomplete.Argument.Year for invalid year (non-integer)
* @throws timezonecomplete.Argument.Month for invalid month
* @throws timezonecomplete.Argument.WeekDay for invalid week day
* @throws timezonecomplete.Arugment.DayInstance for invalid day instance (not 1-5)
* @throws timezonecomplete.NotFound if the month has no such instance (i.e. 5th instance, where only 4 exist)
*/
export declare function nthWeekDayOfMonth(year: number, month: number, weekDay: WeekDay, dayInstance: number): number;
/**
* Returns the day-of-month that is on the given weekday and which is >= the given day; throws if not found
* @throws timezonecomplete.Argument.Year for invalid year (non-integer)
* @throws timezonecomplete.Argument.Month for invalid month
* @throws timezonecomplete.Argument.Day for invalid day of month
* @throws timezonecomplete.Argument.WeekDay for invalid week day
* @throws timezonecomplete.NotFound if the month has no such day
*/
export declare function weekDayOnOrAfter(year: number, month: number, day: number, weekDay: WeekDay): number;
/**
* Returns the day-of-month that is on the given weekday and which is <= the given day.
* @throws timezonecomplete.Argument.Year for invalid year (non-integer)
* @throws timezonecomplete.Argument.Month for invalid month
* @throws timezonecomplete.Argument.Day for invalid day of month
* @throws timezonecomplete.Argument.WeekDay for invalid week day
* @throws timezonecomplete.NotFound if the month has no such day
*/
export declare function weekDayOnOrBefore(year: number, month: number, day: number, weekDay: WeekDay): number;
/**
* The week of this month. There is no official standard for this, but we assume the same rules for the weekNumber:
* week 1 is the week that has the 4th day of the month in it
*
* @param year The year
* @param month The month [1-12]
* @param day The day [1-31]
* @return Week number [1-5]
* @throws timezonecomplete.Argument.Year for invalid year (non-integer)
* @throws timezonecomplete.Argument.Month for invalid month
* @throws timezonecomplete.Argument.Day for invalid day of month
*/
export declare function weekOfMonth(year: number, month: number, day: number): number;
/**
* The week of this month, based on counting calendar weeks. Unlike weekOfMonth() the first day of the month is
* always week 1, and no days count as the last week of the previous month. The week number returned can be from 1-6,
* as a month can span up to 6 different weeks on the calendar. The first day of the week, i.e. when the week number
* increases, is customizable, and defaults to Monday.
*
* @param year The year
* @param month The month [1-12]
* @param day The day [1-31]
* @param weekStartDay The week day to use as the start of the week
* @return Week number [1-6]
* @throws timezonecomplete.Argument.Year for invalid year (non-integer)
* @throws timezonecomplete.Argument.Month for invalid month
* @throws timezonecomplete.Argument.Day for invalid day of month
*/
export declare function calendarWeekInMonth(year: number, month: number, day: number, weekStartDay?: WeekDay): number;
/**
* Returns the weekday instance number in the month for the given date
*
* @param year The year
* @param month The month [1-12]
* @param day The day [1-31]
* @return Instance number [1-5]
* @throws timezonecomplete.Argument.Year for invalid year (non-integer)
* @throws timezonecomplete.Argument.Month for invalid month
* @throws timezonecomplete.Argument.Day for invalid day of month
*/
export declare function weekDayInstanceInMonth(year: number, month: number, day: number): number;
/**
* The ISO 8601 week number for the given date. Week 1 is the week
* that has January 4th in it, and it starts on Monday.
* See https://en.wikipedia.org/wiki/ISO_week_date
*
* @param year Year e.g. 1988
* @param month Month 1-12
* @param day Day of month 1-31
* @return Week number 1-53
* @throws timezonecomplete.Argument.Year for invalid year (non-integer)
* @throws timezonecomplete.Argument.Month for invalid month
* @throws timezonecomplete.Argument.Day for invalid day of month
*/
export declare function weekNumber(year: number, month: number, day: number): number;
/**
* Convert a unix milli timestamp into a TimeT structure.
* This does NOT take leap seconds into account.
* @throws timezonecomplete.Argument.UnixMillis for non-integer `unixMillis` parameter
*/
export declare function unixToTimeNoLeapSecs(unixMillis: number): TimeComponents;
/**
* Convert a year, month, day etc into a unix milli timestamp.
* This does NOT take leap seconds into account.
*
* @param year Year e.g. 1970
* @param month Month 1-12
* @param day Day 1-31
* @param hour Hour 0-23
* @param minute Minute 0-59
* @param second Second 0-59 (no leap seconds)
* @param milli Millisecond 0-999
* @throws timezonecomplete.Argument.Year for invalid year
* @throws timezonecomplete.Argument.Month for invalid month
* @throws timezonecomplete.Argument.Day for invalid day of month
* @throws timezonecomplete.Argument.Hour for invalid hour
* @throws timezonecomplete.Argument.Minute for invalid minute
* @throws timezonecomplete.Argument.Second for invalid second
* @throws timezonecomplete.Argument.Milli for invalid milliseconds
*/
export declare function timeToUnixNoLeapSecs(year: number, month: number, day: number, hour: number, minute: number, second: number, milli: number): number;
export declare function timeToUnixNoLeapSecs(components: TimeComponentOpts): number;
/**
* Return the day-of-week.
* This does NOT take leap seconds into account.
* @throws timezonecomplete.Argument.UnixMillis for invalid `unixMillis` argument
*/
export declare function weekDayNoLeapSecs(unixMillis: number): WeekDay;
/**
* N-th second in the day, counting from 0
* @throws timezonecomplete.Argument.Hour for invalid hour
* @throws timezonecomplete.Argument.Minute for invalid minute
* @throws timezonecomplete.Argument.Second for invalid second
*/
export declare function secondOfDay(hour: number, minute: number, second: number): number;
/**
* Basic representation of a date and time
*/
export declare class TimeStruct {
/**
* Returns a TimeStruct from the given year, month, day etc
*
* @param year Year e.g. 1970
* @param month Month 1-12
* @param day Day 1-31
* @param hour Hour 0-23
* @param minute Minute 0-59
* @param second Second 0-59 (no leap seconds)
* @param milli Millisecond 0-999
* @throws timezonecomplete.Argument.Year for invalid year
* @throws timezonecomplete.Argument.Month for invalid month
* @throws timezonecomplete.Argument.Day for invalid day of month
* @throws timezonecomplete.Argument.Hour for invalid hour
* @throws timezonecomplete.Argument.Minute for invalid minute
* @throws timezonecomplete.Argument.Second for invalid second
* @throws timezonecomplete.Argument.Milli for invalid milliseconds
*/
static fromComponents(year?: number, month?: number, day?: number, hour?: number, minute?: number, second?: number, milli?: number): TimeStruct;
/**
* Create a TimeStruct from a number of unix milliseconds
* (backward compatibility)
* @throws timezonecomplete.Argument.UnixMillis for non-integer milliseconds
*/
static fromUnix(unixMillis: number): TimeStruct;
/**
* Create a TimeStruct from a JavaScript date
*
* @param d The date
* @param df Which functions to take (getX() or getUTCX())
* @throws nothing
*/
static fromDate(d: Date, df: DateFunctions): TimeStruct;
/**
* Returns a TimeStruct from an ISO 8601 string WITHOUT time zone
* @throws timezonecomplete.Argument.S if `s` is not a proper iso string
*/
static fromString(s: string): TimeStruct;
/**
* The time value in unix milliseconds
*/
private _unixMillis;
get unixMillis(): number;
/**
* The time value in separate year/month/... components
*/
private _components;
get components(): TimeComponents;
/**
* Constructor
*
* @param unixMillis milliseconds since 1-1-1970
* @throws timezonecomplete.Argument.UnixMillis for non-integer unixMillis
*/
constructor(unixMillis: number);
/**
* Constructor
*
* @param components Separate timestamp components (year, month, ...)
* @throws timezonecomplete.Argument.Components if `components` is not an object
* @throws timezonecomplete.Argument.* for invalid components (* = Year, Month, Day, Hour, Minute, Second, Milli)
*/
constructor(components: TimeComponentOpts);
get year(): number;
get month(): number;
get day(): number;
get hour(): number;
get minute(): number;
get second(): number;
get milli(): number;
/**
* The day-of-year 0-365
* @throws nothing
*/
yearDay(): number;
/**
* Equality function
* @param other
* @throws TypeError if other is not an Object
*/
equals(other: TimeStruct): boolean;
/**
* @throws nothing
*/
valueOf(): number;
/**
* @throws nothing
*/
clone(): TimeStruct;
/**
* Validate a timestamp. Filters out non-existing values for all time components
* @returns true iff the timestamp is valid
* @throws nothing
*/
validate(): boolean;
/**
* ISO 8601 string YYYY-MM-DDThh:mm:ss.nnn
* @throws nothing
*/
toString(): string;
}
/**
* Binary search
* @param array Array to search
* @param compare Function that should return < 0 if given element is less than searched element etc
* @returns The insertion index of the element to look for
* @throws TypeError if arr is not an array
* @throws whatever `compare()` throws
*/
export declare function binaryInsertionIndex<T>(arr: T[], compare: (a: T) => number): number;