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