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
 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 #         define SAL_DLLPUBLIC_RTTI
 238 #       endif
 239 #     endif
 240 #   else
 241 #     define SAL_DLLPUBLIC_EXPORT
 242 #     define SAL_JNI_EXPORT
 243 #     define SAL_DLLPUBLIC_IMPORT
 244 #     define SAL_DLLPRIVATE
 245 #     define SAL_DLLPUBLIC_TEMPLATE
 246 #     define SAL_DLLPUBLIC_RTTI
 247 #   endif
 248 #   define SAL_CALL
 249 #else
 250 #   error("unknown platform")
 251 #endif
 252
 253 /**
 254    Exporting the symbols necessary for exception handling on GCC.
 255
 256    These macros are used for inline declarations of exception classes, as in
 257    rtl/malformeduriexception.hxx.
 258 */
 259 #if defined(__GNUC__)
 260 #   if defined(DISABLE_DYNLOADING)
 261 #      define SAL_EXCEPTION_DLLPUBLIC_EXPORT __attribute__((visibility("default")))
 262 #    else
 263 #      define SAL_EXCEPTION_DLLPUBLIC_EXPORT SAL_DLLPUBLIC_EXPORT
 264 #    endif
 265 #    define SAL_EXCEPTION_DLLPRIVATE SAL_DLLPRIVATE
 266 #else
 267 #    define SAL_EXCEPTION_DLLPUBLIC_EXPORT
 268 #    define SAL_EXCEPTION_DLLPRIVATE
 269 #endif
 270
 271 /** Use this as markup for functions and methods whose return value must be
 272     checked.
 273
 274     Compilers that support a construct of this nature will emit a compile
 275     time warning on unchecked return value.
 276 */
 277 #if defined LIBO_INTERNAL_ONLY && defined __cplusplus
 278 #define SAL_WARN_UNUSED_RESULT [[nodiscard]]
 279 #elif (defined __GNUC__ \
 280      && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 1))) \
 281     || defined __clang__
 282 #   define SAL_WARN_UNUSED_RESULT __attribute__((warn_unused_result))
 283 #else
 284 #   define SAL_WARN_UNUSED_RESULT
 285 #endif
 286
 287 /** Use this for pure virtual classes, e.g. class SAL_NO_VTABLE Foo { ...
 288     This hinders the compiler from setting a generic vtable stating that
 289     a pure virtual function was called and thus slightly reduces code size.
 290 */
 291 #ifdef _MSC_VER
 292 #   define SAL_NO_VTABLE __declspec(novtable)
 293 #else
 294 #   define SAL_NO_VTABLE
 295 #endif
 296
 297 #ifdef _WIN32
 298 #   pragma pack(push, 8)
 299 #endif
 300
 301 /** This is the binary specification of a SAL sequence.
 302 */
 303 typedef struct _sal_Sequence
 304 {
 305     /** reference count of sequence<br>
 306     */
 307     sal_Int32           nRefCount;
 308     /** element count<br>
 309     */
 310     sal_Int32           nElements;
 311     /** elements array<br>
 312     */
 313     char                elements[1];
 314 } sal_Sequence;
 315
 316 #define SAL_SEQUENCE_HEADER_SIZE ((sal_Size) offsetof(sal_Sequence,elements))
 317
 318 #if defined( _WIN32)
 319 #pragma pack(pop)
 320 #endif
 321
 322 #ifdef __cplusplus
 323 }
 324 #endif /* __cplusplus */
 325
 326 /** Nothrow specification for C functions.
 327
 328     This is a macro so it can expand to nothing in C code.
 329 */
 330 #if defined __cplusplus
 331 #if __cplusplus >= 201103L
 332 #define SAL_THROW_EXTERN_C() noexcept
 333 #else
 334 #define SAL_THROW_EXTERN_C() throw ()
 335 #endif
 336 #else
 337 #define SAL_THROW_EXTERN_C()
 338 #endif
 339
 340 #ifdef __cplusplus
 341
 342 /** To markup destructors that coverity warns might throw exceptions
 343     which won't throw in practice, or where std::terminate is
 344     an acceptable response if they do
 345 */
 346 #if defined(LIBO_INTERNAL_ONLY) && defined(__COVERITY__)
 347 #   define COVERITY_NOEXCEPT_FALSE noexcept(false)
 348 #else
 349 #   define COVERITY_NOEXCEPT_FALSE
 350 #endif
 351
 352 enum __sal_NoAcquire
 353 {
 354     /** definition of a no acquire enum for ctors
 355     */
 356     SAL_NO_ACQUIRE
 357 };
 358
 359 namespace com { namespace sun { namespace star { } } }
 360
 361 /** short-circuit extra-verbose API namespaces
 362
 363  @since LibreOffice 4.0
 364 */
 365 namespace css = ::com::sun::star;
 366
 367 /** C++11 "= delete" feature.
 368
 369     For LIBO_INTERNAL_ONLY, calling a deleted function will cause a compile-time
 370     error, while otherwise it will only cause a link-time error as the declared
 371     function is not defined.
 372
 373     @since LibreOffice 4.1
 374 */
 375 #if defined LIBO_INTERNAL_ONLY
 376 #define SAL_DELETED_FUNCTION = delete
 377 #else
 378 #define SAL_DELETED_FUNCTION
 379 #endif
 380
 381 /** C++11 "override" feature.
 382
 383     For LIBO_INTERNAL_ONLY, force the method to override an existing method in
 384     parent, error out if the method with the correct signature does not exist.
 385
 386     @since LibreOffice 4.1
 387 */
 388 #if defined LIBO_INTERNAL_ONLY
 389 #define SAL_OVERRIDE override
 390 #else
 391 #define SAL_OVERRIDE
 392 #endif
 393
 394 /** C++11 "constexpr" feature.
 395
 396     For LIBO_INTERNAL_ONLY, declare that it's possible to evaluate the value
 397     at compile time.
 398
 399     @since LibreOffice 7.2
 400 */
 401 #if defined LIBO_INTERNAL_ONLY
 402 #define SAL_CONSTEXPR constexpr
 403 #else
 404 #define SAL_CONSTEXPR
 405 #endif
 406
 407 /** Macro for C++11 "noexcept" vs. "throw ()" exception specification.
 408
 409     The latter has been removed completely from C++20.
 410
 411     @since LibreOffice 7.2
 412  */
 413 #if __cplusplus >= 201103L
 414 #define SAL_NOEXCEPT noexcept
 415 #else
 416 #define SAL_NOEXCEPT throw ()
 417 #endif
 418
 419 #endif /* __cplusplus */
 420
 421 #ifdef __cplusplus
 422
 423 namespace sal {
 424
 425 /**
 426    A static_cast between integral types, to avoid C++ compiler warnings.
 427
 428    In C++ source code, use sal::static_int_cast<T>(n) instead of
 429    static_cast<T>(n) whenever a compiler warning about integral type problems
 430    shall be silenced.  That way, source code that needs to be modified when the
 431    type of any of the expressions involved in the compiler warning is changed
 432    can be found more easily.
 433
 434    Both template arguments T1 and T2 must be integral types.
 435 */
 436 template< typename T1, typename T2 > inline T1 static_int_cast(T2 n) {
 437     return static_cast< T1 >(n);
 438 }
 439
 440 }
 441
 442 #else /* __cplusplus */
 443
 444 /**
 445    A cast between integer types, to avoid C compiler warnings.
 446
 447    In C source code, use SAL_INT_CAST(type, expr) instead of ((type) (expr))
 448    whenever a compiler warning about integer type problems shall be silenced.
 449    That way, source code that needs to be modified when the type of any of the
 450    expressions involved in the compiler warning is changed can be found more
 451    easily.
 452
 453    The argument 'type' must be an integer type and the argument 'expr' must be
 454    an integer expression.  Both arguments are evaluated exactly once.
 455 */
 456 #define SAL_INT_CAST(type, expr) ((type) (expr))
 457
 458 #endif /* __cplusplus */
 459
 460 /**
 461     Use as follows:
 462         SAL_DEPRECATED("Don't use, it's evil.") void doit(int nPara);
 463 */
 464
 465 #if defined __GNUC__ || defined __clang__
 466 #if defined LIBO_INTERNAL_ONLY
 467 #    define SAL_DEPRECATED(message) __attribute__((deprecated(message)))
 468 #else
 469 #    define SAL_DEPRECATED(message) __attribute__((deprecated))
 470 #endif
 471 #elif defined(_MSC_VER)
 472 #    define SAL_DEPRECATED(message) __declspec(deprecated(message))
 473 #else
 474 #    define SAL_DEPRECATED(message)
 475 #endif
 476
 477 /**
 478    This macro is used in cppumaker-generated include files, to tag entities that
 479    are marked as @deprecated in UNOIDL.
 480
 481    It causes deprecation warnings to be generated in external code, but for now
 482    is silenced in internal code.  It would need some substantial clean-up of
 483    internal code to fix all warnings/errors generated by it.  (Once that is
 484    done, it can become a synonym for SAL_DEPRECATED under LIBO_INTERNAL_ONLY,
 485    too.  Completely removing the macro then would be incompatible, in case there
 486    are include files still around generated with a cppumaker that emitted it.)
 487  */
 488 #ifdef LIBO_INTERNAL_ONLY
 489 #    define SAL_DEPRECATED_INTERNAL(message)
 490 #else
 491 #    define SAL_DEPRECATED_INTERNAL(message) SAL_DEPRECATED(message)
 492 #endif
 493
 494 /**
 495     Use as follows:
 496         SAL_WNODEPRECATED_DECLARATIONS_PUSH
 497         \::std::auto_ptr<X> ...
 498         SAL_WNODEPRECATED_DECLARATIONS_POP
 499 */
 500
 501 #if defined LIBO_INTERNAL_ONLY && defined __GNUC__
 502 #define SAL_WNODEPRECATED_DECLARATIONS_PUSH \
 503     _Pragma(SAL_STRINGIFY_ARG(GCC diagnostic push)) \
 504     _Pragma(SAL_STRINGIFY_ARG(GCC diagnostic ignored "-Wdeprecated-declarations"))
 505 #define SAL_WNODEPRECATED_DECLARATIONS_POP \
 506     _Pragma(SAL_STRINGIFY_ARG(GCC diagnostic pop))
 507 #elif defined LIBO_INTERNAL_ONLY && defined _MSC_VER
 508 #define SAL_WNODEPRECATED_DECLARATIONS_PUSH \
 509     _Pragma(SAL_STRINGIFY_ARG(warning(push))) \
 510     _Pragma(SAL_STRINGIFY_ARG(warning(disable : 4996)))
 511 #define SAL_WNODEPRECATED_DECLARATIONS_POP \
 512     _Pragma(SAL_STRINGIFY_ARG(warning(pop)))
 513 #else
 514 #   define SAL_WNODEPRECATED_DECLARATIONS_PUSH
 515 #   define SAL_WNODEPRECATED_DECLARATIONS_POP
 516 #endif
 517
 518 /**
 519    Use as follows:
 520
 521    SAL_WNOUNREACHABLE_CODE_PUSH
 522
 523    function definition
 524
 525    SAL_WNOUNREACHABLE_CODE_POP
 526
 527    Useful in cases where the compiler is "too clever" like when doing
 528    link-time code generation, and noticing that a called function
 529    always throws, and fixing the problem cleanly so that it produces
 530    no warnings in normal non-LTO compilations either is not easy.
 531
 532 */
 533
 534 #ifdef _MSC_VER
 535 #define SAL_WNOUNREACHABLE_CODE_PUSH \
 536     __pragma(warning(push)) \
 537     __pragma(warning(disable:4702)) \
 538     __pragma(warning(disable:4722))
 539 #define SAL_WNOUNREACHABLE_CODE_POP \
 540     __pragma(warning(pop))
 541 #else
 542 /* Add definitions for GCC and Clang if needed */
 543 #define SAL_WNOUNREACHABLE_CODE_PUSH
 544 #define SAL_WNOUNREACHABLE_CODE_POP
 545 #endif
 546
 547 /** Annotate unused but required C++ function parameters.
 548
 549     An unused parameter is required if the function needs to adhere to a given
 550     type (e.g., if its address is assigned to a function pointer of a specific
 551     type, or if it is called from template code).  This annotation helps static
 552     analysis tools suppress false warnings.  In the case of virtual functions
 553     (where unused required parameters are common, too), the annotation is not
 554     required (as static analysis tools can themselves derive the information
 555     whether a function is virtual).
 556
 557     Use the annotation in function definitions like
 558
 559       void f(SAL_UNUSED_PARAMETER int) {}
 560
 561     C does not allow unnamed parameters, anyway, so a function definition like
 562     the above needs to be written there as
 563
 564       void f(int dummy) { (void) dummy; / * avoid warnings * / }
 565
 566     without a SAL_UNUSED_PARAMETER annotation.
 567
 568     @since LibreOffice 3.6
 569  */
 570 #if defined __cplusplus
 571 #if defined __GNUC__ || defined __clang__
 572 #define SAL_UNUSED_PARAMETER __attribute__ ((unused))
 573 #else
 574 #define SAL_UNUSED_PARAMETER
 575 #endif
 576 #endif
 577
 578 /**
 579
 580  Annotate classes where a compiler should warn if an instance is unused.
 581
 582  The compiler cannot warn about unused instances if they have non-trivial
 583  or external constructors or destructors. Classes marked with SAL_WARN_UNUSED
 584  will be warned about.
 585
 586  @since LibreOffice 4.0
 587
 588 */
 589
 590 #if defined LIBO_INTERNAL_ONLY && (defined __GNUC__ || defined __clang__)
 591 #define SAL_WARN_UNUSED __attribute__((warn_unused))
 592 #else
 593 #define SAL_WARN_UNUSED
 594 #endif
 595
 596 /// @cond INTERNAL
 597
 598 #if defined __GNUC__ || defined __clang__
 599 // Macro to try to catch and warn on assignments inside expr.
 600 #    define SAL_DETAIL_BOOLEAN_EXPR(expr)   \
 601         __extension__ ({                    \
 602             int sal_boolean_var_;           \
 603             if (expr)                       \
 604                sal_boolean_var_ = 1;        \
 605             else                            \
 606                sal_boolean_var_ = 0;        \
 607             sal_boolean_var_;               \
 608         })
 609
 610 /** An optimization annotation: denotes that expression is likely to be true.
 611
 612     Use it to annotate paths that we think are likely eg.
 613     if (SAL_LIKELY(ptr != nullptr))
 614        // this path is the one that is ~always taken.
 615
 616     @since LibreOffice 5.2
 617
 618     Returns: the boolean value of expr (expressed as either int 1 or 0)
 619  */
 620 #    define SAL_LIKELY(expr) __builtin_expect(SAL_DETAIL_BOOLEAN_EXPR((expr)), 1)
 621
 622 /** An optimization annotation: denotes that expression is unlikely to be true.
 623
 624     Use it to annotate paths that we think are likely eg.
 625     if (SAL_UNLIKELY(ptr != nullptr))
 626        // this path is the one that is ~never taken.
 627
 628     @since LibreOffice 5.2
 629
 630     Returns: the boolean value of expr (expressed as either int 1 or 0)
 631  */
 632 #    define SAL_UNLIKELY(expr) __builtin_expect(SAL_DETAIL_BOOLEAN_EXPR((expr)), 0)
 633
 634 /** An optimization annotation: tells the compiler to work harder at this code
 635
 636     If the SAL_HOT annotation is present on a function or a label then
 637     subsequent code statements may have more aggressive compiler
 638     optimization and in-lining work performed on them.
 639
 640     In addition this code can end up in a special section, to be
 641     grouped with other frequently used code.
 642
 643     @since LibreOffice 5.2
 644  */
 645 #    define SAL_HOT __attribute__((hot))
 646
 647 /** An optimization annotation: tells the compiler to work less on this code
 648
 649     If the SAL_COLD annotation is present on a function or a label then
 650     subsequent code statements are unlikely to be performed except in
 651     exceptional circumstances, and optimizing for code-size rather
 652     than performance is preferable.
 653
 654     In addition this code can end up in a special section, to be grouped
 655     with (and away from) other more frequently used code, to improve
 656     locality of reference.
 657
 658     @since LibreOffice 5.2
 659  */
 660 #    define SAL_COLD __attribute__((cold))
 661 #else
 662 #    define SAL_LIKELY(expr) (expr)
 663 #    define SAL_UNLIKELY(expr) (expr)
 664 #    define SAL_HOT
 665 #    define SAL_COLD
 666 #endif
 667
 668 /// @endcond
 669
 670 /// @cond INTERNAL
 671 /** Annotate pointer-returning functions to indicate that such a pointer
 672     is never nullptr.
 673
 674     Note that MSVC supports this feature via it's SAL _Ret_notnull_
 675     annotation, but since it's in a completely different place on
 676     the function declaration, it's a little hard to support both.
 677
 678     @since LibreOffice 5.5
 679 */
 680 #ifndef __has_attribute
 681 #define __has_attribute(x) 0
 682 #endif
 683
 684 #if defined LIBO_INTERNAL_ONLY && ((defined __GNUC__ && !defined __clang__) || (defined __clang__ && __has_attribute(returns_nonnull)))
 685 #define SAL_RETURNS_NONNULL  __attribute__((returns_nonnull))
 686 #else
 687 #define SAL_RETURNS_NONNULL
 688 #endif
 689 /// @endcond
 690
 691 #if defined LIBO_INTERNAL_ONLY
 692 // An annotation mechanism used by some loplugins.  The id argument must be an ordinary string
 693 // literal.  For Clang, this expands to a clang::annotate attribute with an annotation consisting of
 694 // the concatenation of a "loplugin:" prefix and the given id suffix.  For non-Clang, this expands
 695 // to nothing to avoid e.g. -Wattributes from GCC's -Wall.
 696 #if defined __clang__
 697 #define SAL_LOPLUGIN_ANNOTATE(id) [[clang::annotate("loplugin:" id)]]
 698 #else
 699 #define SAL_LOPLUGIN_ANNOTATE(id)
 700 #endif
 701 #endif
 702
 703 #endif // INCLUDED_SAL_TYPES_H
 704
 705 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */