Branch data Line data Source code
1 : : /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*-
2 : : *
3 : : * Copyright 2024, 2025 GNOME Foundation, Inc.
4 : : *
5 : : * SPDX-License-Identifier: LGPL-2.1-or-later
6 : : *
7 : : * This library is free software; you can redistribute it and/or
8 : : * modify it under the terms of the GNU Lesser General Public
9 : : * License as published by the Free Software Foundation; either
10 : : * version 2.1 of the License, or (at your option) any later version.
11 : : *
12 : : * This library is distributed in the hope that it will be useful,
13 : : * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 : : * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 : : * Lesser General Public License for more details.
16 : : *
17 : : * You should have received a copy of the GNU Lesser General Public
18 : : * License along with this library; if not, write to the Free Software
19 : : * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
20 : : *
21 : : * Authors:
22 : : * - Philip Withnall <pwithnall@gnome.org>
23 : : */
24 : :
25 : : #include "config.h"
26 : :
27 : : #include <glib.h>
28 : : #include <libmalcontent-timer/time-span.h>
29 : : #include <stdint.h>
30 : :
31 : :
32 : : /**
33 : : * MctTimeSpan:
34 : : *
35 : : * A time span representing an interval of one second or longer.
36 : : *
37 : : * Times are stored as Unix timestamps, without timezone data.
38 : : *
39 : : * The span is inclusive of its start and end time, and the end time may be
40 : : * equal to the start time. Formally (in
41 : : * [ISO 31-11 notation](https://en.wikipedia.org/wiki/Interval_(mathematics)#Including_or_excluding_endpoints)),
42 : : * the span is `[start, end]`. If the end time is equal to the start time, the
43 : : * span is one second long; this is the shortest representable span.
44 : : *
45 : : * Since: 0.14.0
46 : : */
47 : :
48 : : struct _MctTimeSpan
49 : : {
50 : : uint64_t start_time_secs;
51 : : uint64_t end_time_secs; /* >= start_time_secs */
52 : : };
53 : :
54 : : /**
55 : : * mct_time_span_new:
56 : : * @start_time_secs: start (inclusive) of the time span, as a Unix timestamp
57 : : * @end_time_secs: end (inclusive) of the time span, as a Unix timestamp
58 : : *
59 : : * Create a new [struct@MalcontentTimer.TimeSpan].
60 : : *
61 : : * The end time must not be before the start time.
62 : : *
63 : : * Returns: (transfer full): a new [struct@MalcontentTimer.TimeSpan]
64 : : * Since: 0.14.0
65 : : */
66 : : MctTimeSpan *
67 : 0 : mct_time_span_new (uint64_t start_time_secs,
68 : : uint64_t end_time_secs)
69 : : {
70 : 0 : g_autoptr(MctTimeSpan) span = NULL;
71 : :
72 : 0 : g_return_val_if_fail (start_time_secs < end_time_secs, NULL);
73 : :
74 : 0 : span = g_new0 (MctTimeSpan, 1);
75 : 0 : span->start_time_secs = start_time_secs;
76 : 0 : span->end_time_secs = end_time_secs;
77 : 0 : return g_steal_pointer (&span);
78 : : }
79 : :
80 : : /**
81 : : * mct_time_span_free:
82 : : * @self: (transfer full): a time span
83 : : *
84 : : * Free the given [struct@MalcontentTimer.TimeSpan].
85 : : *
86 : : * Since: 0.14.0
87 : : */
88 : : void
89 : 0 : mct_time_span_free (MctTimeSpan *self)
90 : : {
91 : 0 : g_return_if_fail (self != NULL);
92 : :
93 : 0 : g_free (self);
94 : : }
95 : :
96 : : /**
97 : : * mct_time_span_copy:
98 : : * @self: a time span
99 : : *
100 : : * Copy the given time span.
101 : : *
102 : : * Returns: (transfer full): a copy of @self
103 : : * Since: 0.14.0
104 : : */
105 : : MctTimeSpan *
106 : 0 : mct_time_span_copy (const MctTimeSpan *self)
107 : : {
108 : 0 : g_return_val_if_fail (self != NULL, NULL);
109 : :
110 : 0 : return mct_time_span_new (self->start_time_secs,
111 : 0 : self->end_time_secs);
112 : : }
113 : :
114 : : /**
115 : : * mct_time_span_compare:
116 : : * @self: a time span
117 : : * @other: another time span
118 : : *
119 : : * Compare two time spans to give a total order.
120 : : *
121 : : * If the time spans are identical, `0` is returned.
122 : : *
123 : : * Otherwise, their start times are compared and `-1` is returned is @self comes
124 : : * before @other; `1` is returned if @self comes after @other.
125 : : *
126 : : * If their start times are equal, their end times are compared and `-1` or `1`
127 : : * is returned depending on whether the end time of @self comes before or after
128 : : * the end time of @other.
129 : : *
130 : : * Returns: an integer representing the total order of @self and @other, with
131 : : * similar semantics to [`strcmp()`](man:strcmp(3))
132 : : * Since: 0.14.0
133 : : */
134 : : int
135 : 0 : mct_time_span_compare (const MctTimeSpan *self,
136 : : const MctTimeSpan *other)
137 : : {
138 : 0 : g_return_val_if_fail (self != NULL, 0);
139 : 0 : g_return_val_if_fail (other != NULL, 0);
140 : :
141 : : /* We can’t do the normal (a - b) trick here because the members of
142 : : * MctTimeSpan are uint64_t, but the return value is only a 32-bit signed int. */
143 [ # # ]: 0 : if (self->start_time_secs != other->start_time_secs)
144 [ # # ]: 0 : return (self->start_time_secs < other->start_time_secs) ? -1 : 1;
145 : :
146 [ # # ]: 0 : if (self->end_time_secs != other->end_time_secs)
147 [ # # ]: 0 : return (self->end_time_secs < other->end_time_secs) ? -1 : 1;
148 : :
149 : 0 : return 0;
150 : : }
151 : :
152 : : /**
153 : : * mct_time_span_get_start_time_secs:
154 : : * @self: an [struct@MalcontentTimer.TimeSpan]
155 : : *
156 : : * Get the start time of the time span.
157 : : *
158 : : * This is included in the time span.
159 : : *
160 : : * Returns: start time of the time span, as a Unix timestamp
161 : : * Since: 0.14.0
162 : : */
163 : : uint64_t
164 : 0 : mct_time_span_get_start_time_secs (const MctTimeSpan *self)
165 : : {
166 : 0 : g_return_val_if_fail (self != NULL, 0);
167 : :
168 : 0 : return self->start_time_secs;
169 : : }
170 : :
171 : : /**
172 : : * mct_time_span_get_end_time_secs:
173 : : * @self: an [struct@MalcontentTimer.TimeSpan]
174 : : *
175 : : * Get the end time of the time span.
176 : : *
177 : : * This is included in the time span.
178 : : *
179 : : * Returns: end time of the time span, as a Unix timestamp
180 : : * Since: 0.14.0
181 : : */
182 : : uint64_t
183 : 0 : mct_time_span_get_end_time_secs (const MctTimeSpan *self)
184 : : {
185 : 0 : g_return_val_if_fail (self != NULL, 0);
186 : :
187 : 0 : return self->end_time_secs;
188 : : }
|
