include/sal/types.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   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/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  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 .
  18  */
  19
  20 /*
  21  * This file is part of LibreOffice published API.
  22  */
  23
  24 #ifndef INCLUDED_SAL_TYPES_H
  25 #define INCLUDED_SAL_TYPES_H
  26
  27 #include "sal/config.h"
  28
  29 #include <stddef.h>
  30
  31 #include "sal/macros.h"
  32 #include "sal/typesizes.h"
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 typedef unsigned char sal_Bool;
  39 #   define sal_False ((sal_Bool)0)
  40 #   define sal_True  ((sal_Bool)1)
  41
  42 /* char is assumed to always be 1 byte long */
  43 typedef signed char         sal_Int8;
  44 typedef unsigned char       sal_uInt8;
  45
  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
  52
  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
  70
  71 #ifdef _MSC_VER
  72     typedef __int64                  sal_Int64;
  73     typedef unsigned __int64         sal_uInt64;
  74
  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
  78
  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;
  87
  88
  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
  92
  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;
 100
 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
 104
 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
 115
 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
 125
 126 typedef void *                   sal_Handle;
 127
 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
 138
 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
 147
 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
 157
 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
 178
 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.
 183  */
 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))
 196
 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
 204
 205 #define SAL_MAX_ENUM 0x7fffffff
 206
 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
 256
 257 /**
 258    Exporting the symbols necessary for exception handling on GCC.
 259
 260    These macros are used for inline declarations of exception classes, as in
 261    rtl/malformeduriexception.hxx.
 262 */
 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
 274
 275 /** Use this as markup for functions and methods whose return value must be
 276     used.
 277
 278     Compilers that support a construct of this nature will emit a compile
 279     time warning on unused return value.
 280 */
 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
 290
 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.
 294
 295     Compilers that support a construct of this nature will emit a compile
 296     time warning on unconditional dereference of returned pointer.
 297 */
 298 #ifdef _MSC_VER
 299 #   define SAL_RET_MAYBENULL _Ret_maybenull_
 300 #else
 301 #   define SAL_RET_MAYBENULL
 302 #endif
 303 #endif
 304
 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.
 308 */
 309 #ifdef _MSC_VER
 310 #   define SAL_NO_VTABLE __declspec(novtable)
 311 #else
 312 #   define SAL_NO_VTABLE
 313 #endif
 314
 315 #ifdef _WIN32
 316 #   pragma pack(push, 8)
 317 #endif
 318
 319 /** This is the binary specification of a SAL sequence.
 320 */
 321 typedef struct _sal_Sequence
 322 {
 323     /** reference count of sequence<br>
 324     */
 325     sal_Int32           nRefCount;
 326     /** element count<br>
 327     */
 328     sal_Int32           nElements;
 329     /** elements array<br>
 330     */
 331     char                elements[1];
 332 } sal_Sequence;
 333
 334 #define SAL_SEQUENCE_HEADER_SIZE ((sal_Size) offsetof(sal_Sequence,elements))
 335
 336 #if defined( _WIN32)
 337 #pragma pack(pop)
 338 #endif
 339
 340 #ifdef __cplusplus
 341 }
 342 #endif /* __cplusplus */
 343
 344 /** Nothrow specification for C functions.
 345
 346     This is a macro so it can expand to nothing in C code.
 347 */
 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
 357
 358 #ifdef __cplusplus
 359
 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
 363 */
 364 #if defined(LIBO_INTERNAL_ONLY) && defined(__COVERITY__)
 365 #   define COVERITY_NOEXCEPT_FALSE noexcept(false)
 366 #else
 367 #   define COVERITY_NOEXCEPT_FALSE
 368 #endif
 369
 370 enum __sal_NoAcquire
 371 {
 372     /** definition of a no acquire enum for ctors
 373     */
 374     SAL_NO_ACQUIRE
 375 };
 376
 377 namespace com { namespace sun { namespace star { } } }
 378
 379 /** short-circuit extra-verbose API namespaces
 380
 381  @since LibreOffice 4.0
 382 */
 383 namespace css = ::com::sun::star;
 384
 385 /** C++11 "= delete" feature.
 386
 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.
 390
 391     @since LibreOffice 4.1
 392 */
 393 #if defined LIBO_INTERNAL_ONLY
 394 #define SAL_DELETED_FUNCTION = delete
 395 #else
 396 #define SAL_DELETED_FUNCTION
 397 #endif
 398
 399 /** C++11 "override" feature.
 400
 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.
 403
 404     @since LibreOffice 4.1
 405 */
 406 #if defined LIBO_INTERNAL_ONLY
 407 #define SAL_OVERRIDE override
 408 #else
 409 #define SAL_OVERRIDE
 410 #endif
 411
 412 /** C++11 "constexpr" feature.
 413
 414     For LIBO_INTERNAL_ONLY, declare that it's possible to evaluate the value
 415     at compile time.
 416
 417     @since LibreOffice 7.2
 418 */
 419 #if defined LIBO_INTERNAL_ONLY
 420 #define SAL_CONSTEXPR constexpr
 421 #else
 422 #define SAL_CONSTEXPR
 423 #endif
 424
 425 /** Macro for C++11 "noexcept" vs. "throw ()" exception specification.
 426
 427     The latter has been removed completely from C++20.
 428
 429     @since LibreOffice 7.2
 430  */
 431 #if __cplusplus >= 201103L
 432 #define SAL_NOEXCEPT noexcept
 433 #else
 434 #define SAL_NOEXCEPT throw ()
 435 #endif
 436
 437 #endif /* __cplusplus */
 438
 439 #ifdef __cplusplus
 440
 441 namespace sal {
 442
 443 /**
 444    A static_cast between integral types, to avoid C++ compiler warnings.
 445
 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.
 451
 452    Both template arguments T1 and T2 must be integral types.
 453 */
 454 template< typename T1, typename T2 > inline T1 static_int_cast(T2 n) {
 455     return static_cast< T1 >(n);
 456 }
 457
 458 }
 459
 460 #else /* __cplusplus */
 461
 462 /**
 463    A cast between integer types, to avoid C compiler warnings.
 464
 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.
 470
 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.
 473 */
 474 #define SAL_INT_CAST(type, expr) ((type) (expr))
 475
 476 #endif /* __cplusplus */
 477
 478 /**
 479     Use as follows:
 480         SAL_DEPRECATED("Don't use, it's evil.") void doit(int nPara);
 481 */
 482
 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
 494
 495 /**
 496    This macro is used in cppumaker-generated include files, to tag entities that
 497    are marked as @deprecated in UNOIDL.
 498
 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.)
 505  */
 506 #ifdef LIBO_INTERNAL_ONLY
 507 #    define SAL_DEPRECATED_INTERNAL(message)
 508 #else
 509 #    define SAL_DEPRECATED_INTERNAL(message) SAL_DEPRECATED(message)
 510 #endif
 511
 512 /**
 513     Use as follows:
 514         SAL_WNODEPRECATED_DECLARATIONS_PUSH
 515         \::std::auto_ptr<X> ...
 516         SAL_WNODEPRECATED_DECLARATIONS_POP
 517 */
 518
 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
 535
 536 /**
 537    Use as follows:
 538
 539    SAL_WNOUNREACHABLE_CODE_PUSH
 540
 541    function definition
 542
 543    SAL_WNOUNREACHABLE_CODE_POP
 544
 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.
 549
 550 */
 551
 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
 564
 565 /** Annotate unused but required C++ function parameters.
 566
 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).
 574
 575     Use the annotation in function definitions like
 576
 577       void f(SAL_UNUSED_PARAMETER int) {}
 578
 579     C does not allow unnamed parameters, anyway, so a function definition like
 580     the above needs to be written there as
 581
 582       void f(int dummy) { (void) dummy; / * avoid warnings * / }
 583
 584     without a SAL_UNUSED_PARAMETER annotation.
 585
 586     @since LibreOffice 3.6
 587  */
 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
 595
 596 /**
 597
 598  Annotate classes where a compiler should warn if an instance is unused.
 599
 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.
 603
 604  @since LibreOffice 4.0
 605
 606 */
 607
 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
 613
 614 /// @cond INTERNAL
 615
 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_;               \
 626         })
 627
 628 /** An optimization annotation: denotes that expression is likely to be true.
 629
 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.
 633
 634     @since LibreOffice 5.2
 635
 636     Returns: the boolean value of expr (expressed as either int 1 or 0)
 637  */
 638 #    define SAL_LIKELY(expr) __builtin_expect(SAL_DETAIL_BOOLEAN_EXPR((expr)), 1)
 639
 640 /** An optimization annotation: denotes that expression is unlikely to be true.
 641
 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.
 645
 646     @since LibreOffice 5.2
 647
 648     Returns: the boolean value of expr (expressed as either int 1 or 0)
 649  */
 650 #    define SAL_UNLIKELY(expr) __builtin_expect(SAL_DETAIL_BOOLEAN_EXPR((expr)), 0)
 651
 652 /** An optimization annotation: tells the compiler to work harder at this code
 653
 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.
 657
 658     In addition this code can end up in a special section, to be
 659     grouped with other frequently used code.
 660
 661     @since LibreOffice 5.2
 662  */
 663 #    define SAL_HOT __attribute__((hot))
 664
 665 /** An optimization annotation: tells the compiler to work less on this code
 666
 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.
 671
 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.
 675
 676     @since LibreOffice 5.2
 677  */
 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
 685
 686 /// @endcond
 687
 688 /// @cond INTERNAL
 689 /** Annotate pointer-returning functions to indicate that such a pointer
 690     is never nullptr.
 691
 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.
 695
 696     @since LibreOffice 5.5
 697 */
 698 #ifndef __has_attribute
 699 #define __has_attribute(x) 0
 700 #endif
 701
 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
 708
 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
 720
 721 #endif // INCLUDED_SAL_TYPES_H
 722
 723 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */