docs: document what the C prayer time fields and formatters do at high latitude - #30
Merged
Merged
Conversation
…h latitude The formatter reference described neither of the two cases a caller actually has to handle, and the struct reference implied every field lands inside a single day. A field can be non-finite, because above roughly 66 degrees the Sun may never reach the altitude an event is defined by. A field can also fall below 0 or at or above 24, because the fajr and isha high-latitude fallback returns such values, which means the event is on the previous or the next calendar day. The second is the one worth warning about. A reader who converts a field into a timestamp and reduces it into 0 to 24 first will silently place the event on the wrong day, because the double is the only thing carrying the offset. Also records the formatter contract added upstream in libmuslim#57. Values outside 0 to 24 are reduced onto the clock face, so 25.075 renders as 01:05 and -0.104 as 23:54, and non-finite values render as --:-- and --:--:--. Both sentinels fit the buffer sizes already documented, so those are unchanged. Every rendered value quoted here was checked against the header rather than written from the description.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to libmuslim#57, which changed formatter behaviour, and libmuslim#56, which is still open.
What was missing
The formatter reference described neither of the two cases a caller actually has to handle, and the
struct PrayerTimesreference implied every field lands inside a single day. It said only that a field is decimal hours in local time, with17.75as the example.Both assumptions break at high latitude.
A field can be non-finite, because above roughly 66 degrees the Sun may never reach the altitude an event is defined by. A field can also fall below 0 or at or above 24, because the fajr and isha high-latitude fallback returns such values.
The part worth warning about
The out-of-range case is the dangerous one, and it is dangerous in a way that looks like tidying up.
A reader who converts a field into a timestamp and helpfully reduces it into 0 to 24 first will silently place the event on the wrong calendar day. The double is the only thing carrying that offset. Nothing else in the API expresses it, which is exactly why libmuslim#56 is still open.
So the caution tells the reader to check
isfinite()and to keep the whole value when building an instant, rather than normalising it.Formatter contract
Now documented, matching the upstream change.
Both sentinels fit inside the buffer sizes already documented, 6 and 9 bytes, so those figures are unchanged and correct as they stand.
Every rendered value quoted was checked against the header rather than written from the description.
Not changed here, but worth a decision
The C overview still pins its download to
v0.1.0.That tag predates the formatter fix, so a reader who follows the quick start gets a header where a high-latitude time can print as
00:-6. The docs would then describe behaviour the downloaded file does not have. Either av0.1.1tag or a change to the pin resolves it, and both are your call rather than something to slip into a docs PR.The Rust and Dart pages need no change. Both already document their non-finite handling,
Error::NonFiniteResultandPrayerTimesUnavailable, and neither exposes the raw out-of-range double.Site builds clean.