Cookbook example showing how to do Hijri days adjustments (without custom calendar)

[khawarizmus]

This PR implements the AdjustableHijriTemporal class for customizing Hijri date display.

This class allows for adjustment of Hijri dates by shifting days forward or backward. It's designed to:

• Help users synchronize displayed Hijri dates with their local Hijri calendar.
• Facilitate the use of alternative Hijri calendar epochs.

Key points:

• It adjusts the display of Hijri dates without modifying the underlying calendar system.
• The adjustment is a simple day shift and does not alter month lengths or other calendar rules.
• This approach is useful for visual alignment but does not implement comprehensive calendar customization or detailed Hijri calendar variants.

Notes to maintainers: The implementation uses composition instead of inheritance and I have made it so that one class can accommodate for PlainDate, PlainDateTime and ZonedDateTime as such the class doesn't implement the following functions:

• with the exception of toPlainYearMonth and toPlainMonthDay that exist in all the Temporal objects aforementioned. the rest of toX functions are not implemented here and would like to hear your thoughts on how the implementation would look like. for example how would toZonedDateTime behave on a ZonedDateTime underlying object.
• from and fromX where not implemented because of the same complexity mentioned above. but if there is an agreement on how they should behave I can proceed with the implementation.

[ptomato]

Thanks for the example!

You had some questions, I'll try to answer them here:

with the exception of toPlainYearMonth and toPlainMonthDay that exist in all the Temporal objects aforementioned. the rest of toX functions are not implemented here and would like to hear your thoughts on how the implementation would look like. for example how would toZonedDateTime behave on a ZonedDateTime underlying object.

If you don't need them directly, I'd consider leaving them out. If you do need them, then I'd suggest to decide first whether e.g. toZonedDateTime should return Temporal.ZonedDateTime or AdjustableHijriTemporal with underlying ZonedDateTime. I could imagine good reasons for either one.

The question of how would toZonedDateTime behave on a ZonedDateTime underlying object, I'd say it depends on your use case. It could return the same object or it could throw.

from and fromX where not implemented because of the same complexity mentioned above. but if there is an agreement on how they should behave I can proceed with the implementation.

Same, if you don't need them directly, I'd consider leaving them out. I'd say this example is meant as a starting point for readers to customize for their own use cases, not as an API specification that they must implement. The AdjustableHijriTemporal constructor seems pretty comprehensive to me; if you want to construct an AdjustableHijriTemporal object from a string or property bag, there's always the option of new AdjustableHijriTemporal(Temporal.PlainDate.from(...), ...).

If readers need a from() method that behaves differently, they can write it according to their use cases, or simplify the problem by splitting AdjustableHijriTemporal into separate PlainDate/PlainDateTime/ZonedDateTime classes, or whatever.

[ptomato]

Thanks for finishing up the description page. The one thing missing was a link from the main cookbook page. I've added this and will merge it now.