@hebcal/hdate
Version:
converts between Hebrew and Gregorian dates using Rata Die (R.D.) algorithm by Dershowitz and Reingold
439 lines (438 loc) • 18.2 kB
TypeScript
import { MonthName, SimpleHebrewDate } from './hdateBase';
declare const UNITS_DAY = "day";
declare const UNITS_WEEK = "week";
declare const UNITS_MONTH = "month";
declare const UNITS_YEAR = "year";
type ToFlexibleUnit<U extends TimeUnit> = U | `${U}s` | Uppercase<U> | Uppercase<`${U}s`> | Capitalize<U> | Capitalize<`${U}s`> | (U extends 'month' ? 'M' : FirstChar<U>);
type FirstChar<S extends string> = S extends `${infer FirstLetter}${string}` ? FirstLetter : never;
type Capitalize<S extends string> = S extends `${infer FirstLetter}${infer Rest}` ? `${Uppercase<FirstLetter>}${Rest}` : never;
type TimeUnit = typeof UNITS_DAY | typeof UNITS_WEEK | typeof UNITS_MONTH | typeof UNITS_YEAR;
/** Units that can be passed to `add()` and similar methods. */
export type FlexibleTimeUnit = ToFlexibleUnit<TimeUnit>;
/**
* A `HDate` represents a Hebrew calendar date.
*
* An instance of this class encapsulates a date in the Hebrew calendar system.
* It consists of a year, month, and day, without any associated time or location data.
* The Hebrew calendar is a lunisolar calendar, meaning it is based on both lunar and solar cycles.
*
* A Hebrew date internally stores three numbers:
* - year: The Hebrew year (1-9999). Counted from the traditional Hebrew date of creation (3761 BCE in the Gregorian calendar)
* - month: The Hebrew month (1-13). Month 1 is Nisan, month 7 is Tishrei. There are 12 months in a regular year and 13 months in a leap year.
* - day: The day of the month (1-30)
*
* This class uses Rata Die to convert between the Hebrew and Gregorian calendars.
*
* To calculate times of day, use `Zmanim` class from `@hebcal/core`
* @see {@link https://en.wikipedia.org/wiki/Rata_Die | Rata Die}
* @see {@link https://hebcal.github.io/api/core/classes/Zmanim.html | Zmanim}
*/
export declare class HDate {
/** Hebrew year, 1-9999 */
yy: number;
/** Hebrew month of year (1=NISAN, 7=TISHREI) */
mm: number;
/** Hebrew day within the month (1-30) */
dd: number;
/** absolute Rata Die (R.D.) days */
rd?: number;
/**
* Create a Hebrew date. There are 3 basic forms for the `HDate()` constructor.
*
* 1. No parameters - represents the current Hebrew date at time of instantiation
* 2. One parameter
* * `Date` - represents the Hebrew date corresponding to the Gregorian date using
* local time. Hours, minutes, seconds and milliseconds are ignored.
* * `HDate` - clones a copy of the given Hebrew date
* * `number` - Converts absolute R.D. days to Hebrew date.
* R.D. 1 == the imaginary date January 1, 1 (Gregorian)
* 3. Three parameters: Hebrew day, Hebrew month, Hebrew year. Hebrew day should
* be a number between 1-30, Hebrew month can be a number or string, and
* Hebrew year is always a number.
* @example
* import {HDate, months} from '@hebcal/hdate';
*
* const hd1 = new HDate();
* const hd2 = new HDate(new Date(2008, 10, 13));
* const hd3 = new HDate(15, 'Cheshvan', 5769);
* const hd4 = new HDate(15, months.CHESHVAN, 5769);
* const hd5 = new HDate(733359); // ==> 15 Cheshvan 5769
* const monthName = 'אייר';
* const hd6 = new HDate(5, monthName, 5773);
* @param [day] - Day of month (1-30) if a `number`.
* If a `Date` is specified, represents the Hebrew date corresponding to the
* Gregorian date using local time.
* If an `HDate` is specified, clones a copy of the given Hebrew date.
* @param [month] - Hebrew month of year (1=NISAN, 7=TISHREI)
* @param [year] - Hebrew year
*/
constructor(day?: number | Date | HDate | SimpleHebrewDate | undefined, month?: number | string, year?: number);
/**
* Returns the Hebrew year of this Hebrew date
* @returns an integer >= 1
* @example
* const hd = new HDate(new Date(2008, 10, 13)); // 15 Cheshvan 5769
* hd.getFullYear(); // 5769
*/
getFullYear(): number;
/**
* Returns `true` if this Hebrew date occurs during a Hebrew leap year
* @example
* const hd = new HDate(new Date(2008, 10, 13)); // 15 Cheshvan 5769
* hd.isLeapYear(); // false
*/
isLeapYear(): boolean;
/**
* Returns the Hebrew month (1=NISAN, 7=TISHREI) of this Hebrew date
* @returns an integer 1-13
* @example
* const hd = new HDate(new Date(2008, 10, 13)); // 15 Cheshvan 5769
* hd.getMonth(); // 8
*/
getMonth(): number;
/**
* The Tishrei-based month of this Hebrew date. 1 is Tishrei, 7 is Nisan, 13 is Elul in a leap year
* @returns an integer 1-13
* @example
* const hd = new HDate(new Date(2008, 10, 13)); // 15 Cheshvan 5769
* hd.getTishreiMonth(); // 2
*/
getTishreiMonth(): number;
/**
* Number of days in the month of this Hebrew date (29 or 30)
* @returns an integer 29-30
* @example
* const hd = new HDate(new Date(2008, 10, 13)); // 15 Cheshvan 5769
* hd.daysInMonth(); // 29
*/
daysInMonth(): number;
/**
* Gets the day within the month (1-30)
* @returns an integer 1-30
* @example
* const hd = new HDate(new Date(2008, 10, 13)); // 15 Cheshvan 5769
* hd.getDate(); // 15
*/
getDate(): number;
/**
* Returns the day of the week for this Hebrew date,
* where 0 represents Sunday, 1 represents Monday, 6 represents Saturday.
*
* For the day of the month, see `getDate()`
* @returns an integer 0-6
* @example
* const hd = new HDate(new Date(2008, 10, 13)); // 15 Cheshvan 5769
* hd.getDate(); // 4
*/
getDay(): number;
/**
* Converts this Hebrew date to the corresponding Gregorian date.
*
* The returned `Date` object will be in the local (i.e. host system) time zone.
* Hours, minutes, seconds and milliseconds will all be zero.
*
* Note that this function returns the daytime portion of the date.
* For example, the 15th of Cheshvan 5769 began at sundown on
* 12 November 2008 and continues through 13 November 2008. This
* function would return only the date 13 November 2008.
* @example
* const hd = new HDate(15, 'Cheshvan', 5769);
* const date = hd.greg(); // 13 November 2008
* const year = date.getFullYear(); // 2008
* const monthNum = date.getMonth() + 1; // 11
* const day = date.getDate(); // 13
*/
greg(): Date;
/**
* Converts from Hebrew date representation to R.D. (Rata Die) fixed days.
* R.D. 1 is the imaginary date Monday, January 1, 1 (Gregorian).
* Note also that R.D. = Julian Date − 1,721,424.5
* @see {@link https://en.wikipedia.org/wiki/Rata_Die | Rata Die}
* @example
* const hd = new HDate(15, 'Cheshvan', 5769);
* hd.abs(); // 733359
*/
abs(): number;
/**
* Converts Hebrew date to R.D. (Rata Die) fixed days.
* R.D. 1 is the imaginary date Monday, January 1, 1 on the Gregorian
* Calendar.
* @param year Hebrew year
* @param month Hebrew month (1=NISAN, 7=TISHREI)
* @param day Hebrew date (1-30)
* @example
* import {HDate, months} from '@hebcal/hdate';
* HDate.hebrew2abs(5769, months.CHESHVAN, 15); // 733359
*/
static hebrew2abs(year: number, month: number, day: number): number;
/**
* Returns a transliterated Hebrew month name, e.g. `'Elul'` or `'Cheshvan'`.
* @example
* const hd = new HDate(new Date(2008, 10, 13)); // 15 Cheshvan 5769
* hd.getMonthName(); // 'Cheshvan'
*/
getMonthName(): MonthName;
/**
* Renders this Hebrew date as a translated or transliterated string,
* including ordinal e.g. `'15th of Cheshvan, 5769'`.
* @example
* import {HDate, months} from '@hebcal/hdate';
*
* const hd = new HDate(15, months.CHESHVAN, 5769);
* console.log(hd.render('en')); // '15th of Cheshvan, 5769'
* console.log(hd.render('he')); // '15 חֶשְׁוָן, 5769'
* console.log(hd.render('en', false)); // '15th of Cheshvan'
* console.log(hd.render('he', false)); // '15 חֶשְׁוָן'
* @param [locale] Optional locale name (defaults to active locale).
* @param [showYear=true] Display year (defaults to true).
* @see {@link Locale}
*/
render(locale?: string, showYear?: boolean): string;
/**
* Renders this Hebrew date in Hebrew gematriya, regardless of locale.
* @example
* import {HDate, months} from '@hebcal/hdate';
* const hd = new HDate(15, months.CHESHVAN, 5769);
* hd.renderGematriya(); // 'ט״ו חֶשְׁוָן תשס״ט'
* hd.renderGematriya(true); // 'ט״ו חשון תשס״ט'
*/
renderGematriya(suppressNikud?: boolean): string;
/**
* Returns an `HDate` corresponding to the specified day of week
* **before** this Hebrew date
* @example
* new HDate(new Date('Wednesday February 19, 2014')).before(6).greg() // Sat Feb 15 2014
* @param dayOfWeek day of week: Sunday=0, Saturday=6
*/
before(dayOfWeek: number): HDate;
/**
* Returns an `HDate` corresponding to the specified day of week
* **on or before** this Hebrew date
* @example
* new HDate(new Date('Wednesday February 19, 2014')).onOrBefore(6).greg() // Sat Feb 15 2014
* new HDate(new Date('Saturday February 22, 2014')).onOrBefore(6).greg() // Sat Feb 22 2014
* new HDate(new Date('Sunday February 23, 2014')).onOrBefore(6).greg() // Sat Feb 22 2014
* @param dayOfWeek day of week: Sunday=0, Saturday=6
*/
onOrBefore(dayOfWeek: number): HDate;
/**
* Returns an `HDate` corresponding to the specified day of week
* **nearest** to this Hebrew date
* @example
* new HDate(new Date('Wednesday February 19, 2014')).nearest(6).greg() // Sat Feb 22 2014
* new HDate(new Date('Tuesday February 18, 2014')).nearest(6).greg() // Sat Feb 15 2014
* @param dayOfWeek day of week: Sunday=0, Saturday=6
*/
nearest(dayOfWeek: number): HDate;
/**
* Returns an `HDate` corresponding to the specified day of week
* **on or after** this Hebrew date
* @example
* new HDate(new Date('Wednesday February 19, 2014')).onOrAfter(6).greg() // Sat Feb 22 2014
* new HDate(new Date('Saturday February 22, 2014')).onOrAfter(6).greg() // Sat Feb 22 2014
* new HDate(new Date('Sunday February 23, 2014')).onOrAfter(6).greg() // Sat Mar 01 2014
* @param dayOfWeek day of week: Sunday=0, Saturday=6
*/
onOrAfter(dayOfWeek: number): HDate;
/**
* Returns an `HDate` corresponding to the specified day of week
* **after** this Hebrew date
* @example
* new HDate(new Date('Wednesday February 19, 2014')).after(6).greg() // Sat Feb 22 2014
* new HDate(new Date('Saturday February 22, 2014')).after(6).greg() // Sat Mar 01 2014
* new HDate(new Date('Sunday February 23, 2014')).after(6).greg() // Sat Mar 01 2014
* @param dayOfWeek day of week: Sunday=0, Saturday=6
*/
after(dayOfWeek: number): HDate;
/**
* Returns the next Hebrew date
* @example
* const hd = new HDate(new Date(2008, 10, 13)); // 15 Cheshvan 5769
* hd.next(); // '16 Cheshvan 5769'
*/
next(): HDate;
/**
* Returns the previous Hebrew date
* @example
* const hd = new HDate(new Date(2008, 10, 13)); // 15 Cheshvan 5769
* hd.prev(); // '14 Cheshvan 5769'
*/
prev(): HDate;
/**
* Returns a cloned `HDate` object with a specified amount of time added
*
* Units are case insensitive, and support plural and short forms.
* Note, short forms are case sensitive.
*
* | Unit | Shorthand | Description
* | --- | --- | --- |
* | `day` | `d` | days |
* | `week` | `w` | weeks |
* | `month` | `M` | months |
* | `year` | `y` | years |
*/
add(amount: number | string, units?: FlexibleTimeUnit): HDate;
/**
* Returns a cloned `HDate` object with a specified amount of time subracted
*
* Units are case insensitive, and support plural and short forms.
* Note, short forms are case sensitive.
*
* | Unit | Shorthand | Description
* | --- | --- | --- |
* | `day` | `d` | days |
* | `week` | `w` | weeks |
* | `month` | `M` | months |
* | `year` | `y` | years |
* @example
* import {HDate, months} from '@hebcal/hdate';
*
* const hd1 = new HDate(15, months.CHESHVAN, 5769);
* const hd2 = hd1.add(1, 'weeks'); // 7 Kislev 5769
* const hd3 = hd1.add(-3, 'M'); // 30 Av 5768
*/
subtract(amount: number, units?: FlexibleTimeUnit): HDate;
/**
* Returns the difference in days between the two given HDates.
*
* The result is positive if `this` date is comes chronologically
* after the `other` date, and negative
* if the order of the two dates is reversed.
*
* The result is zero if the two dates are identical.
* @example
* import {HDate, months} from '@hebcal/hdate';
*
* const hd1 = new HDate(25, months.KISLEV, 5770);
* const hd2 = new HDate(15, months.CHESHVAN, 5769);
* const days = hd1.deltaDays(hd2); // 394
* @param other Hebrew date to compare
*/
deltaDays(other: HDate): number;
/**
* Compares this Hebrew date to another date, returning `true` if the dates match.
* @param other Hebrew date to compare
* @example
* const hd1 = new HDate(new Date(2008, 10, 13));
* const hd2 = new HDate(15, 'Cheshvan', 5769);
* hd1.isSameDate(hd2); // true
*/
isSameDate(other: HDate): boolean;
/**
* Returns a string representation of this Hebrew date using English transliterations
* @example
* const hd = new HDate(new Date(2008, 10, 13)); // 15 Cheshvan 5769
* hd.toString(); // '15 Cheshvan 5769'
*/
toString(): string;
/**
* Returns true if Hebrew year is a leap year
* @param year Hebrew year
* @example
* HDate.isLeapYear(5783); // false
* HDate.isLeapYear(5784); // true
*/
static isLeapYear(year: number): boolean;
/**
* Number of months in this Hebrew year (either 12 or 13 depending on leap year)
* @param year Hebrew year
* @example
* HDate.monthsInYear(5783); // 12
* HDate.monthsInYear(5784); // 13
*/
static monthsInYear(year: number): number;
/**
* Number of days in Hebrew month in a given year (29 or 30)
* @param month Hebrew month (e.g. months.TISHREI)
* @param year Hebrew year
* @example
* import {HDate, months} from '@hebcal/hdate';
* HDate.daysInMonth(months.CHESHVAN, 5769); // 29
*/
static daysInMonth(month: number, year: number): number;
/**
* Returns a transliterated string name of Hebrew month in year,
* for example 'Elul' or 'Cheshvan'.
* @param month Hebrew month (e.g. months.TISHREI)
* @param year Hebrew year
* @example
* import {HDate, months} from '@hebcal/hdate';
* HDate.getMonthName(months.CHESHVAN, 5769); // 'Cheshvan'
*/
static getMonthName(month: number, year: number): MonthName;
/**
* Returns the Hebrew month number (NISAN=1, TISHREI=7)
* @param month A number, or Hebrew month name string
* @example
* import {HDate, months} from '@hebcal/hdate';
* HDate.monthNum(months.CHESHVAN); // 8
* HDate.monthNum('Cheshvan'); // 8
* HDate.monthNum('חשון'); // 8
*/
static monthNum(month: number | string): number;
/**
* Number of days in the Hebrew year.
* Regular years can have 353, 354, or 355 days.
* Leap years can have 383, 384, or 385 days.
* @param year Hebrew year
* @example
* HDate.daysInYear(5783); // 355
* HDate.daysInYear(5784); // 383
*/
static daysInYear(year: number): number;
/**
* true if Cheshvan is long in Hebrew year
* @param year Hebrew year
* @example
* HDate.longCheshvan(5783); // true
* HDate.longCheshvan(5784); // false
*/
static longCheshvan(year: number): boolean;
/**
* true if Kislev is short in Hebrew year
* @param year Hebrew year
* @example
* HDate.shortKislev(5783); // false
* HDate.shortKislev(5784); // true
*/
static shortKislev(year: number): boolean;
/**
* Converts Hebrew month string name to numeric
* @example
* import {HDate, months} from '@hebcal/hdate';
* HDate.monthFromName(months.CHESHVAN); // 8
* HDate.monthFromName('Cheshvan'); // 8
* HDate.monthFromName('חשון'); // 8
*/
static monthFromName(monthName: string | number): number;
/**
* Convenience function for determining the R.D. date
* near a specified R.D. date, corresponding to the specified day of week.
*
* Note: Applying this function to d+6 gives us the `dayOfWeek` on or after an
* absolute day d. Similarly, applying it to d+3 gives the `dayOfWeek` nearest to
* absolute date d, applying it to d-1 gives the `dayOfWeek` previous to absolute
* date d, and applying it to d+7 gives the `dayOfWeek` following absolute date d.
* @param dayOfWeek day of week: Sunday=0, Saturday=6
*/
static dayOnOrBefore(dayOfWeek: number, absdate: number): number;
/**
* Tests if the object is an instance of `HDate`
* @example
* HDate.isHDate(new HDate()); // true
* HDate.isHDate(new Date()); // false
* HDate.isHDate(null); // false
* HDate.isHDate(12345); // false
* HDate.isHDate('15 Cheshvan 5769'); // false
*/
static isHDate(obj: any): boolean;
/**
* Construct a new instance of `HDate` from a Gematriya-formatted string
* @example
* HDate.fromGematriyaString('כ״ז בְּתַמּוּז תשפ״ג') // 27 Tamuz 5783
* HDate.fromGematriyaString('כ׳ סיון תש״ד') // 20 Sivan 5704
* HDate.fromGematriyaString('ה׳ אִיָיר תש״ח') // 5 Iyyar 5708
*/
static fromGematriyaString(str: string, currentThousands?: number): HDate;
}
export {};