GnuCash  4.8a-132-gcdaeb421d+
Recurrence.h
1 /* Recurrence.h:
2  *
3  * A Recurrence represents the periodic occurrence of dates, with a
4  * beginning point. For example, "Every Friday, beginning April 15,
5  * 2005" or "The 1st of every 3rd month, beginning April 1, 2001."
6  *
7  * Technically, a Recurrence can also represent certain useful
8  * "almost periodic" date sequences. For example, "The last day of
9  * every month, beginning Feb. 28, 2005."
10  *
11  * The main operation you can perform on a Recurrence is to find the
12  * earliest date in the sequence of occurrences that is after some
13  * specified date (often the "previous" occurrence).
14  *
15  * In addition, you can use a GList of Recurrences to represent a
16  * sequence containing all the dates in each Recurrence in the list,
17  * and perform the same "next instance" computation for this
18  * sequence.
19  *
20  * Copyright (C) 2005, Chris Shoemaker <c.shoemaker@cox.net>
21  *
22  * This program is free software; you can redistribute it and/or
23  * modify it under the terms of the GNU General Public License as
24  * published by the Free Software Foundation; either version 2 of
25  * the License, or (at your option) any later version.
26  *
27  * This program is distributed in the hope that it will be useful,
28  * but WITHOUT ANY WARRANTY; without even the implied warranty of
29  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
30  * GNU General Public License for more details.
31  *
32  * You should have received a copy of the GNU General Public License
33  * along with this program; if not, contact:
34  *
35  * Free Software Foundation Voice: +1-617-542-5942
36  * 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652
37  * Boston, MA 02110-1301, USA gnu@gnu.org
38  */
39 
40 #ifndef RECURRENCE_H
41 #define RECURRENCE_H
42 
43 #include <glib.h>
44 #include "Account.h"
45 #include "gnc-numeric.h"
46 
47 typedef enum
48 {
49  PERIOD_ONCE, /* Not a true period at all, but convenient here. */
50  PERIOD_DAY,
51  PERIOD_WEEK,
52  PERIOD_MONTH,
53  PERIOD_END_OF_MONTH, /* This is actually a period plus a phase. */
54  PERIOD_NTH_WEEKDAY, /* Also a phase, e.g. Second Tueday. */
55  PERIOD_LAST_WEEKDAY, /* Also a phase. */
56  PERIOD_YEAR,
57  NUM_PERIOD_TYPES,
58  PERIOD_INVALID = -1,
59 } PeriodType;
60 
61 typedef enum
62 {
63  WEEKEND_ADJ_NONE,
64  WEEKEND_ADJ_BACK, /* Previous weekday */
65  WEEKEND_ADJ_FORWARD, /* Next weekday */
66  NUM_WEEKEND_ADJS,
67  WEEKEND_ADJ_INVALID = -1,
68 } WeekendAdjust;
69 
70 /* Recurrences represent both the phase and period of a recurring event. */
71 
72 typedef struct
73 {
74  GDate start; /* First date in the recurrence; specifies phase. */
75  PeriodType ptype; /* see PeriodType enum */
76  guint16 mult; /* a period multiplier */
77  WeekendAdjust wadj; /* see WeekendAdjust enum */
78 } Recurrence;
79 
80 
81 /* recurrenceSet() will enforce internal consistency by overriding
82  inconsistent inputs so that 'r' will _always_ end up being a valid
83  recurrence.
84 
85  - if the period type is invalid, PERIOD_MONTH is used.
86 
87  - if the period type is PERIOD_ONCE, then mult is ignored,
88  otherwise, if mult is zero, then mult of 1 is used.
89 
90  - if the date is invalid, the current date is used.
91 
92  - if the period type specifies phase, the date is made to agree
93  with that phase:
94 
95  - for PERIOD_END_OF_MONTH, the last day of date's month is used.
96 
97  - for PERIOD_NTH_WEEKDAY, a fifth weekday converts to a
98  PERIOD_LAST_WEEKDAY
99 
100  - for PERIOD_LAST_WEEKDAY, the last day in date's month with
101  date's day-of-week is used.
102 
103 */
104 void recurrenceSet(Recurrence *r, guint16 mult, PeriodType pt,
105  const GDate *date, WeekendAdjust wadj);
106 
107 /* get the fields */
108 PeriodType recurrenceGetPeriodType(const Recurrence *r);
109 guint recurrenceGetMultiplier(const Recurrence *r);
110 GDate recurrenceGetDate(const Recurrence *r);
111 time64 recurrenceGetTime(const Recurrence *r);
112 WeekendAdjust recurrenceGetWeekendAdjust(const Recurrence *r);
113 
114 /* Get the occurrence immediately after refDate.
115  *
116  * This function has strict and precise post-conditions:
117  *
118  * Given a valid recurrence and a valid 'refDate', 'nextDate' will be
119  * *IN*valid IFF the period_type is PERIOD_ONCE, and 'refDate' is
120  * later-than or equal to the single occurrence (start_date).
121  *
122  * A valid 'nextDate' will _always_ be:
123  * - strictly later than the 'refDate', AND
124  * - later than or equal to the start date of the recurrence, AND
125  * - exactly an integral number of periods away from the start date
126  *
127  * Furthermore, there will be no date _earlier_ than 'nextDate' for
128  * which the three things above are true.
129  *
130  */
131 void recurrenceNextInstance(const Recurrence *r, const GDate *refDate,
132  GDate *nextDate);
133 
134 /* Zero-based. n == 1 gets the instance after the start date. */
135 void recurrenceNthInstance(const Recurrence *r, guint n, GDate *date);
136 
137 /* Get a time corresponding to the beginning (or end if 'end' is true)
138  of the nth instance of the recurrence. Also zero-based. */
139 time64 recurrenceGetPeriodTime(const Recurrence *r, guint n, gboolean end);
140 
146 gnc_numeric recurrenceGetAccountPeriodValue(const Recurrence *r,
147  Account *acct, guint n);
148 
150 void recurrenceListNextInstance(const GList *r, const GDate *refDate,
151  GDate *nextDate);
152 
153 /* These four functions are only for xml storage, not user presentation. */
154 gchar *recurrencePeriodTypeToString(PeriodType pt);
155 PeriodType recurrencePeriodTypeFromString(const gchar *str);
156 gchar *recurrenceWeekendAdjustToString(WeekendAdjust wadj);
157 WeekendAdjust recurrenceWeekendAdjustFromString(const gchar *str);
158 
159 /* For debugging. Caller owns the returned string. Not intl. */
160 gchar *recurrenceToString(const Recurrence *r);
161 gchar *recurrenceListToString(const GList *rlist);
162 
164 gboolean recurrenceListIsSemiMonthly(GList *recurrences);
166 gboolean recurrenceListIsWeeklyMultiple(const GList *recurrences);
167 
180 gchar *recurrenceListToCompactString(GList *recurrence_list);
181 
183 int recurrenceCmp(Recurrence *a, Recurrence *b);
184 int recurrenceListCmp(GList *a, GList *b);
185 
186 void recurrenceListFree(GList **recurrence);
187 
188 #endif /* RECURRENCE_H */
An exact-rational-number library for gnucash.
Account handling public routines.
gint64 time64
Many systems, including Microsoft Windows and BSD-derived Unixes like Darwin, are retaining the int-3...
Definition: gnc-date.h:93