tdf#130857 qt weld: Implement QtInstanceWidget::strip_mnemonic
[LibreOffice.git] / include / sal / types.h
blobeaaf69af250d9301324ea5b8aaa4a6b7c82a96ec
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /*
3 * This file is part of the LibreOffice project.
5 * This Source Code Form is subject to the terms of the Mozilla Public
6 * License, v. 2.0. If a copy of the MPL was not distributed with this
7 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
9 * This file incorporates work covered by the following license notice:
11 * Licensed to the Apache Software Foundation (ASF) under one or more
12 * contributor license agreements. See the NOTICE file distributed
13 * with this work for additional information regarding copyright
14 * ownership. The ASF licenses this file to you under the Apache
15 * License, Version 2.0 (the "License"); you may not use this file
16 * except in compliance with the License. You may obtain a copy of
17 * the License at http://www.apache.org/licenses/LICENSE-2.0 .
21 * This file is part of LibreOffice published API.
24 #ifndef INCLUDED_SAL_TYPES_H
25 #define INCLUDED_SAL_TYPES_H
27 #include "sal/config.h"
29 #include <stddef.h>
31 #include "sal/macros.h"
32 #include "sal/typesizes.h"
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
38 typedef unsigned char sal_Bool;
39 # define sal_False ((sal_Bool)0)
40 # define sal_True ((sal_Bool)1)
42 /* char is assumed to always be 1 byte long */
43 typedef signed char sal_Int8;
44 typedef unsigned char sal_uInt8;
46 #if SAL_TYPES_SIZEOFSHORT == 2
47 typedef signed short sal_Int16;
48 typedef unsigned short sal_uInt16;
49 #else
50 #error "Could not find 16-bit type, add support for your architecture"
51 #endif
53 #if SAL_TYPES_SIZEOFLONG == 4
54 typedef signed long sal_Int32;
55 typedef unsigned long sal_uInt32;
56 #define SAL_PRIdINT32 "ld"
57 #define SAL_PRIuUINT32 "lu"
58 #define SAL_PRIxUINT32 "lx"
59 #define SAL_PRIXUINT32 "lX"
60 #elif SAL_TYPES_SIZEOFINT == 4
61 typedef signed int sal_Int32;
62 typedef unsigned int sal_uInt32;
63 #define SAL_PRIdINT32 "d"
64 #define SAL_PRIuUINT32 "u"
65 #define SAL_PRIxUINT32 "x"
66 #define SAL_PRIXUINT32 "X"
67 #else
68 #error "Could not find 32-bit type, add support for your architecture"
69 #endif
71 #ifdef _MSC_VER
72 typedef __int64 sal_Int64;
73 typedef unsigned __int64 sal_uInt64;
75 /* The following are macros that will add the 64 bit constant suffix. */
76 #define SAL_CONST_INT64(x) x##i64
77 #define SAL_CONST_UINT64(x) x##ui64
79 #define SAL_PRIdINT64 "I64d"
80 #define SAL_PRIuUINT64 "I64u"
81 #define SAL_PRIxUINT64 "I64x"
82 #define SAL_PRIXUINT64 "I64X"
83 #elif defined (__GNUC__)
84 #if SAL_TYPES_SIZEOFLONG == 8
85 typedef signed long int sal_Int64;
86 typedef unsigned long int sal_uInt64;
89 /* The following are macros that will add the 64 bit constant suffix. */
90 #define SAL_CONST_INT64(x) x##l
91 #define SAL_CONST_UINT64(x) x##ul
93 #define SAL_PRIdINT64 "ld"
94 #define SAL_PRIuUINT64 "lu"
95 #define SAL_PRIxUINT64 "lx"
96 #define SAL_PRIXUINT64 "lX"
97 #elif SAL_TYPES_SIZEOFLONGLONG == 8
98 typedef signed long long sal_Int64;
99 typedef unsigned long long sal_uInt64;
101 /* The following are macros that will add the 64 bit constant suffix. */
102 #define SAL_CONST_INT64(x) x##ll
103 #define SAL_CONST_UINT64(x) x##ull
105 #define SAL_PRIdINT64 "lld"
106 #define SAL_PRIuUINT64 "llu"
107 #define SAL_PRIxUINT64 "llx"
108 #define SAL_PRIXUINT64 "llX"
109 #else
110 #error "Could not find 64-bit type, add support for your architecture"
111 #endif
112 #else
113 #error "Please define the 64-bit types for your architecture/compiler in include/sal/types.h"
114 #endif
116 #if defined LIBO_INTERNAL_ONLY && defined __cplusplus
117 #define SAL_UNICODE_NOTEQUAL_WCHAR_T
118 typedef char16_t sal_Unicode;
119 #elif defined(_WIN32)
120 typedef wchar_t sal_Unicode;
121 #else
122 #define SAL_UNICODE_NOTEQUAL_WCHAR_T
123 typedef sal_uInt16 sal_Unicode;
124 #endif
126 typedef void * sal_Handle;
128 /* sal_Size should currently be the native width of the platform */
129 #if SAL_TYPES_SIZEOFPOINTER == 4
130 typedef sal_uInt32 sal_Size;
131 typedef sal_Int32 sal_sSize;
132 #elif SAL_TYPES_SIZEOFPOINTER == 8
133 typedef sal_uInt64 sal_Size;
134 typedef sal_Int64 sal_sSize;
135 #else
136 #error "Please make sure SAL_TYPES_SIZEOFPOINTER is defined for your architecture/compiler"
137 #endif
139 /* sal_PtrDiff holds the result of a pointer subtraction */
140 #if SAL_TYPES_SIZEOFPOINTER == 4
141 typedef sal_Int32 sal_PtrDiff;
142 #elif SAL_TYPES_SIZEOFPOINTER == 8
143 typedef sal_Int64 sal_PtrDiff;
144 #else
145 #error "Please make sure SAL_TYPES_SIZEOFPOINTER is defined for your architecture/compiler"
146 #endif
148 /* printf-style conversion specification length modifiers for size_t and
149 ptrdiff_t (most platforms support C99, MSC has its own extension) */
150 #if defined(_MSC_VER)
151 #define SAL_PRI_SIZET "I"
152 #define SAL_PRI_PTRDIFFT "I"
153 #else
154 #define SAL_PRI_SIZET "z"
155 #define SAL_PRI_PTRDIFFT "t"
156 #endif
158 /* sal_IntPtr, sal_uIntPtr are integer types designed to hold pointers so that any valid
159 * pointer to void can be converted to this type and back to a pointer to void and the
160 * result will compare to the original pointer */
161 #if SAL_TYPES_SIZEOFPOINTER == 4
162 typedef sal_Int32 sal_IntPtr;
163 typedef sal_uInt32 sal_uIntPtr;
164 #define SAL_PRIdINTPTR SAL_PRIdINT32
165 #define SAL_PRIuUINTPTR SAL_PRIuUINT32
166 #define SAL_PRIxUINTPTR SAL_PRIxUINT32
167 #define SAL_PRIXUINTPTR SAL_PRIXUINT32
168 #elif SAL_TYPES_SIZEOFPOINTER == 8
169 typedef sal_Int64 sal_IntPtr;
170 typedef sal_uInt64 sal_uIntPtr;
171 #define SAL_PRIdINTPTR SAL_PRIdINT64
172 #define SAL_PRIuUINTPTR SAL_PRIuUINT64
173 #define SAL_PRIxUINTPTR SAL_PRIxUINT64
174 #define SAL_PRIXUINTPTR SAL_PRIXUINT64
175 #else
176 #error "Please make sure SAL_TYPES_SIZEOFPOINTER is defined for your architecture/compiler"
177 #endif
179 /* The following SAL_MIN_INTn defines codify the assumption that the signed
180 * sal_Int types use two's complement representation. Defining them as
181 * "-0x7F... - 1" instead of as "-0x80..." prevents warnings about applying the
182 * unary minus operator to unsigned quantities.
184 #define SAL_MIN_INT8 ((sal_Int8) (-0x7F - 1))
185 #define SAL_MAX_INT8 ((sal_Int8) 0x7F)
186 #define SAL_MAX_UINT8 ((sal_uInt8) 0xFF)
187 #define SAL_MIN_INT16 ((sal_Int16) (-0x7FFF - 1))
188 #define SAL_MAX_INT16 ((sal_Int16) 0x7FFF)
189 #define SAL_MAX_UINT16 ((sal_uInt16) 0xFFFF)
190 #define SAL_MIN_INT32 ((sal_Int32) (-0x7FFFFFFF - 1))
191 #define SAL_MAX_INT32 ((sal_Int32) 0x7FFFFFFF)
192 #define SAL_MAX_UINT32 ((sal_uInt32) 0xFFFFFFFF)
193 #define SAL_MIN_INT64 ((sal_Int64) (SAL_CONST_INT64(-0x7FFFFFFFFFFFFFFF) - 1))
194 #define SAL_MAX_INT64 ((sal_Int64) SAL_CONST_INT64(0x7FFFFFFFFFFFFFFF))
195 #define SAL_MAX_UINT64 ((sal_uInt64) SAL_CONST_UINT64(0xFFFFFFFFFFFFFFFF))
197 #if SAL_TYPES_SIZEOFPOINTER == 4
198 #define SAL_MAX_SSIZE SAL_MAX_INT32
199 #define SAL_MAX_SIZE SAL_MAX_UINT32
200 #elif SAL_TYPES_SIZEOFPOINTER == 8
201 #define SAL_MAX_SSIZE SAL_MAX_INT64
202 #define SAL_MAX_SIZE SAL_MAX_UINT64
203 #endif
205 #define SAL_MAX_ENUM 0x7fffffff
207 #if defined(_MSC_VER)
208 # define SAL_DLLPUBLIC_EXPORT __declspec(dllexport)
209 # define SAL_JNI_EXPORT __declspec(dllexport)
210 # define SAL_DLLPUBLIC_IMPORT __declspec(dllimport)
211 # define SAL_DLLPRIVATE
212 # define SAL_DLLPUBLIC_TEMPLATE
213 # define SAL_DLLPUBLIC_RTTI
214 # define SAL_CALL __cdecl
215 #elif defined SAL_UNX
216 # if defined(__GNUC__)
217 # if defined(DISABLE_DYNLOADING)
218 # define SAL_DLLPUBLIC_EXPORT __attribute__ ((visibility("hidden")))
219 # define SAL_JNI_EXPORT __attribute__ ((visibility("default")))
220 # define SAL_DLLPUBLIC_IMPORT __attribute__ ((visibility("hidden")))
221 # define SAL_DLLPRIVATE __attribute__ ((visibility("hidden")))
222 # define SAL_DLLPUBLIC_TEMPLATE __attribute__ ((visibility("hidden")))
223 # define SAL_DLLPUBLIC_RTTI __attribute__ ((visibility("default")))
224 # else
225 # define SAL_DLLPUBLIC_EXPORT __attribute__ ((visibility("default")))
226 # define SAL_JNI_EXPORT __attribute__ ((visibility("default")))
227 # define SAL_DLLPUBLIC_IMPORT __attribute__ ((visibility("default")))
228 # define SAL_DLLPRIVATE __attribute__ ((visibility("hidden")))
229 # define SAL_DLLPUBLIC_TEMPLATE __attribute__ ((visibility("default")))
230 # if defined __clang__
231 # if __has_attribute(type_visibility)
232 # define SAL_DLLPUBLIC_RTTI __attribute__ ((type_visibility("default")))
233 # else
234 # define SAL_DLLPUBLIC_RTTI __attribute__ ((visibility("default")))
235 # endif
236 # else
237 // GCC does not have currently have equivalent functionality to clang's type_visibility
238 // but I have a feature request for that at https://gcc.gnu.org/bugzilla/show_bug.cgi?id=113958
239 // Until that is implemented, just make the whole class visible, which is what I would need to
240 // do anyhow if something wants to import the typeinfo symbol.
241 # define SAL_DLLPUBLIC_RTTI __attribute__ ((visibility("default")))
242 # endif
243 # endif
244 # else
245 # define SAL_DLLPUBLIC_EXPORT
246 # define SAL_JNI_EXPORT
247 # define SAL_DLLPUBLIC_IMPORT
248 # define SAL_DLLPRIVATE
249 # define SAL_DLLPUBLIC_TEMPLATE
250 # define SAL_DLLPUBLIC_RTTI
251 # endif
252 # define SAL_CALL
253 #else
254 # error("unknown platform")
255 #endif
258 Exporting the symbols necessary for exception handling on GCC.
260 These macros are used for inline declarations of exception classes, as in
261 rtl/malformeduriexception.hxx.
263 #if defined(__GNUC__)
264 # if defined(DISABLE_DYNLOADING)
265 # define SAL_EXCEPTION_DLLPUBLIC_EXPORT __attribute__((visibility("default")))
266 # else
267 # define SAL_EXCEPTION_DLLPUBLIC_EXPORT SAL_DLLPUBLIC_EXPORT
268 # endif
269 # define SAL_EXCEPTION_DLLPRIVATE SAL_DLLPRIVATE
270 #else
271 # define SAL_EXCEPTION_DLLPUBLIC_EXPORT
272 # define SAL_EXCEPTION_DLLPRIVATE
273 #endif
275 /** Use this as markup for functions and methods whose return value must be
276 used.
278 Compilers that support a construct of this nature will emit a compile
279 time warning on unused return value.
281 #if defined LIBO_INTERNAL_ONLY && defined __cplusplus
282 #define SAL_WARN_UNUSED_RESULT [[nodiscard]]
283 #elif (defined __GNUC__ \
284 && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 1))) \
285 || defined __clang__
286 # define SAL_WARN_UNUSED_RESULT __attribute__((warn_unused_result))
287 #else
288 # define SAL_WARN_UNUSED_RESULT
289 #endif
291 #if defined LIBO_INTERNAL_ONLY
292 /** Use this as markup for functions and methods whose return value may be
293 null and should not be dereferenced unconditionally.
295 Compilers that support a construct of this nature will emit a compile
296 time warning on unconditional dereference of returned pointer.
298 #ifdef _MSC_VER
299 # define SAL_RET_MAYBENULL _Ret_maybenull_
300 #else
301 # define SAL_RET_MAYBENULL
302 #endif
303 #endif
305 /** Use this for pure virtual classes, e.g. class SAL_NO_VTABLE Foo { ...
306 This hinders the compiler from setting a generic vtable stating that
307 a pure virtual function was called and thus slightly reduces code size.
309 #ifdef _MSC_VER
310 # define SAL_NO_VTABLE __declspec(novtable)
311 #else
312 # define SAL_NO_VTABLE
313 #endif
315 #ifdef _WIN32
316 # pragma pack(push, 8)
317 #endif
319 /** This is the binary specification of a SAL sequence.
321 typedef struct _sal_Sequence
323 /** reference count of sequence<br>
325 sal_Int32 nRefCount;
326 /** element count<br>
328 sal_Int32 nElements;
329 /** elements array<br>
331 char elements[1];
332 } sal_Sequence;
334 #define SAL_SEQUENCE_HEADER_SIZE ((sal_Size) offsetof(sal_Sequence,elements))
336 #if defined( _WIN32)
337 #pragma pack(pop)
338 #endif
340 #ifdef __cplusplus
342 #endif /* __cplusplus */
344 /** Nothrow specification for C functions.
346 This is a macro so it can expand to nothing in C code.
348 #if defined __cplusplus
349 #if __cplusplus >= 201103L
350 #define SAL_THROW_EXTERN_C() noexcept
351 #else
352 #define SAL_THROW_EXTERN_C() throw ()
353 #endif
354 #else
355 #define SAL_THROW_EXTERN_C()
356 #endif
358 #ifdef __cplusplus
360 /** To markup destructors that coverity warns might throw exceptions
361 which won't throw in practice, or where std::terminate is
362 an acceptable response if they do
364 #if defined(LIBO_INTERNAL_ONLY) && defined(__COVERITY__) && __COVERITY_MAJOR__ <= 2023
365 # define COVERITY_NOEXCEPT_FALSE noexcept(false)
366 #else
367 # define COVERITY_NOEXCEPT_FALSE
368 #endif
370 enum __sal_NoAcquire
372 /** definition of a no acquire enum for ctors
374 SAL_NO_ACQUIRE
377 namespace com { namespace sun { namespace star { } } }
379 /** short-circuit extra-verbose API namespaces
381 @since LibreOffice 4.0
383 namespace css = ::com::sun::star;
385 /** C++11 "= delete" feature.
387 For LIBO_INTERNAL_ONLY, calling a deleted function will cause a compile-time
388 error, while otherwise it will only cause a link-time error as the declared
389 function is not defined.
391 @since LibreOffice 4.1
393 #if defined LIBO_INTERNAL_ONLY
394 #define SAL_DELETED_FUNCTION = delete
395 #else
396 #define SAL_DELETED_FUNCTION
397 #endif
399 /** C++11 "override" feature.
401 For LIBO_INTERNAL_ONLY, force the method to override an existing method in
402 parent, error out if the method with the correct signature does not exist.
404 @since LibreOffice 4.1
406 #if defined LIBO_INTERNAL_ONLY
407 #define SAL_OVERRIDE override
408 #else
409 #define SAL_OVERRIDE
410 #endif
412 /** C++11 "constexpr" feature.
414 For LIBO_INTERNAL_ONLY, declare that it's possible to evaluate the value
415 at compile time.
417 @since LibreOffice 7.2
419 #if defined LIBO_INTERNAL_ONLY
420 #define SAL_CONSTEXPR constexpr
421 #else
422 #define SAL_CONSTEXPR
423 #endif
425 /** Macro for C++11 "noexcept" vs. "throw ()" exception specification.
427 The latter has been removed completely from C++20.
429 @since LibreOffice 7.2
431 #if __cplusplus >= 201103L
432 #define SAL_NOEXCEPT noexcept
433 #else
434 #define SAL_NOEXCEPT throw ()
435 #endif
437 #endif /* __cplusplus */
439 #ifdef __cplusplus
441 namespace sal {
444 A static_cast between integral types, to avoid C++ compiler warnings.
446 In C++ source code, use sal::static_int_cast<T>(n) instead of
447 static_cast<T>(n) whenever a compiler warning about integral type problems
448 shall be silenced. That way, source code that needs to be modified when the
449 type of any of the expressions involved in the compiler warning is changed
450 can be found more easily.
452 Both template arguments T1 and T2 must be integral types.
454 template< typename T1, typename T2 > inline T1 static_int_cast(T2 n) {
455 return static_cast< T1 >(n);
460 #else /* __cplusplus */
463 A cast between integer types, to avoid C compiler warnings.
465 In C source code, use SAL_INT_CAST(type, expr) instead of ((type) (expr))
466 whenever a compiler warning about integer type problems shall be silenced.
467 That way, source code that needs to be modified when the type of any of the
468 expressions involved in the compiler warning is changed can be found more
469 easily.
471 The argument 'type' must be an integer type and the argument 'expr' must be
472 an integer expression. Both arguments are evaluated exactly once.
474 #define SAL_INT_CAST(type, expr) ((type) (expr))
476 #endif /* __cplusplus */
479 Use as follows:
480 SAL_DEPRECATED("Don't use, it's evil.") void doit(int nPara);
483 #if defined __GNUC__ || defined __clang__
484 #if defined LIBO_INTERNAL_ONLY
485 # define SAL_DEPRECATED(message) __attribute__((deprecated(message)))
486 #else
487 # define SAL_DEPRECATED(message) __attribute__((deprecated))
488 #endif
489 #elif defined(_MSC_VER)
490 # define SAL_DEPRECATED(message) __declspec(deprecated(message))
491 #else
492 # define SAL_DEPRECATED(message)
493 #endif
496 This macro is used in cppumaker-generated include files, to tag entities that
497 are marked as @deprecated in UNOIDL.
499 It causes deprecation warnings to be generated in external code, but for now
500 is silenced in internal code. It would need some substantial clean-up of
501 internal code to fix all warnings/errors generated by it. (Once that is
502 done, it can become a synonym for SAL_DEPRECATED under LIBO_INTERNAL_ONLY,
503 too. Completely removing the macro then would be incompatible, in case there
504 are include files still around generated with a cppumaker that emitted it.)
506 #ifdef LIBO_INTERNAL_ONLY
507 # define SAL_DEPRECATED_INTERNAL(message)
508 #else
509 # define SAL_DEPRECATED_INTERNAL(message) SAL_DEPRECATED(message)
510 #endif
513 Use as follows:
514 SAL_WNODEPRECATED_DECLARATIONS_PUSH
515 \::std::auto_ptr<X> ...
516 SAL_WNODEPRECATED_DECLARATIONS_POP
519 #if defined LIBO_INTERNAL_ONLY && defined __GNUC__
520 #define SAL_WNODEPRECATED_DECLARATIONS_PUSH \
521 _Pragma(SAL_STRINGIFY_ARG(GCC diagnostic push)) \
522 _Pragma(SAL_STRINGIFY_ARG(GCC diagnostic ignored "-Wdeprecated-declarations"))
523 #define SAL_WNODEPRECATED_DECLARATIONS_POP \
524 _Pragma(SAL_STRINGIFY_ARG(GCC diagnostic pop))
525 #elif defined LIBO_INTERNAL_ONLY && defined _MSC_VER
526 #define SAL_WNODEPRECATED_DECLARATIONS_PUSH \
527 _Pragma(SAL_STRINGIFY_ARG(warning(push))) \
528 _Pragma(SAL_STRINGIFY_ARG(warning(disable : 4996)))
529 #define SAL_WNODEPRECATED_DECLARATIONS_POP \
530 _Pragma(SAL_STRINGIFY_ARG(warning(pop)))
531 #else
532 # define SAL_WNODEPRECATED_DECLARATIONS_PUSH
533 # define SAL_WNODEPRECATED_DECLARATIONS_POP
534 #endif
537 Use as follows:
539 SAL_WNOUNREACHABLE_CODE_PUSH
541 function definition
543 SAL_WNOUNREACHABLE_CODE_POP
545 Useful in cases where the compiler is "too clever" like when doing
546 link-time code generation, and noticing that a called function
547 always throws, and fixing the problem cleanly so that it produces
548 no warnings in normal non-LTO compilations either is not easy.
552 #ifdef _MSC_VER
553 #define SAL_WNOUNREACHABLE_CODE_PUSH \
554 __pragma(warning(push)) \
555 __pragma(warning(disable:4702)) \
556 __pragma(warning(disable:4722))
557 #define SAL_WNOUNREACHABLE_CODE_POP \
558 __pragma(warning(pop))
559 #else
560 /* Add definitions for GCC and Clang if needed */
561 #define SAL_WNOUNREACHABLE_CODE_PUSH
562 #define SAL_WNOUNREACHABLE_CODE_POP
563 #endif
565 /** Annotate unused but required C++ function parameters.
567 An unused parameter is required if the function needs to adhere to a given
568 type (e.g., if its address is assigned to a function pointer of a specific
569 type, or if it is called from template code). This annotation helps static
570 analysis tools suppress false warnings. In the case of virtual functions
571 (where unused required parameters are common, too), the annotation is not
572 required (as static analysis tools can themselves derive the information
573 whether a function is virtual).
575 Use the annotation in function definitions like
577 void f(SAL_UNUSED_PARAMETER int) {}
579 C does not allow unnamed parameters, anyway, so a function definition like
580 the above needs to be written there as
582 void f(int dummy) { (void) dummy; / * avoid warnings * / }
584 without a SAL_UNUSED_PARAMETER annotation.
586 @since LibreOffice 3.6
588 #if defined __cplusplus
589 #if defined __GNUC__ || defined __clang__
590 #define SAL_UNUSED_PARAMETER __attribute__ ((unused))
591 #else
592 #define SAL_UNUSED_PARAMETER
593 #endif
594 #endif
598 Annotate classes where a compiler should warn if an instance is unused.
600 The compiler cannot warn about unused instances if they have non-trivial
601 or external constructors or destructors. Classes marked with SAL_WARN_UNUSED
602 will be warned about.
604 @since LibreOffice 4.0
608 #if defined LIBO_INTERNAL_ONLY && (defined __GNUC__ || defined __clang__)
609 #define SAL_WARN_UNUSED __attribute__((warn_unused))
610 #else
611 #define SAL_WARN_UNUSED
612 #endif
614 /// @cond INTERNAL
616 #if defined __GNUC__ || defined __clang__
617 // Macro to try to catch and warn on assignments inside expr.
618 # define SAL_DETAIL_BOOLEAN_EXPR(expr) \
619 __extension__ ({ \
620 int sal_boolean_var_; \
621 if (expr) \
622 sal_boolean_var_ = 1; \
623 else \
624 sal_boolean_var_ = 0; \
625 sal_boolean_var_; \
628 /** An optimization annotation: denotes that expression is likely to be true.
630 Use it to annotate paths that we think are likely eg.
631 if (SAL_LIKELY(ptr != nullptr))
632 // this path is the one that is ~always taken.
634 @since LibreOffice 5.2
636 Returns: the boolean value of expr (expressed as either int 1 or 0)
638 # define SAL_LIKELY(expr) __builtin_expect(SAL_DETAIL_BOOLEAN_EXPR((expr)), 1)
640 /** An optimization annotation: denotes that expression is unlikely to be true.
642 Use it to annotate paths that we think are likely eg.
643 if (SAL_UNLIKELY(ptr != nullptr))
644 // this path is the one that is ~never taken.
646 @since LibreOffice 5.2
648 Returns: the boolean value of expr (expressed as either int 1 or 0)
650 # define SAL_UNLIKELY(expr) __builtin_expect(SAL_DETAIL_BOOLEAN_EXPR((expr)), 0)
652 /** An optimization annotation: tells the compiler to work harder at this code
654 If the SAL_HOT annotation is present on a function or a label then
655 subsequent code statements may have more aggressive compiler
656 optimization and in-lining work performed on them.
658 In addition this code can end up in a special section, to be
659 grouped with other frequently used code.
661 @since LibreOffice 5.2
663 # define SAL_HOT __attribute__((hot))
665 /** An optimization annotation: tells the compiler to work less on this code
667 If the SAL_COLD annotation is present on a function or a label then
668 subsequent code statements are unlikely to be performed except in
669 exceptional circumstances, and optimizing for code-size rather
670 than performance is preferable.
672 In addition this code can end up in a special section, to be grouped
673 with (and away from) other more frequently used code, to improve
674 locality of reference.
676 @since LibreOffice 5.2
678 # define SAL_COLD __attribute__((cold))
679 #else
680 # define SAL_LIKELY(expr) (expr)
681 # define SAL_UNLIKELY(expr) (expr)
682 # define SAL_HOT
683 # define SAL_COLD
684 #endif
686 /// @endcond
688 /// @cond INTERNAL
689 /** Annotate pointer-returning functions to indicate that such a pointer
690 is never nullptr.
692 Note that MSVC supports this feature via it's SAL _Ret_notnull_
693 annotation, but since it's in a completely different place on
694 the function declaration, it's a little hard to support both.
696 @since LibreOffice 5.5
698 #ifndef __has_attribute
699 #define __has_attribute(x) 0
700 #endif
702 #if defined LIBO_INTERNAL_ONLY && ((defined __GNUC__ && !defined __clang__) || (defined __clang__ && __has_attribute(returns_nonnull)))
703 #define SAL_RETURNS_NONNULL __attribute__((returns_nonnull))
704 #else
705 #define SAL_RETURNS_NONNULL
706 #endif
707 /// @endcond
709 #if defined LIBO_INTERNAL_ONLY
710 // An annotation mechanism used by some loplugins. The id argument must be an ordinary string
711 // literal. For Clang, this expands to a clang::annotate attribute with an annotation consisting of
712 // the concatenation of a "loplugin:" prefix and the given id suffix. For non-Clang, this expands
713 // to nothing to avoid e.g. -Wattributes from GCC's -Wall.
714 #if defined __clang__
715 #define SAL_LOPLUGIN_ANNOTATE(id) [[clang::annotate("loplugin:" id)]]
716 #else
717 #define SAL_LOPLUGIN_ANNOTATE(id)
718 #endif
719 #endif
721 #endif // INCLUDED_SAL_TYPES_H
723 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */