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( | |
152 | const bt_integer_range_unsigned *int_range); | |
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( | |
171 | const bt_integer_range_unsigned *int_range); | |
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, | |
195 | const bt_integer_range_unsigned *b_int_range); | |
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( | |
221 | const bt_integer_range_signed *int_range); | |
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( | |
240 | const bt_integer_range_signed *int_range); | |
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, | |
264 | const bt_integer_range_signed *b_int_range); | |
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( | |
314 | const bt_integer_range_set *int_range_set); | |
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 | */ | |
330 | extern bt_integer_range_set_unsigned *bt_integer_range_set_unsigned_create(void); | |
331 | ||
332 | /*! | |
333 | @brief | |
334 | Adds an unsigned 64-bit integer range having the lower value | |
335 | \bt_p{lower} and the upper value \bt_p{upper} to the unsigned | |
336 | integer range set | |
337 | \bt_p{int_range_set}. | |
338 | ||
339 | The values \bt_p{lower} and \bt_p{upper} are included in the unsigned | |
340 | integer range to add to \bt_p{int_range_set}. | |
341 | ||
342 | @param[in] int_range_set | |
343 | Unsigned integer range set to which to add an unsigned integer | |
344 | range. | |
345 | @param[in] lower | |
346 | Lower value (included) of the unsigned integer range to add to | |
347 | \bt_p{int_range_set}. | |
348 | @param[in] upper | |
349 | Upper value (included) of the unsigned integer range to add to | |
350 | \bt_p{int_range_set}. | |
351 | ||
352 | @retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK | |
353 | Success. | |
354 | @retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR | |
355 | Out of memory. | |
356 | ||
357 | @bt_pre_not_null{int_range_set} | |
358 | @bt_pre_hot{int_range_set} | |
359 | @pre | |
360 | \bt_p{lower} ≤ \bt_p{upper}. | |
361 | */ | |
362 | extern bt_integer_range_set_add_range_status | |
363 | bt_integer_range_set_unsigned_add_range( | |
364 | bt_integer_range_set_unsigned *int_range_set, | |
fb91c0ef PP |
365 | uint64_t lower, uint64_t upper); |
366 | ||
43c59509 PP |
367 | /*! |
368 | @brief | |
369 | Borrows the unsigned integer range at index \bt_p{index} from the | |
370 | unsigned integer range set \bt_p{int_range_set}. | |
371 | ||
372 | @param[in] int_range_set | |
373 | Unsigned integer range set from which to borrow the unsigned integer | |
374 | range at index \bt_p{index}. | |
375 | @param[in] index | |
376 | Index of the unsigned integer range to borrow from | |
377 | \bt_p{int_range_set}. | |
378 | ||
379 | @returns | |
380 | @parblock | |
381 | \em Borrowed reference of the unsigned integer range of | |
382 | \bt_p{int_range_set} at index \bt_p{index}. | |
383 | ||
384 | The returned pointer remains valid until \bt_p{int_range_set} is | |
385 | modified. | |
386 | @endparblock | |
387 | ||
388 | @bt_pre_not_null{int_range_set} | |
389 | @pre | |
390 | \bt_p{index} is less than the number of unsigned integer ranges in | |
391 | \bt_p{int_range_set} (as returned by | |
392 | bt_integer_range_set_get_range_count()). | |
393 | */ | |
394 | extern const bt_integer_range_unsigned * | |
395 | bt_integer_range_set_unsigned_borrow_range_by_index_const( | |
396 | const bt_integer_range_set_unsigned *int_range_set, | |
397 | uint64_t index); | |
398 | ||
399 | /*! | |
400 | @brief | |
401 | Returns whether or not the unsigned integer range set | |
402 | \bt_p{int_range_set_a} is equal to \bt_p{int_range_set_b}. | |
403 | ||
404 | Two unsigned integer range sets are considered equal if they contain the | |
405 | exact same unsigned integer ranges, whatever the order. In other words, | |
406 | an unsigned integer range set containing [2, 9] and [10, 15] | |
407 | is \em not equal to an unsigned integer range containing [2, 15]. | |
408 | ||
409 | @param[in] int_range_set_a | |
410 | Unsigned integer range set A. | |
411 | @param[in] int_range_set_b | |
412 | Unsigned integer range set B. | |
413 | ||
414 | @returns | |
415 | #BT_TRUE if \bt_p{int_range_set_a} is equal to | |
416 | \bt_p{int_range_set_b}. | |
417 | ||
418 | @bt_pre_not_null{int_range_set_a} | |
419 | @bt_pre_not_null{int_range_set_b} | |
420 | */ | |
421 | extern bt_bool bt_integer_range_set_unsigned_is_equal( | |
422 | const bt_integer_range_set_unsigned *int_range_set_a, | |
423 | const bt_integer_range_set_unsigned *int_range_set_b); | |
424 | ||
425 | /*! | |
426 | @brief | |
427 | \ref api-fund-c-typing "Upcasts" the unsigned integer range set | |
428 | \bt_p{int_range_set} to the abstract #bt_integer_range_set type. | |
429 | ||
430 | @param[in] int_range_set | |
431 | @parblock | |
432 | Unsigned integer range set to upcast. | |
433 | ||
434 | Can be \c NULL. | |
435 | @endparblock | |
436 | ||
437 | @returns | |
438 | \bt_p{int_range_set} as an abstract integer range set. | |
439 | */ | |
440 | static inline | |
441 | const bt_integer_range_set *bt_integer_range_set_unsigned_as_range_set_const( | |
442 | const bt_integer_range_set_unsigned *int_range_set) | |
443 | { | |
444 | return __BT_UPCAST_CONST(bt_integer_range_set, int_range_set); | |
445 | } | |
446 | ||
447 | /*! | |
448 | @brief | |
449 | Increments the \ref api-fund-shared-object "reference count" of | |
450 | the unsigned integer range set \bt_p{int_range_set}. | |
451 | ||
452 | @param[in] int_range_set | |
453 | @parblock | |
454 | Unsigned integer range set of which to increment the reference | |
455 | count. | |
456 | ||
457 | Can be \c NULL. | |
458 | @endparblock | |
459 | ||
460 | @sa bt_integer_range_set_unsigned_put_ref() — | |
461 | Decrements the reference count of an unsigned integer range set. | |
462 | */ | |
463 | extern void bt_integer_range_set_unsigned_get_ref( | |
464 | const bt_integer_range_set_unsigned *int_range_set); | |
465 | ||
466 | /*! | |
467 | @brief | |
468 | Decrements the \ref api-fund-shared-object "reference count" of | |
469 | the unsigned integer range set \bt_p{int_range_set}. | |
470 | ||
471 | @param[in] int_range_set | |
472 | @parblock | |
473 | Unsigned integer range set of which to decrement the reference | |
474 | count. | |
475 | ||
476 | Can be \c NULL. | |
477 | @endparblock | |
478 | ||
479 | @sa bt_integer_range_set_unsigned_get_ref() — | |
480 | Increments the reference count of an unsigned integer range set. | |
481 | */ | |
482 | extern void bt_integer_range_set_unsigned_put_ref( | |
483 | const bt_integer_range_set_unsigned *int_range_set); | |
484 | ||
485 | /*! | |
486 | @brief | |
487 | Decrements the reference count of the unsigned integer range set | |
488 | \bt_p{_int_range_set}, and then sets \bt_p{_int_range_set} to \c | |
489 | NULL. | |
490 | ||
491 | @param _int_range_set | |
492 | @parblock | |
493 | Unsigned integer range set of which to decrement the reference | |
494 | count. | |
495 | ||
496 | Can contain \c NULL. | |
497 | @endparblock | |
498 | ||
499 | @bt_pre_assign_expr{_int_range_set} | |
500 | */ | |
501 | #define BT_INTEGER_RANGE_SET_UNSIGNED_PUT_REF_AND_RESET(_int_range_set) \ | |
502 | do { \ | |
503 | bt_integer_range_set_unsigned_put_ref(_int_range_set); \ | |
504 | (_int_range_set) = NULL; \ | |
505 | } while (0) | |
506 | ||
507 | /*! | |
508 | @brief | |
509 | Decrements the reference count of the unsigned integer range set | |
510 | \bt_p{_dst}, sets \bt_p{_dst} to \bt_p{_src}, and then sets | |
511 | \bt_p{_src} to \c NULL. | |
512 | ||
513 | This macro effectively moves an unsigned integer range set reference | |
514 | from the expression \bt_p{_src} to the expression \bt_p{_dst}, putting | |
515 | the existing \bt_p{_dst} reference. | |
516 | ||
517 | @param _dst | |
518 | @parblock | |
519 | Destination expression. | |
520 | ||
521 | Can contain \c NULL. | |
522 | @endparblock | |
523 | @param _src | |
524 | @parblock | |
525 | Source expression. | |
526 | ||
527 | Can contain \c NULL. | |
528 | @endparblock | |
529 | ||
530 | @bt_pre_assign_expr{_dst} | |
531 | @bt_pre_assign_expr{_src} | |
532 | */ | |
533 | #define BT_INTEGER_RANGE_SET_UNSIGNED_MOVE_REF(_dst, _src) \ | |
534 | do { \ | |
535 | bt_integer_range_set_unsigned_put_ref(_dst); \ | |
536 | (_dst) = (_src); \ | |
537 | (_src) = NULL; \ | |
538 | } while (0) | |
539 | ||
540 | /*! @} */ | |
541 | ||
542 | /*! | |
543 | @name Signed integer range set | |
544 | @{ | |
545 | */ | |
546 | ||
547 | /*! | |
548 | @brief | |
549 | Creates and returns an empty set of signed 64-bit integer ranges. | |
550 | ||
551 | @returns | |
552 | New signed integer range set, or \c NULL on memory error. | |
553 | */ | |
fb91c0ef PP |
554 | extern bt_integer_range_set_signed *bt_integer_range_set_signed_create(void); |
555 | ||
43c59509 PP |
556 | /*! |
557 | @brief | |
558 | Adds a signed 64-bit integer range having the lower value | |
559 | \bt_p{lower} and the upper value \bt_p{upper} to the signed | |
560 | integer range set | |
561 | \bt_p{int_range_set}. | |
562 | ||
563 | The values \bt_p{lower} and \bt_p{upper} are included in the signed | |
564 | integer range to add to \bt_p{int_range_set}. | |
565 | ||
566 | @param[in] int_range_set | |
567 | Signed integer range set to which to add a signed integer | |
568 | range. | |
569 | @param[in] lower | |
570 | Lower value (included) of the signed integer range to add to | |
571 | \bt_p{int_range_set}. | |
572 | @param[in] upper | |
573 | Upper value (included) of the signed integer range to add to | |
574 | \bt_p{int_range_set}. | |
575 | ||
576 | @retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK | |
577 | Success. | |
578 | @retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR | |
579 | Out of memory. | |
580 | ||
581 | @bt_pre_not_null{int_range_set} | |
582 | @bt_pre_hot{int_range_set} | |
583 | @pre | |
584 | \bt_p{lower} ≤ \bt_p{upper}. | |
585 | */ | |
586 | extern bt_integer_range_set_add_range_status | |
587 | bt_integer_range_set_signed_add_range( | |
588 | bt_integer_range_set_signed *int_range_set, | |
fb91c0ef PP |
589 | int64_t lower, int64_t upper); |
590 | ||
43c59509 PP |
591 | /*! |
592 | @brief | |
593 | Borrows the signed integer range at index \bt_p{index} from the | |
594 | signed integer range set \bt_p{int_range_set}. | |
595 | ||
596 | @param[in] int_range_set | |
597 | Signed integer range set from which to borrow the signed integer | |
598 | range at index \bt_p{index}. | |
599 | @param[in] index | |
600 | Index of the signed integer range to borrow from | |
601 | \bt_p{int_range_set}. | |
602 | ||
603 | @returns | |
604 | @parblock | |
605 | \em Borrowed reference of the signed integer range of | |
606 | \bt_p{int_range_set} at index \bt_p{index}. | |
607 | ||
608 | The returned pointer remains valid until \bt_p{int_range_set} is | |
609 | modified. | |
610 | @endparblock | |
611 | ||
612 | @bt_pre_not_null{int_range_set} | |
613 | @pre | |
614 | \bt_p{index} is less than the number of signed integer ranges in | |
615 | \bt_p{int_range_set} (as returned by | |
616 | bt_integer_range_set_get_range_count()). | |
617 | */ | |
618 | extern const bt_integer_range_signed * | |
619 | bt_integer_range_set_signed_borrow_range_by_index_const( | |
620 | const bt_integer_range_set_signed *int_range_set, uint64_t index); | |
621 | ||
622 | /*! | |
623 | @brief | |
624 | Returns whether or not the signed integer range set | |
625 | \bt_p{int_range_set_a} is equal to \bt_p{int_range_set_b}. | |
626 | ||
627 | Two signed integer range sets are considered equal if they contain the | |
628 | exact same signed integer ranges, whatever the order. In other words, | |
1eca514c PP |
629 | a signed integer range set containing [−57, 23] and [24, 42] |
630 | is \em not equal to a signed integer range containing [−57, 42]. | |
43c59509 PP |
631 | |
632 | @param[in] int_range_set_a | |
633 | Signed integer range set A. | |
634 | @param[in] int_range_set_b | |
635 | Signed integer range set B. | |
636 | ||
637 | @returns | |
638 | #BT_TRUE if \bt_p{int_range_set_a} is equal to | |
639 | \bt_p{int_range_set_b}. | |
640 | ||
641 | @bt_pre_not_null{int_range_set_a} | |
642 | @bt_pre_not_null{int_range_set_b} | |
643 | */ | |
644 | extern bt_bool bt_integer_range_set_signed_is_equal( | |
645 | const bt_integer_range_set_signed *int_range_set_a, | |
646 | const bt_integer_range_set_signed *int_range_set_b); | |
647 | ||
648 | /*! | |
649 | @brief | |
650 | \ref api-fund-c-typing "Upcasts" the signed integer range set | |
651 | \bt_p{int_range_set} to the abstract #bt_integer_range_set type. | |
652 | ||
653 | @param[in] int_range_set | |
654 | @parblock | |
655 | Signed integer range set to upcast. | |
656 | ||
657 | Can be \c NULL. | |
658 | @endparblock | |
659 | ||
660 | @returns | |
661 | \bt_p{int_range_set} as an abstract integer range set. | |
662 | */ | |
663 | static inline | |
664 | const bt_integer_range_set *bt_integer_range_set_signed_as_range_set_const( | |
665 | const bt_integer_range_set_signed *int_range_set) | |
666 | { | |
667 | return __BT_UPCAST_CONST(bt_integer_range_set, int_range_set); | |
668 | } | |
669 | ||
670 | /*! | |
671 | @brief | |
672 | Increments the \ref api-fund-shared-object "reference count" of | |
673 | the signed integer range set \bt_p{int_range_set}. | |
674 | ||
675 | @param[in] int_range_set | |
676 | @parblock | |
677 | Signed integer range set of which to increment the reference | |
678 | count. | |
679 | ||
680 | Can be \c NULL. | |
681 | @endparblock | |
682 | ||
683 | @sa bt_integer_range_set_signed_put_ref() — | |
684 | Decrements the reference count of a signed integer range set. | |
685 | */ | |
686 | extern void bt_integer_range_set_signed_get_ref( | |
687 | const bt_integer_range_set_signed *int_range_set); | |
688 | ||
689 | /*! | |
690 | @brief | |
691 | Decrements the \ref api-fund-shared-object "reference count" of | |
692 | the signed integer range set \bt_p{int_range_set}. | |
693 | ||
694 | @param[in] int_range_set | |
695 | @parblock | |
696 | Signed integer range set of which to decrement the reference | |
697 | count. | |
698 | ||
699 | Can be \c NULL. | |
700 | @endparblock | |
701 | ||
702 | @sa bt_integer_range_set_signed_get_ref() — | |
703 | Increments the reference count of a signed integer range set. | |
704 | */ | |
705 | extern void bt_integer_range_set_signed_put_ref( | |
706 | const bt_integer_range_set_signed *int_range_set); | |
707 | ||
708 | /*! | |
709 | @brief | |
710 | Decrements the reference count of the signed integer range set | |
711 | \bt_p{_int_range_set}, and then sets \bt_p{_int_range_set} to \c | |
712 | NULL. | |
713 | ||
714 | @param _int_range_set | |
715 | @parblock | |
716 | Signed integer range set of which to decrement the reference | |
717 | count. | |
718 | ||
719 | Can contain \c NULL. | |
720 | @endparblock | |
721 | ||
722 | @bt_pre_assign_expr{_int_range_set} | |
723 | */ | |
724 | #define BT_INTEGER_RANGE_SET_SIGNED_PUT_REF_AND_RESET(_int_range_set) \ | |
725 | do { \ | |
726 | bt_integer_range_set_signed_put_ref(_int_range_set); \ | |
727 | (_int_range_set) = NULL; \ | |
728 | } while (0) | |
729 | ||
730 | /*! | |
731 | @brief | |
732 | Decrements the reference count of the signed integer range set | |
733 | \bt_p{_dst}, sets \bt_p{_dst} to \bt_p{_src}, and then sets | |
734 | \bt_p{_src} to \c NULL. | |
735 | ||
736 | This macro effectively moves a signed integer range set reference | |
737 | from the expression \bt_p{_src} to the expression \bt_p{_dst}, putting | |
738 | the existing \bt_p{_dst} reference. | |
739 | ||
740 | @param _dst | |
741 | @parblock | |
742 | Destination expression. | |
743 | ||
744 | Can contain \c NULL. | |
745 | @endparblock | |
746 | @param _src | |
747 | @parblock | |
748 | Source expression. | |
749 | ||
750 | Can contain \c NULL. | |
751 | @endparblock | |
752 | ||
753 | @bt_pre_assign_expr{_dst} | |
754 | @bt_pre_assign_expr{_src} | |
755 | */ | |
756 | #define BT_INTEGER_RANGE_SET_SIGNED_MOVE_REF(_dst, _src) \ | |
757 | do { \ | |
758 | bt_integer_range_set_signed_put_ref(_dst); \ | |
759 | (_dst) = (_src); \ | |
760 | (_src) = NULL; \ | |
761 | } while (0) | |
762 | ||
763 | /*! @} */ | |
764 | ||
765 | /*! @} */ | |
766 | ||
fb91c0ef PP |
767 | #ifdef __cplusplus |
768 | } | |
769 | #endif | |
770 | ||
771 | #endif /* BABELTRACE2_INTEGER_RANGE_SET_H */ |