File indexing completed on 2024-12-08 09:38:10

0001 /*
0002     This file is part of the kholidays library.
0003 
0004     SPDX-FileCopyrightText: 2004, 2007, 2009 Allen Winter <winter@kde.org>
0005 
0006     SPDX-License-Identifier: LGPL-2.0-or-later
0007 */
0008 
0009 #ifndef KHOLIDAYS_LUNARPHASE_H
0010 #define KHOLIDAYS_LUNARPHASE_H
0011 
0012 #include "kholidays_export.h"
0013 
0014 #include <qobjectdefs.h>
0015 
0016 class QDate;
0017 class QString;
0018 
0019 namespace KHolidays
0020 {
0021 /**
0022   Represents and manages a Lunar Phase
0023 
0024   A Lunar Phase can be one of the following:
0025 
0026    + "new": the moon is not visible; or traditionally: first visible
0027             crescent of the Moon.  For religious purposes, the new
0028             month begins when the first crescent moon can be seen.
0029             Thus, it is impossible to be certain in advance of when
0030             months will begin; in particular, the exact date on which
0031             Ramadan will begin is not known in advance. In Saudi Arabia,
0032             observers are sent up in airplanes if the weather is cloudy
0033             when the new moon is expected.
0034    + "waxing crescent": between "new" and "first quarter".
0035    + "first quarter": the right 50% of the moon is visible.
0036    + "waxing gibbous": between "first quarter" and "full".
0037    + "full": the moon is fully visible.
0038    + "waning gibbous": between "full" and "last quarter".
0039    + "last quarter": the left 50% of the moon is visible.
0040    + "waning crescent": between "last quarter" and "new".
0041 
0042    A very good description of the lunar phases can be read at the Wikipedia,
0043      https://en.wikipedia.org/wiki/Lunar_phase
0044 */
0045 class KHOLIDAYS_EXPORT LunarPhase // krazy:exclude=dpointer
0046 {
0047     Q_GADGET
0048 public:
0049     /**
0050       Phases of the moon, in traditional English notation. The
0051       phase @c None is used only as an error indicator, for instance
0052       in phase().
0053     */
0054     enum Phase {
0055         NewMoon, ///< New moon phase
0056         FirstQuarter, ///< First quarter of moon phase
0057         LastQuarter, ///< Last quarter of moon phase
0058         FullMoon, ///< Full moon phase
0059         None, ///< Indication for error
0060         WaxingCrescent, ///< @since 5.94
0061         WaxingGibbous, ///< @since 5.94
0062         WaningGibbous, ///< @since 5.94
0063         WaningCrescent, ///< @since 5.94
0064     };
0065     Q_ENUM(Phase)
0066 
0067     /**
0068        Return the lunar phase for the specified Gregorian date.
0069        The enum 'None' is returned if one of the supported phases
0070        does not occur on the date.
0071 
0072        @param date compute the lunar phase for the specified Gregorian date.
0073     */
0074     static Phase phaseAtDate(const QDate &date);
0075 
0076     /**
0077        Return the lunar phase as a text string for the specified date.
0078        A null string is returned if one of the supported phases does
0079        not occur on the date.
0080 
0081        @param date compute the lunar phase for the specified Gregorian date.
0082     */
0083     static QString phaseNameAtDate(const QDate &date);
0084 
0085     /**
0086        Return the string representation of phase.
0087 
0088        @param phase the lunar phase.
0089     */
0090     static QString phaseName(Phase phase);
0091 };
0092 
0093 }
0094 
0095 #endif