src/hdate.h(3)

okay bestie, welcome to src/hdate.h, section 3 of the libhdate C language manual 💅 this is the header file that makes the whole Hebrew calendar thing go, and we are gonna go through every single line of it together. grab a snack. 🍓

---

🌸 NAME 🌸

src/hdate.h —

libhdate C language header. that's it, that's the name, she's simple and she knows it ✨

---

🎀 SYNOPSIS 🎀

💖 Data Structures 💖

• struct hdate_struct — libhdate Hebrew date struct. the main character of this whole file 👑

🦋 Defines 🦋

• #define HDATE_DIASPORA_FLAG -1 — use diaspora dates and holydays flag
• #define HDATE_ISRAEL_FLAG 0 — use israel dates and holydays flag
• #define HDATE_SHORT_FLAG -1 — use short strings flag
• #define HDATE_LONG_FLAG 0 — use long strings flag
• #define HEBREW_NUMBER_BUFFER_SIZE 17 — for hdate_get_int_string_ and hdate_get_int_wstring
• #define HEBREW_WNUMBER_BUFFER_SIZE 9
• #define HDATE_STRING_INT 0 — for function hdate_string: identifies string type: integer
• #define HDATE_STRING_DOW 1 — for function hdate_string: identifies string type: day of week
• #define HDATE_STRING_PARASHA 2 — for function hdate_string: identifies string type: parasha
• #define HDATE_STRING_HMONTH 3 — for function hdate_string: identifies string type: hebrew_month
• #define HDATE_STRING_GMONTH 4 — for function hdate_string: identifies string type: gregorian_month
• #define HDATE_STRING_HOLIDAY 5 — for function hdate_string: identifies string type: holiday
• #define HDATE_STRING_OMER 6
• #define HDATE_STRING_SHORT 1 — for function hdate_string: use short form, if one exists
• #define HDATE_STRING_LONG 0 — for function hdate_string: use long form
• #define HDATE_STRING_HEBREW 1 — for function hdate_string: use embedded hebrew string
• #define HDATE_STRING_LOCAL 0 — for function hdate_string: use local locale string

⭐ Functions ⭐

• hdate_struct * hdate_set_gdate (hdate_struct *h, int d, int m, int y) — compute date structure from the Gregorian date
• hdate_struct * hdate_set_hdate (hdate_struct *h, int d, int m, int y) — compute date structure from the Hebrew date
• hdate_struct * hdate_set_jd (hdate_struct *h, int jd) — compute date structure from the Julian day
• char * hdate_get_format_date (hdate_struct const *h, int diaspora, int s) — Return a string, with the hebrew date.
• int hdate_get_parasha (hdate_struct const *h, int diaspora) — get the number of hebrew parasha.
• int hdate_get_holyday (hdate_struct const *h, int diaspora) — get the number of hebrew holiday.
• char * hdate_get_int_string (int n) — convert an integer to hebrew string.
• char * hdate_get_day_string (int day, int s) — Return a static string, with name of week day.
• char * hdate_get_month_string (int month, int s) — Return a static string, with name of month.
• char * hdate_get_hebrew_month_string (int month, int s) — Return a static string, with name of hebrew month.
• char * hdate_get_holyday_string (int holyday, int s) — Name of hebrew holiday.
• char * hdate_get_parasha_string (int parasha, int s) — Name of Parasha.
• char * hdate_get_omer_string (int omer_day) — Return a static string, with the day in the omer.
• int hdate_get_omer_day (hdate_struct const *h) — Return the day in the omer of the given date.
• int hdate_get_holyday_type (int holyday) — Return number of hebrew holyday type.
• int hdate_get_size_of_hebrew_year (int hebrew_year) — size of hebrew year in days.
• int hdate_days_from_3744 (int hebrew_year) — Days since Tishrey 3744.
• int hdate_get_year_type (int size_of_year, int new_year_dw) — Return Hebrew year type based on size and first week day of year.
• int hdate_gdate_to_jd (int day, int month, int year) — Compute Julian day from Gregorian date.
• int hdate_hdate_to_jd (int day, int month, int year, int *jd_tishrey1, int *jd_tishrey1_next_year) — Compute Julian day from Hebrew day, month and year.
• void hdate_jd_to_gdate (int jd, int *day, int *month, int *year) — Converting from the Julian day to the Gregorian date.
• void hdate_jd_to_hdate (int jd, int *day, int *month, int *year, int *jd_tishrey1, int *jd_tishrey1_next_year) — Converting from the Julian day to the Hebrew day.
• int hdate_get_day_of_year (int day, int month, int year) — days from 1 january
• void hdate_get_utc_sun_time_deg (int day, int month, int year, double latitude, double longitude, double deg, int *sunrise, int *sunset) — utc sun times for altitude at a gregorian date
• void hdate_get_utc_sun_time (int day, int month, int year, double latitude, double longitude, int *sunrise, int *sunset) — utc sunrise/set time for a gregorian date
• void hdate_get_utc_sun_time_full (int day, int month, int year, double latitude, double longitude, int *sun_hour, int *first_light, int *talit, int *sunrise, int *midday, int *sunset, int *first_stars, int *three_stars) — utc sunrise/set time for a gregorian date
• int hdate_get_gday (hdate_struct const *h) — get the Gregorian day of the month
• int hdate_get_gmonth (hdate_struct const *h) — get the Gregorian month
• int hdate_get_gyear (hdate_struct const *h) — get the Gregorian year
• int hdate_get_hday (hdate_struct const *h) — get the Hebrew day of the month
• int hdate_get_hmonth (hdate_struct const *h) — get the Hebrew month
• int hdate_get_hyear (hdate_struct const *h) — get the Hebrew year
• int hdate_get_day_of_the_week (hdate_struct const *h) — get the day of the week
• int hdate_get_size_of_year (hdate_struct const *h) — get the size of the hebrew year
• int hdate_get_new_year_day_of_the_week (hdate_struct const *h) — get the new year day of the week
• int hdate_get_julian (hdate_struct const *h) — get the Julian day number
• int hdate_get_days (hdate_struct const *h) — get the number of days passed since 1 tishrey
• int hdate_get_weeks (hdate_struct const *h) — get the number of weeks passed since 1 tishrey
• hdate_struct * new_hdate () — creat a new hdate struct object, must be deleted using delete_hdate.
• hdate_struct * delete_hdate (hdate_struct *h) — delete an hdate struct object.
• char * hdate_get_version_string () — Return a static string, with the package name and version.
• char * hdate_get_translator_string () — name of translator
• int hdate_is_hebrew_locale () — helper function to find hebrew locale
• char * hdate_string (int type_of_string, int index, int short_form, int hebrew_form) — Return string values for hdate information.

---

💜 Detailed Description 💜

libhdate C language header.

libhdate - Hebrew calendar library, the C language header file. periodt. that's the whole vibe of the file — she's a header, she declares things, she does not compute them, and honestly? iconic. 💅

---

🌈 Define Documentation 🌈

💖 #define HDATE_DIASPORA_FLAG -1 💖

use diaspora dates and holydays flag

💖 #define HDATE_ISRAEL_FLAG 0 💖

use israel dates and holydays flag

💖 #define HDATE_SHORT_FLAG -1 💖

use short strings flag

💖 #define HDATE_LONG_FLAG 0 💖

use long strings flag

💖 #define HEBREW_NUMBER_BUFFER_SIZE 17 💖

for hdate_get_int_string_ and hdate_get_int_wstring

Note: How large should the buffer be? Hebrew year 10,999 would be י'תתקצ"ט, eight characters, each two bytes, plus an end-of-string delimiter, equals 17. This could effectively yield a range extending to Hebrew year 11,899, י'א תתצ'ט, due to the extra ק needed for the '900' century. However, for readability, I would want a an extra space at that point between the millennium and the century...

the way the author did the math on this and then immediately went "but actually I want a space there" 😭 fr fr, respect.

💖 #define HEBREW_WNUMBER_BUFFER_SIZE 9 💖

no description, she's mysterious, she said nothing and left 🫶

💖 #define HDATE_STRING_INT 0 💖

for function hdate_string: identifies string type: integer

💖 #define HDATE_STRING_DOW 1 💖

for function hdate_string: identifies string type: day of week

💖 #define HDATE_STRING_PARASHA 2 💖

for function hdate_string: identifies string type: parasha

💖 #define HDATE_STRING_HMONTH 3 💖

for function hdate_string: identifies string type: hebrew_month

💖 #define HDATE_STRING_GMONTH 4 💖

for function hdate_string: identifies string type: gregorian_month

💖 #define HDATE_STRING_HOLIDAY 5 💖

for function hdate_string: identifies string type: holiday

💖 #define HDATE_STRING_OMER 6 💖

another quiet queen, no notes ✨

💖 #define HDATE_STRING_SHORT 1 💖

for function hdate_string: use short form, if one exists

💖 #define HDATE_STRING_LONG 0 💖

for function hdate_string: use long form

💖 #define HDATE_STRING_HEBREW 1 💖

for function hdate_string: use embedded hebrew string

💖 #define HDATE_STRING_LOCAL 0 💖

for function hdate_string: use local locale string

---

🔥 Function Documentation 🔥

🧚 hdate_struct* hdate_set_gdate (hdate_struct *h, intd, intm, inty) 🧚

compute date structure from the Gregorian date

Parameters:

• h pointer this hdate struct.
• d Day of month 1..31
• m Month 1..12 if m or d is 0 return current date.
• y Year in 4 digits e.g. 2001

Returns:

pointer to this hdate struct

🧚 hdate_struct* hdate_set_hdate (hdate_struct *h, intd, intm, inty) 🧚

compute date structure from the Hebrew date

Parameters:

• h pointer this hdate struct.
• d Day of month 1..31
• m Month 1..14 ,(13 - Adar 1, 14 - Adar 2) if m or d is 0 return current date.
• y Year in 4 digits e.g. 5731

Returns:

pointer to this hdate struct

🧚 hdate_struct* hdate_set_jd (hdate_struct *h, intjd) 🧚

compute date structure from the Julian day

Parameters:

• h pointer this hdate struct.
• jd the julian day number.

Returns:

pointer to this hdate struct

🧚 char* hdate_get_format_date (hdate_struct const *h, intdiaspora, ints) 🧚

Return a string, with the hebrew date.

Returns:

NULL pointer upon failure or, upon success, a pointer to a string containing the short ( e.g. '1 Tishrey' ) or long (e.g. 'Tuesday 18 Tishrey 5763 Hol hamoed Sukot' ) formatted date. You must free() the pointer after use.

Parameters:

• h The hdate_struct of the date to print.
• diaspora if true give diaspora holydays
• short_format A short flag (true - returns a short string, false returns a long string).

Warning: This was originally written using a local static string, calling for output to be copied away.

not me reading "you must free() the pointer after use" and feeling the pressure 😭 bestie, free your memory. it's the law. 🫶

🧚 int hdate_get_parasha (hdate_struct const *h, intdiaspora) 🧚

get the number of hebrew parasha.

Parameters:

• h pointer this hdate struct.
• diaspora if true give diaspora readings

Returns:

the number of parasha 1. Bereshit etc.. (55 through 61 are joined strings e.g. Vayakhel Pekudei)

🧚 int hdate_get_holyday (hdate_struct const *h, intdiaspora) 🧚

get the number of hebrew holiday.

Parameters:

• h pointer this hdate struct.
• diaspora if true give diaspora holidays

Returns:

the number of holiday.

🧚 char* hdate_get_int_string (intn) 🧚

convert an integer to hebrew string.

Parameters:

• n The int to convert ( 0 < n < 11000)

Returns:

a string of the hebrew number UTF-8 (logical)

⚠️ Warning — DEPRECATION: this function is literally just a wrapper for hdate_string now, and it's on its way out. 🫠 If you call it, you must free() the memory that the return value points at. Back in the day it used to dump its output into a local static string and politely suggest you copy it somewhere safe — that era is over bestie. [deprecation date 2011-12-28]

---

char* hdate_get_day_string (int day, int s)

Hands you a static string with the name of the weekday. Classic.

• day_of_week — the number of the day, 1..7 (where 1 = sun 🌞).
• short_form — a short flag (true = sun; false = sunday).

⚠️ Warning — DEPRECATION: this function is now just a wrapper for hdate_string, and it is subject to deprecation. [deprecation date 2011-12-28]

---

char* hdate_get_month_string (int month, int s)

Returns a static string with the name of the month. cute.

• month — the number of the month, 1..12 (where 1 = jan).
• short_form — a short flag.

⚠️ Warning — DEPRECATION: this function is now just a wrapper for hdate_string, and it is subject to deprecation. [deprecation date 2011-12-28]

---

char* hdate_get_hebrew_month_string (int month, int s)

Returns a static string with the name of the Hebrew month 💜.

• month — the number of the month, 1..14 (1 = tishre, 13 = adar 1, 14 = adar 2).
• short_form — a short flag.

⚠️ Warning — DEPRECATION: this function is now just a wrapper for hdate_string, and it is subject to deprecation. [deprecation date 2011-12-28]

---

char* hdate_get_holyday_string (int holyday, int s)

Name of the Hebrew holiday ✨.

• holiday — the holiday number.
• short_text — a short flag. 0 = true, !0 = false.

⚠️ Warning — DEPRECATION: this function is now just a wrapper for hdate_string, and it is subject to deprecation. [deprecation date 2011-12-28]

---

char* hdate_get_parasha_string (int parasha, int s)

Name of the Parasha 📖.

• parasha — the number of the Parasha, 1-Bereshit (55 through 61 are joined strings, e.g. Vayakhel Pekudei).
• short_form — a short flag. 0 = true, !0 = false.

⚠️ Warning — DEPRECATION: this function is now just a wrapper for hdate_string, and it is subject to deprecation. [deprecation date 2011-12-28]

---

char* hdate_get_omer_string (int omer_day)

Returns a static string with the day in the omer 🌾.

• omer day — the day in the omer.

Returns: a pointer to a string with the day in the omer. The caller must free() the pointer after use.

⚠️ Warning — DEPRECATION: this function is now just a wrapper for hdate_string, and it is subject to deprecation.

👀 Attention: the prior version of this function returned a pointer to a static string buffer. The current version returns a pointer to a malloc()ed buffer and needs to be free()d after use. No cap. [deprecation date 2011-12-28]

---

int hdate_get_omer_day (hdate_struct const *h)

Tells you which day in the omer a given date falls on.

• h — the hdate_struct of the date to use.

Returns: the day in the omer, starting from 1 (or 0 if not in sfirat ha omer).

---

int hdate_get_holyday_type (int holyday)

Returns the number of the Hebrew holyday type 🎀. Here's the whole roster, bestie:

• 0 — Regular day
• 1 — Yom tov (plus yom kippor)
• 2 — Erev yom kippur
• 3 — Hol hamoed
• 4 — Hanuka and purim
• 5 — Tzomot
• 6 — Independance day and Yom yerushalaim
• 7 — Lag baomer ,Tu beav, Tu beshvat
• 8 — Tzahal and Holocaust memorial days
• 9 — National days

Parameters:

• holyday — the holyday number.

Returns: the number of holyday type.

---

int hdate_get_size_of_hebrew_year (int hebrew_year)

Size of the Hebrew year, in days 📏.

• hebrew_year — the hebrew year.

Returns: size of Hebrew year.

---

int hdate_days_from_3744 (int hebrew_year)

Days since Tishrey 3744.

Author: Amos Shapir 1984 (rev. 1985, 1992) Yaacov Zamir 2003-2005

Parameters:

• hebrew_year — the Hebrew year.

Returns: number of days since 3,1,3744.

---

int hdate_get_year_type (int size_of_year, int new_year_dw)

Returns the Hebrew year type based on the size of the year and the first week day of the year.

Parameters:

• size_of_year — length of year in days.
• new_year_dw — first week day of year.

Returns: the number for year type (1..14).

---

int hdate_gdate_to_jd (int day, int month, int year)

Computes the Julian day from a Gregorian date 🗓️.

Author: Yaacov Zamir (algorithm from Henry F. Fliegel and Thomas C. Van Flandern ,1968)

Parameters:

• day — day of month 1..31.
• month — month 1..12.
• year — year in 4 digits, e.g. 2001.

Returns: the julian day number.

---

int hdate_hdate_to_jd (int day, int month, int year, int *jd_tishrey1, int *jd_tishrey1_next_year)

Computes the Julian day from a Hebrew day, month and year 🔥.

Author: Amos Shapir 1984 (rev. 1985, 1992) Yaacov Zamir 2003-2005

Parameters:

• day — day of month 1..31.
• month — month 1..14 (13 - Adar 1, 14 - Adar 2).
• year — Hebrew year in 4 digits, e.g. 5753.
• jd_tishrey1 — return the julian number of 1 Tishrey this year.
• jd_tishrey1_next_year — return the julian number of 1 Tishrey next year.

Returns: the julian day number.

---

void hdate_jd_to_gdate (int jd, int *day, int *month, int *year)

Converting from the Julian day to the Gregorian date 💫.

Author: Yaacov Zamir (Algorithm, Henry F. Fliegel and Thomas C. Van Flandern ,1968)

Parameters:

• jd — Julian day.
• day — return day of month 1..31.
• month — return month 1..12.
• year — return year in 4 digits, e.g. 2001.

---

void hdate_jd_to_hdate (int jd, int *day, int *month, int *year, int *jd_tishrey1, int *jd_tishrey1_next_year)

Converting from the Julian day to the Hebrew day 🌙.

Author: Yaacov Zamir 2005

Parameters:

• jd — Julian day.
• day — return day of month 1..31.
• month — return month 1..14 (13 - Adar 1, 14 - Adar 2).
• year — return year in 4 digits, e.g. 2001.
• jd_tishrey1 — return the julian number of 1 Tishrey this year.
• jd_tishrey1_next_year — return the julian number of 1 Tishrey next year.

---

int hdate_get_day_of_year (int day, int month, int year)

Days from 1 january.

Parameters:

• day — this day of month.
• month — this month.
• year — this year.

Returns: the days from 1 jan.

---

void hdate_get_utc_sun_time_deg (int day, int month, int year, double latitude, double longitude, double deg, int *sunrise, int *sunset)

UTC sun times for a given altitude at a gregorian date 🌅. Returns the sunset and sunrise times in minutes from 00:00 (utc time) if sun altitude in sunrise is deg degries. This function only works for altitudes the sun realy is. If the sun never gets to this altitude, the returned sunset and sunrise values will be negative. That can happen at low altitude when latitude is nearing the pols in winter times — the sun never goes very high in the sky there, fr.

Parameters:

• day — this day of month.
• month — this month.
• year — this year.
• longitude — longitude to use in calculations.
• latitude — latitude to use in calculations.
• deg — degrees of sun's altitude (0 - Zenith .. 90 - Horizon).
• sunrise — return the utc sunrise in minutes.
• sunset — return the utc sunset in minutes.

---

void hdate_get_utc_sun_time (int day, int month, int year, double latitude, double longitude, int *sunrise, int *sunset)

UTC sunrise/set time for a gregorian date ☀️.

Parameters:

• day — this day of month.
• month — this month.
• year — this year.
• longitude — longitude to use in calculations degrees, negative values are east.
• latitude — latitude to use in calculations degrees, negative values are south.
• sunrise — return the utc sunrise in minutes after midnight (00:00).
• sunset — return the utc sunset in minutes after midnight (00:00).

---

void hdate_get_utc_sun_time_full (int day, int month, int year, double latitude, double longitude, int *sun_hour, int *first_light, int *talit, int *sunrise, int *midday, int *sunset, int *first_stars, int *three_stars)

UTC sunrise/set time for a gregorian date — the full deluxe package 🌈.

Parameters:

• day — this day of month.
• month — this month.
• year — this year.
• longitude — longitude to use in calculations.
• latitude — latitude to use in calculations.
• sun_hour — return the length of shaa zaminit in minutes.
• first_light — return the utc alut ha-shachar in minutes.
• talit — return the utc tphilin and talit in minutes.
• sunrise — return the utc sunrise in minutes.
• midday — return the utc midday in minutes.
• sunset — return the utc sunset in minutes.
• first_stars — return the utc tzeit hacochavim in minutes.
• three_stars — return the utc shlosha cochavim in minutes.

---

int hdate_get_gday (hdate_struct const *h)

Get the Gregorian day of the month.

• h — pointer this hdate struct.

Returns: the Gregorian day of the month, 1..31.

---

int hdate_get_gmonth (hdate_struct const *h)

Get the Gregorian month.

• h — pointer this hdate struct.

Returns: the Gregorian month, jan = 1.

---

int hdate_get_gyear (hdate_struct const *h)

Get the Gregorian year.

• h — pointer this hdate struct.

Returns: the Gregorian year.

---

int hdate_get_hday (hdate_struct const *h)

Get the Hebrew day of the month.

• h — pointer this hdate struct.

Returns: the Hebrew day of the month, 1..30.

---

int hdate_get_hmonth (hdate_struct const *h)

Get the Hebrew month.

• h — pointer this hdate struct.

Returns: the Hebrew month, Tishery = 1 .. Adar I = 13, Adar II = 14.

---

int hdate_get_hyear (hdate_struct const *h)

Get the Hebrew year.

• h — pointer this hdate struct.

Returns: the Hebrew year.

---

int hdate_get_day_of_the_week (hdate_struct const *h)

Get the day of the week 👑.

• h — pointer this hdate struct.

Returns: the the day of the week.

---

int hdate_get_size_of_year (hdate_struct const *h)

Get the size of the hebrew year.

• h — pointer this hdate struct.

Returns: the the size of the hebrew year.

---

int hdate_get_new_year_day_of_the_week (hdate_struct const *h)

Get the new year day of the week 🎊.

• h — pointer this hdate struct.

Returns: the the new year day of the week.

---

int hdate_get_julian (hdate_struct const *h)

Get the Julian day number.

• h — pointer this hdate struct.

Returns: the Julian day number.

---

int hdate_get_days (hdate_struct const *h)

Get the number of days passed since 1 tishrey.

• h — pointer this hdate struct.

Returns: the number of days passed since 1 tishrey.

---

int hdate_get_weeks (hdate_struct const *h)

Get the number of weeks passed since 1 tishrey 🦋.

• h — pointer this hdate struct.

Returns: the number of weeks passed since 1 tishrey.

💫 hdate_struct* new_hdate ()

okay so bestie, this is the glow-up moment — it creates a brand-new hdate struct object ✨. And like, listen: it's not set-and-forget. You gotta delete_hdate it when you're done, no cap, or you're just leaving your memory lying around like laundry on the floor 🙈.

Returns: a new hdate object 💖

---

🗑️ hdate_struct* delete_hdate (hdate_struct *h)

the cleanup era 💅 this one deletes an hdate struct object. bye bestie, you served 🫶

Parameters:

• h — pointer this hdate struct.

---

🏷️ char* hdate_get_version_string ()

gives you a static string with the package name and the version. it's giving name-tag energy 🎀

Returns: a static string, with the package name and version ⭐

---

🌍 char* hdate_get_translator_string ()

the name of the translator, iconic behavior honestly 👑

Returns: a static string with name of translator, or NULL if none.

---

🕵️‍♀️ int hdate_is_hebrew_locale ()

a little helper function that goes snooping around to find out if you're in a hebrew locale. lowkey useful, highkey underrated 🌈

Returns:

• 0 — latin locale
• -1 — hebrew locale

---

🎀 char* hdate_string (inttype_of_string, intindex, intshort_form, inthebrew_form)

this one returns string values for hdate info — it's the main character of this whole page fr fr 🔥

Returns: a pointer to a string containing the information. but bestie, heads up ⚠️: in the cases integers and omer, the strings will NOT be static, and the caller must free() them after use. Returns a null pointer upon failure.

Parameters:

• type_of_string — 0 = integer, 1 = day of week, 2 = parshaot, 3 = hmonth, 4 = gmonth, 5 = holiday, 6 = omer
• index — integer ( 0 < n < 11000 ) day of week ( 0 < n < 8 ) parshaot ( 0 , n < 62 ) hmonth ( 0 < n < 15 ) gmonth ( 0 < n < 13 ) holiday ( 0 < n < 37 ) omer ( 0 < n < 50 )
• short_form — 0 = short format
• hebrew_form — 0 = not hebrew (native/embedded)

---

✍️ Author ✍️

Generated automatically by Doxygen for libhdate C language from the source code. yeah, the robots did the typing, we just did the vibes 🧚

---

and that's the whole page bestie, we ate and left no crumbs 🍓 this was Version 1.4, dated Sun Jan 8 2012, living in src/hdate.h(3) 💜 mwah, go compile something cute 💅✨