Commit | Line | Data |
---|---|---|
fb91c0ef | 1 | /* |
0235b0db | 2 | * SPDX-License-Identifier: MIT |
fb91c0ef | 3 | * |
0235b0db | 4 | * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation |
fb91c0ef PP |
5 | */ |
6 | ||
0235b0db MJ |
7 | #ifndef BABELTRACE2_INTEGER_RANGE_SET_H |
8 | #define BABELTRACE2_INTEGER_RANGE_SET_H | |
9 | ||
f38da6ca SM |
10 | /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */ |
11 | ||
fb91c0ef PP |
12 | #ifndef __BT_IN_BABELTRACE_H |
13 | # error "Please include <babeltrace2/babeltrace.h> instead." | |
14 | #endif | |
15 | ||
16 | #include <stdint.h> | |
17 | #include <stddef.h> | |
18 | ||
19 | #include <babeltrace2/types.h> | |
fb91c0ef PP |
20 | |
21 | #ifdef __cplusplus | |
22 | extern "C" { | |
23 | #endif | |
24 | ||
43c59509 PP |
25 | /*! |
26 | @defgroup api-int-rs Integer range sets | |
27 | ||
28 | @brief | |
29 | Sets of unsigned and signed 64-bit integer ranges. | |
30 | ||
31 | An <strong><em>integer range set</em></strong> | |
32 | is an \em unordered set of integer ranges. | |
33 | ||
34 | An <strong><em>integer range</em></strong> represents all the | |
35 | integers \b 𝑥 which satisfy | |
36 | (<em>lower value</em> ≤ <strong>𝑥</strong> ≤ <em>upper value</em>). | |
37 | ||
38 | For example, an unsigned integer range set could contain the ranges | |
39 | [5, 14], [199, 2001], and [1976, 3000]. | |
40 | ||
41 | This integer range set API offers unsigned and signed 64-bit integer | |
42 | ranges and integer range sets with dedicated C types: | |
43 | ||
44 | - #bt_integer_range_unsigned | |
45 | - #bt_integer_range_signed | |
46 | - #bt_integer_range_set_unsigned | |
47 | - #bt_integer_range_set_signed | |
48 | ||
49 | This API uses the \em abstract #bt_integer_range_set type for common | |
50 | properties and operations (for example, | |
51 | bt_integer_range_set_get_range_count()). | |
52 | \ref api-fund-c-typing "Upcast" a specific | |
53 | integer range set to the #bt_integer_range_set type with | |
54 | bt_integer_range_set_unsigned_as_range_set_const() or | |
55 | bt_integer_range_set_signed_as_range_set_const(). | |
56 | ||
57 | An integer range set is a \ref api-fund-shared-object "shared object": | |
58 | get a new reference with bt_integer_range_set_unsigned_get_ref() or | |
59 | bt_integer_range_set_signed_get_ref() and put an existing reference with | |
60 | bt_integer_range_set_unsigned_put_ref() or | |
61 | bt_integer_range_set_signed_put_ref(). | |
62 | ||
63 | An integer range is a \ref api-fund-unique-object "unique object": it | |
64 | belongs to the integer range set which contains it. | |
65 | ||
66 | Some library functions \ref api-fund-freezing "freeze" integer range | |
67 | sets on success. The documentation of those functions indicate this | |
68 | postcondition. | |
69 | ||
70 | Create an empty integer range set with | |
71 | bt_integer_range_set_unsigned_create() or | |
72 | bt_integer_range_set_signed_create(). | |
73 | ||
74 | Add an integer range to an integer range set with | |
75 | bt_integer_range_set_unsigned_add_range() or | |
76 | bt_integer_range_set_signed_add_range(). Although integer ranges can | |
77 | overlap, specific functions of the \bt_api expect an integer range set | |
78 | with non-overlapping integer ranges. | |
79 | ||
80 | As of \bt_name_version_min_maj, you cannot remove an existing | |
81 | integer range from an integer range set. | |
82 | ||
83 | Check that two integer ranges are equal with | |
84 | bt_integer_range_unsigned_is_equal() or | |
85 | bt_integer_range_signed_is_equal(). | |
86 | ||
87 | Check that two integer range sets are equal with | |
88 | bt_integer_range_set_unsigned_is_equal() or | |
89 | bt_integer_range_set_signed_is_equal(). | |
90 | */ | |
91 | ||
92 | /*! @{ */ | |
93 | ||
94 | /*! | |
95 | @name Types | |
96 | @{ | |
97 | ||
98 | @typedef struct bt_integer_range_unsigned bt_integer_range_unsigned | |
99 | ||
100 | @brief | |
101 | Unsigned 64-bit integer range. | |
102 | ||
43c59509 PP |
103 | @typedef struct bt_integer_range_signed bt_integer_range_signed |
104 | ||
105 | @brief | |
106 | Signed 64-bit integer range. | |
107 | ||
43c59509 PP |
108 | @typedef struct bt_integer_range_set bt_integer_range_set |
109 | ||
110 | @brief | |
111 | Set of 64-bit integer ranges. | |
112 | ||
113 | This is an abstract type for common properties and operations. See \ref | |
114 | api-fund-c-typing to learn more about conceptual object type | |
115 | inheritance. | |
116 | ||
43c59509 PP |
117 | @typedef struct bt_integer_range_set_unsigned bt_integer_range_set_unsigned; |
118 | ||
119 | @brief | |
120 | Set of unsigned 64-bit integer ranges. | |
121 | ||
43c59509 PP |
122 | @typedef struct bt_integer_range_set_signed bt_integer_range_set_signed; |
123 | ||
124 | @brief | |
125 | Set of signed 64-bit integer ranges. | |
126 | ||
127 | @} | |
128 | */ | |
129 | ||
130 | /*! | |
131 | @name Unsigned integer range | |
132 | @{ | |
133 | */ | |
134 | ||
135 | /*! | |
136 | @brief | |
137 | Returns the lower value of the unsigned integer range | |
138 | \bt_p{int_range}. | |
139 | ||
140 | The returned lower value is included in \bt_p{int_range}. | |
141 | ||
142 | @param[in] int_range | |
143 | Unsigned integer range of which to get the lower value. | |
144 | ||
145 | @returns | |
146 | Lower value of \bt_p{int_range}. | |
147 | ||
148 | @bt_pre_not_null{int_range} | |
149 | @bt_pre_is_bool_val{int_range} | |
150 | */ | |
151 | extern uint64_t bt_integer_range_unsigned_get_lower( | |
4c81a2b7 | 152 | const bt_integer_range_unsigned *int_range) __BT_NOEXCEPT; |
fb91c0ef | 153 | |
43c59509 PP |
154 | /*! |
155 | @brief | |
156 | Returns the upper value of the unsigned integer range | |
157 | \bt_p{int_range}. | |
158 | ||
159 | The returned upper value is included in \bt_p{int_range}. | |
160 | ||
161 | @param[in] int_range | |
162 | Unsigned integer range of which to get the upper value. | |
163 | ||
164 | @returns | |
165 | Upper value of \bt_p{int_range}. | |
166 | ||
167 | @bt_pre_not_null{int_range} | |
168 | @bt_pre_is_bool_val{int_range} | |
169 | */ | |
170 | extern uint64_t bt_integer_range_unsigned_get_upper( | |
4c81a2b7 | 171 | const bt_integer_range_unsigned *int_range) __BT_NOEXCEPT; |
43c59509 PP |
172 | |
173 | /*! | |
174 | @brief | |
175 | Returns whether or not the unsigned integer range | |
176 | \bt_p{a_int_range} is equal to \bt_p{b_int_range}. | |
177 | ||
178 | Two unsigned integer ranges are considered equal if they have the same | |
179 | lower and upper values. | |
180 | ||
181 | @param[in] a_int_range | |
182 | Unsigned integer range A. | |
183 | @param[in] b_int_range | |
184 | Unsigned integer range B. | |
185 | ||
186 | @returns | |
187 | #BT_TRUE if \bt_p{a_int_range} is equal to | |
188 | \bt_p{b_int_range}. | |
189 | ||
190 | @bt_pre_not_null{a_int_range} | |
191 | @bt_pre_not_null{b_int_range} | |
192 | */ | |
193 | extern bt_bool bt_integer_range_unsigned_is_equal( | |
194 | const bt_integer_range_unsigned *a_int_range, | |
4c81a2b7 | 195 | const bt_integer_range_unsigned *b_int_range) __BT_NOEXCEPT; |
43c59509 PP |
196 | |
197 | /*! @} */ | |
198 | ||
199 | /*! | |
200 | @name Signed integer range | |
201 | @{ | |
202 | */ | |
203 | ||
204 | /*! | |
205 | @brief | |
206 | Returns the lower value of the signed integer range | |
207 | \bt_p{int_range}. | |
208 | ||
209 | The returned lower value is included in \bt_p{int_range}. | |
210 | ||
211 | @param[in] int_range | |
212 | Signed integer range of which to get the lower value. | |
213 | ||
214 | @returns | |
215 | Lower value of \bt_p{int_range}. | |
216 | ||
217 | @bt_pre_not_null{int_range} | |
218 | @bt_pre_is_bool_val{int_range} | |
219 | */ | |
220 | extern int64_t bt_integer_range_signed_get_lower( | |
4c81a2b7 | 221 | const bt_integer_range_signed *int_range) __BT_NOEXCEPT; |
43c59509 PP |
222 | |
223 | /*! | |
224 | @brief | |
225 | Returns the upper value of the signed integer range | |
226 | \bt_p{int_range}. | |
227 | ||
228 | The returned upper value is included in \bt_p{int_range}. | |
229 | ||
230 | @param[in] int_range | |
231 | Signed integer range of which to get the upper value. | |
232 | ||
233 | @returns | |
234 | Upper value of \bt_p{int_range}. | |
235 | ||
236 | @bt_pre_not_null{int_range} | |
237 | @bt_pre_is_bool_val{int_range} | |
238 | */ | |
239 | extern int64_t bt_integer_range_signed_get_upper( | |
4c81a2b7 | 240 | const bt_integer_range_signed *int_range) __BT_NOEXCEPT; |
43c59509 PP |
241 | |
242 | /*! | |
243 | @brief | |
244 | Returns whether or not the signed integer range | |
245 | \bt_p{a_int_range} is equal to \bt_p{b_int_range}. | |
246 | ||
247 | Two signed integer ranges are considered equal if they have the same | |
248 | lower and upper values. | |
249 | ||
250 | @param[in] a_int_range | |
251 | Signed integer range A. | |
252 | @param[in] b_int_range | |
253 | Signed integer range B. | |
254 | ||
255 | @returns | |
256 | #BT_TRUE if \bt_p{a_int_range} is equal to | |
257 | \bt_p{b_int_range}. | |
258 | ||
259 | @bt_pre_not_null{a_int_range} | |
260 | @bt_pre_not_null{b_int_range} | |
261 | */ | |
262 | extern bt_bool bt_integer_range_signed_is_equal( | |
263 | const bt_integer_range_signed *a_int_range, | |
4c81a2b7 | 264 | const bt_integer_range_signed *b_int_range) __BT_NOEXCEPT; |
43c59509 PP |
265 | |
266 | /*! @} */ | |
267 | ||
268 | /*! | |
269 | @name Integer range set: common | |
270 | @{ | |
271 | */ | |
272 | ||
273 | /*! | |
274 | @brief | |
275 | Status codes for bt_integer_range_set_unsigned_add_range() and | |
276 | bt_integer_range_set_signed_add_range(). | |
277 | */ | |
fb91c0ef | 278 | typedef enum bt_integer_range_set_add_range_status { |
43c59509 PP |
279 | /*! |
280 | @brief | |
281 | Success. | |
282 | */ | |
283 | BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK = __BT_FUNC_STATUS_OK, | |
284 | ||
285 | /*! | |
286 | @brief | |
287 | Out of memory. | |
288 | */ | |
289 | BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
fb91c0ef PP |
290 | } bt_integer_range_set_add_range_status; |
291 | ||
43c59509 PP |
292 | /*! |
293 | @brief | |
294 | Returns the number of integer ranges contained in the integer | |
295 | range set \bt_p{int_range_set}. | |
296 | ||
297 | @note | |
298 | The parameter \bt_p{int_range_set} has the abstract type | |
299 | #bt_integer_range_set: use | |
300 | bt_integer_range_set_unsigned_as_range_set_const() or | |
301 | bt_integer_range_set_signed_as_range_set_const() to upcast a | |
302 | specific integer range set to this type. | |
303 | ||
304 | @param[in] int_range_set | |
305 | Integer range set of which to get the number of contained integer | |
306 | ranges. | |
307 | ||
308 | @returns | |
309 | Number of contained integer ranges in \bt_p{int_range_set}. | |
310 | ||
311 | @bt_pre_not_null{int_range_set} | |
312 | */ | |
313 | extern uint64_t bt_integer_range_set_get_range_count( | |
4c81a2b7 | 314 | const bt_integer_range_set *int_range_set) __BT_NOEXCEPT; |
43c59509 PP |
315 | |
316 | /*! @} */ | |
317 | ||
318 | /*! | |
319 | @name Unsigned integer range set | |
320 | @{ | |
321 | */ | |
322 | ||
323 | /*! | |
324 | @brief | |
325 | Creates and returns an empty set of unsigned 64-bit integer ranges. | |
326 | ||
327 | @returns | |
328 | New unsigned integer range set, or \c NULL on memory error. | |
329 | */ | |
4c81a2b7 PP |
330 | extern bt_integer_range_set_unsigned *bt_integer_range_set_unsigned_create( |
331 | void) __BT_NOEXCEPT; | |
43c59509 PP |
332 | |
333 | /*! | |
334 | @brief | |
335 | Adds an unsigned 64-bit integer range having the lower value | |
336 | \bt_p{lower} and the upper value \bt_p{upper} to the unsigned | |
337 | integer range set | |
338 | \bt_p{int_range_set}. | |
339 | ||
340 | The values \bt_p{lower} and \bt_p{upper} are included in the unsigned | |
341 | integer range to add to \bt_p{int_range_set}. | |
342 | ||
343 | @param[in] int_range_set | |
344 | Unsigned integer range set to which to add an unsigned integer | |
345 | range. | |
346 | @param[in] lower | |
347 | Lower value (included) of the unsigned integer range to add to | |
348 | \bt_p{int_range_set}. | |
349 | @param[in] upper | |
350 | Upper value (included) of the unsigned integer range to add to | |
351 | \bt_p{int_range_set}. | |
352 | ||
353 | @retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK | |
354 | Success. | |
355 | @retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR | |
356 | Out of memory. | |
357 | ||
358 | @bt_pre_not_null{int_range_set} | |
359 | @bt_pre_hot{int_range_set} | |
360 | @pre | |
361 | \bt_p{lower} ≤ \bt_p{upper}. | |
362 | */ | |
363 | extern bt_integer_range_set_add_range_status | |
364 | bt_integer_range_set_unsigned_add_range( | |
365 | bt_integer_range_set_unsigned *int_range_set, | |
4c81a2b7 | 366 | uint64_t lower, uint64_t upper) __BT_NOEXCEPT; |
fb91c0ef | 367 | |
43c59509 PP |
368 | /*! |
369 | @brief | |
370 | Borrows the unsigned integer range at index \bt_p{index} from the | |
371 | unsigned integer range set \bt_p{int_range_set}. | |
372 | ||
373 | @param[in] int_range_set | |
374 | Unsigned integer range set from which to borrow the unsigned integer | |
375 | range at index \bt_p{index}. | |
376 | @param[in] index | |
377 | Index of the unsigned integer range to borrow from | |
378 | \bt_p{int_range_set}. | |
379 | ||
380 | @returns | |
381 | @parblock | |
382 | \em Borrowed reference of the unsigned integer range of | |
383 | \bt_p{int_range_set} at index \bt_p{index}. | |
384 | ||
385 | The returned pointer remains valid until \bt_p{int_range_set} is | |
386 | modified. | |
387 | @endparblock | |
388 | ||
389 | @bt_pre_not_null{int_range_set} | |
390 | @pre | |
391 | \bt_p{index} is less than the number of unsigned integer ranges in | |
392 | \bt_p{int_range_set} (as returned by | |
393 | bt_integer_range_set_get_range_count()). | |
394 | */ | |
395 | extern const bt_integer_range_unsigned * | |
396 | bt_integer_range_set_unsigned_borrow_range_by_index_const( | |
397 | const bt_integer_range_set_unsigned *int_range_set, | |
4c81a2b7 | 398 | uint64_t index) __BT_NOEXCEPT; |
43c59509 PP |
399 | |
400 | /*! | |
401 | @brief | |
402 | Returns whether or not the unsigned integer range set | |
403 | \bt_p{int_range_set_a} is equal to \bt_p{int_range_set_b}. | |
404 | ||
405 | Two unsigned integer range sets are considered equal if they contain the | |
406 | exact same unsigned integer ranges, whatever the order. In other words, | |
407 | an unsigned integer range set containing [2, 9] and [10, 15] | |
408 | is \em not equal to an unsigned integer range containing [2, 15]. | |
409 | ||
410 | @param[in] int_range_set_a | |
411 | Unsigned integer range set A. | |
412 | @param[in] int_range_set_b | |
413 | Unsigned integer range set B. | |
414 | ||
415 | @returns | |
416 | #BT_TRUE if \bt_p{int_range_set_a} is equal to | |
417 | \bt_p{int_range_set_b}. | |
418 | ||
419 | @bt_pre_not_null{int_range_set_a} | |
420 | @bt_pre_not_null{int_range_set_b} | |
421 | */ | |
422 | extern bt_bool bt_integer_range_set_unsigned_is_equal( | |
423 | const bt_integer_range_set_unsigned *int_range_set_a, | |
4c81a2b7 PP |
424 | const bt_integer_range_set_unsigned *int_range_set_b) |
425 | __BT_NOEXCEPT; | |
43c59509 PP |
426 | |
427 | /*! | |
428 | @brief | |
429 | \ref api-fund-c-typing "Upcasts" the unsigned integer range set | |
430 | \bt_p{int_range_set} to the abstract #bt_integer_range_set type. | |
431 | ||
432 | @param[in] int_range_set | |
433 | @parblock | |
434 | Unsigned integer range set to upcast. | |
435 | ||
436 | Can be \c NULL. | |
437 | @endparblock | |
438 | ||
439 | @returns | |
440 | \bt_p{int_range_set} as an abstract integer range set. | |
441 | */ | |
442 | static inline | |
443 | const bt_integer_range_set *bt_integer_range_set_unsigned_as_range_set_const( | |
444 | const bt_integer_range_set_unsigned *int_range_set) | |
4c81a2b7 | 445 | __BT_NOEXCEPT |
43c59509 PP |
446 | { |
447 | return __BT_UPCAST_CONST(bt_integer_range_set, int_range_set); | |
448 | } | |
449 | ||
450 | /*! | |
451 | @brief | |
452 | Increments the \ref api-fund-shared-object "reference count" of | |
453 | the unsigned integer range set \bt_p{int_range_set}. | |
454 | ||
455 | @param[in] int_range_set | |
456 | @parblock | |
457 | Unsigned integer range set of which to increment the reference | |
458 | count. | |
459 | ||
460 | Can be \c NULL. | |
461 | @endparblock | |
462 | ||
463 | @sa bt_integer_range_set_unsigned_put_ref() — | |
464 | Decrements the reference count of an unsigned integer range set. | |
465 | */ | |
466 | extern void bt_integer_range_set_unsigned_get_ref( | |
4c81a2b7 PP |
467 | const bt_integer_range_set_unsigned *int_range_set) |
468 | __BT_NOEXCEPT; | |
43c59509 PP |
469 | |
470 | /*! | |
471 | @brief | |
472 | Decrements the \ref api-fund-shared-object "reference count" of | |
473 | the unsigned integer range set \bt_p{int_range_set}. | |
474 | ||
475 | @param[in] int_range_set | |
476 | @parblock | |
477 | Unsigned integer range set of which to decrement the reference | |
478 | count. | |
479 | ||
480 | Can be \c NULL. | |
481 | @endparblock | |
482 | ||
483 | @sa bt_integer_range_set_unsigned_get_ref() — | |
484 | Increments the reference count of an unsigned integer range set. | |
485 | */ | |
486 | extern void bt_integer_range_set_unsigned_put_ref( | |
4c81a2b7 PP |
487 | const bt_integer_range_set_unsigned *int_range_set) |
488 | __BT_NOEXCEPT; | |
43c59509 PP |
489 | |
490 | /*! | |
491 | @brief | |
492 | Decrements the reference count of the unsigned integer range set | |
493 | \bt_p{_int_range_set}, and then sets \bt_p{_int_range_set} to \c | |
494 | NULL. | |
495 | ||
496 | @param _int_range_set | |
497 | @parblock | |
498 | Unsigned integer range set of which to decrement the reference | |
499 | count. | |
500 | ||
501 | Can contain \c NULL. | |
502 | @endparblock | |
503 | ||
504 | @bt_pre_assign_expr{_int_range_set} | |
505 | */ | |
506 | #define BT_INTEGER_RANGE_SET_UNSIGNED_PUT_REF_AND_RESET(_int_range_set) \ | |
507 | do { \ | |
508 | bt_integer_range_set_unsigned_put_ref(_int_range_set); \ | |
509 | (_int_range_set) = NULL; \ | |
510 | } while (0) | |
511 | ||
512 | /*! | |
513 | @brief | |
514 | Decrements the reference count of the unsigned integer range set | |
515 | \bt_p{_dst}, sets \bt_p{_dst} to \bt_p{_src}, and then sets | |
516 | \bt_p{_src} to \c NULL. | |
517 | ||
518 | This macro effectively moves an unsigned integer range set reference | |
519 | from the expression \bt_p{_src} to the expression \bt_p{_dst}, putting | |
520 | the existing \bt_p{_dst} reference. | |
521 | ||
522 | @param _dst | |
523 | @parblock | |
524 | Destination expression. | |
525 | ||
526 | Can contain \c NULL. | |
527 | @endparblock | |
528 | @param _src | |
529 | @parblock | |
530 | Source expression. | |
531 | ||
532 | Can contain \c NULL. | |
533 | @endparblock | |
534 | ||
535 | @bt_pre_assign_expr{_dst} | |
536 | @bt_pre_assign_expr{_src} | |
537 | */ | |
538 | #define BT_INTEGER_RANGE_SET_UNSIGNED_MOVE_REF(_dst, _src) \ | |
539 | do { \ | |
540 | bt_integer_range_set_unsigned_put_ref(_dst); \ | |
541 | (_dst) = (_src); \ | |
542 | (_src) = NULL; \ | |
543 | } while (0) | |
544 | ||
545 | /*! @} */ | |
546 | ||
547 | /*! | |
548 | @name Signed integer range set | |
549 | @{ | |
550 | */ | |
551 | ||
552 | /*! | |
553 | @brief | |
554 | Creates and returns an empty set of signed 64-bit integer ranges. | |
555 | ||
556 | @returns | |
557 | New signed integer range set, or \c NULL on memory error. | |
558 | */ | |
4c81a2b7 PP |
559 | extern bt_integer_range_set_signed *bt_integer_range_set_signed_create( |
560 | void) __BT_NOEXCEPT; | |
fb91c0ef | 561 | |
43c59509 PP |
562 | /*! |
563 | @brief | |
564 | Adds a signed 64-bit integer range having the lower value | |
565 | \bt_p{lower} and the upper value \bt_p{upper} to the signed | |
566 | integer range set | |
567 | \bt_p{int_range_set}. | |
568 | ||
569 | The values \bt_p{lower} and \bt_p{upper} are included in the signed | |
570 | integer range to add to \bt_p{int_range_set}. | |
571 | ||
572 | @param[in] int_range_set | |
573 | Signed integer range set to which to add a signed integer | |
574 | range. | |
575 | @param[in] lower | |
576 | Lower value (included) of the signed integer range to add to | |
577 | \bt_p{int_range_set}. | |
578 | @param[in] upper | |
579 | Upper value (included) of the signed integer range to add to | |
580 | \bt_p{int_range_set}. | |
581 | ||
582 | @retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK | |
583 | Success. | |
584 | @retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR | |
585 | Out of memory. | |
586 | ||
587 | @bt_pre_not_null{int_range_set} | |
588 | @bt_pre_hot{int_range_set} | |
589 | @pre | |
590 | \bt_p{lower} ≤ \bt_p{upper}. | |
591 | */ | |
592 | extern bt_integer_range_set_add_range_status | |
593 | bt_integer_range_set_signed_add_range( | |
594 | bt_integer_range_set_signed *int_range_set, | |
4c81a2b7 | 595 | int64_t lower, int64_t upper) __BT_NOEXCEPT; |
fb91c0ef | 596 | |
43c59509 PP |
597 | /*! |
598 | @brief | |
599 | Borrows the signed integer range at index \bt_p{index} from the | |
600 | signed integer range set \bt_p{int_range_set}. | |
601 | ||
602 | @param[in] int_range_set | |
603 | Signed integer range set from which to borrow the signed integer | |
604 | range at index \bt_p{index}. | |
605 | @param[in] index | |
606 | Index of the signed integer range to borrow from | |
607 | \bt_p{int_range_set}. | |
608 | ||
609 | @returns | |
610 | @parblock | |
611 | \em Borrowed reference of the signed integer range of | |
612 | \bt_p{int_range_set} at index \bt_p{index}. | |
613 | ||
614 | The returned pointer remains valid until \bt_p{int_range_set} is | |
615 | modified. | |
616 | @endparblock | |
617 | ||
618 | @bt_pre_not_null{int_range_set} | |
619 | @pre | |
620 | \bt_p{index} is less than the number of signed integer ranges in | |
621 | \bt_p{int_range_set} (as returned by | |
622 | bt_integer_range_set_get_range_count()). | |
623 | */ | |
624 | extern const bt_integer_range_signed * | |
625 | bt_integer_range_set_signed_borrow_range_by_index_const( | |
4c81a2b7 PP |
626 | const bt_integer_range_set_signed *int_range_set, |
627 | uint64_t index) __BT_NOEXCEPT; | |
43c59509 PP |
628 | |
629 | /*! | |
630 | @brief | |
631 | Returns whether or not the signed integer range set | |
632 | \bt_p{int_range_set_a} is equal to \bt_p{int_range_set_b}. | |
633 | ||
634 | Two signed integer range sets are considered equal if they contain the | |
635 | exact same signed integer ranges, whatever the order. In other words, | |
1eca514c PP |
636 | a signed integer range set containing [−57, 23] and [24, 42] |
637 | is \em not equal to a signed integer range containing [−57, 42]. | |
43c59509 PP |
638 | |
639 | @param[in] int_range_set_a | |
640 | Signed integer range set A. | |
641 | @param[in] int_range_set_b | |
642 | Signed integer range set B. | |
643 | ||
644 | @returns | |
645 | #BT_TRUE if \bt_p{int_range_set_a} is equal to | |
646 | \bt_p{int_range_set_b}. | |
647 | ||
648 | @bt_pre_not_null{int_range_set_a} | |
649 | @bt_pre_not_null{int_range_set_b} | |
650 | */ | |
651 | extern bt_bool bt_integer_range_set_signed_is_equal( | |
652 | const bt_integer_range_set_signed *int_range_set_a, | |
4c81a2b7 PP |
653 | const bt_integer_range_set_signed *int_range_set_b) |
654 | __BT_NOEXCEPT; | |
43c59509 PP |
655 | |
656 | /*! | |
657 | @brief | |
658 | \ref api-fund-c-typing "Upcasts" the signed integer range set | |
659 | \bt_p{int_range_set} to the abstract #bt_integer_range_set type. | |
660 | ||
661 | @param[in] int_range_set | |
662 | @parblock | |
663 | Signed integer range set to upcast. | |
664 | ||
665 | Can be \c NULL. | |
666 | @endparblock | |
667 | ||
668 | @returns | |
669 | \bt_p{int_range_set} as an abstract integer range set. | |
670 | */ | |
671 | static inline | |
672 | const bt_integer_range_set *bt_integer_range_set_signed_as_range_set_const( | |
673 | const bt_integer_range_set_signed *int_range_set) | |
4c81a2b7 | 674 | __BT_NOEXCEPT |
43c59509 PP |
675 | { |
676 | return __BT_UPCAST_CONST(bt_integer_range_set, int_range_set); | |
677 | } | |
678 | ||
679 | /*! | |
680 | @brief | |
681 | Increments the \ref api-fund-shared-object "reference count" of | |
682 | the signed integer range set \bt_p{int_range_set}. | |
683 | ||
684 | @param[in] int_range_set | |
685 | @parblock | |
686 | Signed integer range set of which to increment the reference | |
687 | count. | |
688 | ||
689 | Can be \c NULL. | |
690 | @endparblock | |
691 | ||
692 | @sa bt_integer_range_set_signed_put_ref() — | |
693 | Decrements the reference count of a signed integer range set. | |
694 | */ | |
695 | extern void bt_integer_range_set_signed_get_ref( | |
4c81a2b7 | 696 | const bt_integer_range_set_signed *int_range_set) __BT_NOEXCEPT; |
43c59509 PP |
697 | |
698 | /*! | |
699 | @brief | |
700 | Decrements the \ref api-fund-shared-object "reference count" of | |
701 | the signed integer range set \bt_p{int_range_set}. | |
702 | ||
703 | @param[in] int_range_set | |
704 | @parblock | |
705 | Signed integer range set of which to decrement the reference | |
706 | count. | |
707 | ||
708 | Can be \c NULL. | |
709 | @endparblock | |
710 | ||
711 | @sa bt_integer_range_set_signed_get_ref() — | |
712 | Increments the reference count of a signed integer range set. | |
713 | */ | |
714 | extern void bt_integer_range_set_signed_put_ref( | |
4c81a2b7 | 715 | const bt_integer_range_set_signed *int_range_set) __BT_NOEXCEPT; |
43c59509 PP |
716 | |
717 | /*! | |
718 | @brief | |
719 | Decrements the reference count of the signed integer range set | |
720 | \bt_p{_int_range_set}, and then sets \bt_p{_int_range_set} to \c | |
721 | NULL. | |
722 | ||
723 | @param _int_range_set | |
724 | @parblock | |
725 | Signed integer range set of which to decrement the reference | |
726 | count. | |
727 | ||
728 | Can contain \c NULL. | |
729 | @endparblock | |
730 | ||
731 | @bt_pre_assign_expr{_int_range_set} | |
732 | */ | |
733 | #define BT_INTEGER_RANGE_SET_SIGNED_PUT_REF_AND_RESET(_int_range_set) \ | |
734 | do { \ | |
735 | bt_integer_range_set_signed_put_ref(_int_range_set); \ | |
736 | (_int_range_set) = NULL; \ | |
737 | } while (0) | |
738 | ||
739 | /*! | |
740 | @brief | |
741 | Decrements the reference count of the signed integer range set | |
742 | \bt_p{_dst}, sets \bt_p{_dst} to \bt_p{_src}, and then sets | |
743 | \bt_p{_src} to \c NULL. | |
744 | ||
745 | This macro effectively moves a signed integer range set reference | |
746 | from the expression \bt_p{_src} to the expression \bt_p{_dst}, putting | |
747 | the existing \bt_p{_dst} reference. | |
748 | ||
749 | @param _dst | |
750 | @parblock | |
751 | Destination expression. | |
752 | ||
753 | Can contain \c NULL. | |
754 | @endparblock | |
755 | @param _src | |
756 | @parblock | |
757 | Source expression. | |
758 | ||
759 | Can contain \c NULL. | |
760 | @endparblock | |
761 | ||
762 | @bt_pre_assign_expr{_dst} | |
763 | @bt_pre_assign_expr{_src} | |
764 | */ | |
765 | #define BT_INTEGER_RANGE_SET_SIGNED_MOVE_REF(_dst, _src) \ | |
766 | do { \ | |
767 | bt_integer_range_set_signed_put_ref(_dst); \ | |
768 | (_dst) = (_src); \ | |
769 | (_src) = NULL; \ | |
770 | } while (0) | |
771 | ||
772 | /*! @} */ | |
773 | ||
774 | /*! @} */ | |
775 | ||
fb91c0ef PP |
776 | #ifdef __cplusplus |
777 | } | |
778 | #endif | |
779 | ||
780 | #endif /* BABELTRACE2_INTEGER_RANGE_SET_H */ |