"Fossies" - the Fresh Open Source Software Archive 
"Fossies" - the Fresh Open Source Software Archive A hint: This file contains one or more very long lines, so maybe it is better readable using the pure text view mode that shows the contents as wrapped lines within the browser window.
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2 <html> 3 <head> 4 <title>SWIG and C++11</title> 5 <link rel="stylesheet" type="text/css" href="style.css"> 6 <meta http-equiv="content-type" content="text/html; charset=UTF-8"> 7 </head> 8 9 <body bgcolor="#ffffff"> 10 <H1><a name="CPlusPlus11">7 SWIG and C++11</a></H1> 11 <!-- INDEX --> 12 <div class="sectiontoc"> 13 <ul> 14 <li><a href="#CPlusPlus11_introduction">Introduction</a> 15 <li><a href="#CPlusPlus11_core_language_changes">Core language changes</a> 16 <ul> 17 <li><a href="#CPlusPlus11_rvalue_reference_and_move_semantics">Rvalue reference and move semantics</a> 18 <ul> 19 <li><a href="#CPlusPlus11_rvalue_reference_inputs">Rvalue reference inputs</a> 20 <li><a href="#CPlusPlus11_rvalue_reference_outputs">Rvalue reference outputs</a> 21 <li><a href="#CPlusPlus11_move_only">Movable and move-only types by value</a> 22 </ul> 23 <li><a href="#CPlusPlus11_generalized_constant_expressions">Generalized constant expressions</a> 24 <li><a href="#CPlusPlus11_extern_template">Extern template</a> 25 <li><a href="#CPlusPlus11_initializer_lists">Initializer lists</a> 26 <li><a href="#CPlusPlus11_uniform_initialization">Uniform initialization</a> 27 <li><a href="#CPlusPlus11_type_inference">Type inference</a> 28 <li><a href="#CPlusPlus11_range_based_for_loop">Range-based for-loop</a> 29 <li><a href="#CPlusPlus11_lambda_functions_and_expressions">Lambda functions and expressions</a> 30 <li><a href="#CPlusPlus11_alternate_function_syntax">Alternate function syntax</a> 31 <li><a href="#CPlusPlus11_object_construction_improvement">Object construction improvement</a> 32 <li><a href="#CPlusPlus11_explicit_overrides_final">Explicit overrides and final</a> 33 <li><a href="#CPlusPlus11_null_pointer_constant">Null pointer constant</a> 34 <li><a href="#CPlusPlus11_strongly_typed_enumerations">Strongly typed enumerations</a> 35 <li><a href="#CPlusPlus11_double_angle_brackets">Double angle brackets</a> 36 <li><a href="#CPlusPlus11_explicit_conversion_operators">Explicit conversion operators</a> 37 <li><a href="#CPlusPlus11_alias_templates">Type alias and alias templates</a> 38 <li><a href="#CPlusPlus11_unrestricted_unions">Unrestricted unions</a> 39 <li><a href="#CPlusPlus11_variadic_templates">Variadic templates</a> 40 <li><a href="#CPlusPlus11_new_char_literals">New character literals</a> 41 <li><a href="#CPlusPlus11_new_string_literals">New string literals</a> 42 <li><a href="#CPlusPlus11_user_defined_literals">User-defined literals</a> 43 <li><a href="#CPlusPlus11_thread_local_storage">Thread-local storage</a> 44 <li><a href="#CPlusPlus11_defaulted_deleted">Explicitly defaulted functions and deleted functions</a> 45 <li><a href="#CPlusPlus11_type_long_long_int">Type long long int</a> 46 <li><a href="#CPlusPlus11_static_assertions">Static assertions</a> 47 <li><a href="#CPlusPlus11_sizeof">Allow sizeof to work on members of classes without an explicit object</a> 48 <li><a href="#CPlusPlus11_noexcept">Exception specifications and noexcept</a> 49 <li><a href="#CPlusPlus11_alignment">Control and query object alignment</a> 50 <li><a href="#CPlusPlus11_attributes">Attributes</a> 51 <li><a href="#CPlusPlus11_ref_qualifiers">Methods with ref-qualifiers</a> 52 </ul> 53 <li><a href="#CPlusPlus11_standard_library_changes">Standard library changes</a> 54 <ul> 55 <li><a href="#CPlusPlus11_threading_facilities">Threading facilities</a> 56 <li><a href="#CPlusPlus11_tuple_types">Tuple types</a> 57 <li><a href="#CPlusPlus11_hash_tables">Hash tables</a> 58 <li><a href="#CPlusPlus11_regular_expressions">Regular expressions</a> 59 <li><a href="#CPlusPlus11_general_purpose_smart_pointers">General-purpose smart pointers</a> 60 <li><a href="#CPlusPlus11_extensible_random_number_facility">Extensible random number facility</a> 61 <li><a href="#CPlusPlus11_wrapper_reference">Wrapper reference</a> 62 <li><a href="#CPlusPlus11_polymorphous_wrappers_for_function_objects">Polymorphic wrappers for function objects</a> 63 <li><a href="#CPlusPlus11_type_traits_for_metaprogramming">Type traits for metaprogramming</a> 64 <li><a href="#CPlusPlus11_uniform_method_for_computing_return_type_of_function_objects">Uniform method for computing return type of function objects</a> 65 </ul> 66 </ul> 67 </div> 68 <!-- INDEX --> 69 70 71 72 <H2><a name="CPlusPlus11_introduction">7.1 Introduction</a></H2> 73 74 75 <p>This chapter gives you a brief overview about the SWIG 76 implementation of the C++11 standard. This part of SWIG is still a work in 77 progress. 78 </p> 79 <p>SWIG supports the new C++ syntax changes with some minor limitations 80 in some areas such as decltype expressions and variadic templates. Wrappers for the 81 new STL types (unordered_ containers, result_of, tuples) are incomplete. 82 The wrappers for the new containers would work much like the C++03 containers and 83 users are welcome to help by adapting the existing container interface files and submitting them 84 as a patch for inclusion in future versions of SWIG. 85 </p> 86 87 <H2><a name="CPlusPlus11_core_language_changes">7.2 Core language changes</a></H2> 88 89 90 <H3><a name="CPlusPlus11_rvalue_reference_and_move_semantics">7.2.1 Rvalue reference and move semantics</a></H3> 91 92 93 <p> 94 SWIG correctly parses the rvalue reference syntax '&&', 95 for example the typical usage of it in the move constructor and move assignment operator below: 96 </p> 97 98 <div class="code"><pre> 99 class MyClass { 100 ... 101 std::vector<int> numbers; 102 public: 103 MyClass() : numbers() {} 104 MyClass(MyClass &&other) : numbers(std::move(other.numbers)) {} 105 MyClass & operator=(MyClass &&other) { 106 numbers = std::move(other.numbers); 107 return *this; 108 } 109 }; 110 </pre></div> 111 112 <p> 113 Rvalue references are designed for C++ temporaries and are not particularly useful when used from non-C++ target languages. 114 One option is to just ignore them via <tt>%ignore</tt>. 115 For example, ignore the move constructor: 116 </p> 117 118 <div class="code"><pre> 119 %ignore MyClass::MyClass(MyClass &&); 120 </pre></div> 121 122 <H4><a name="CPlusPlus11_rvalue_reference_inputs">7.2.1.1 Rvalue reference inputs</a></H4> 123 124 125 <p> 126 Rvalue reference parameters are useful as input parameters in C++ for implementing move semantics, such as, 127 in the move constructor and move assignment operator. 128 This type of usage can be useful from target languages too to avoid copying large objects. 129 </p> 130 131 <p> 132 If you do wrap a function/contructor with an rvalue reference parameter and pass a proxy class to it, SWIG will assume that after the call, the rvalue reference parameter object will have been 'moved'. 133 The proxy class passed as the rvalue reference, will own the underlying C++ object up until it is used as an rvalue reference parameter. 134 Afterwards, the proxy class will have the underlying C++ pointer set to the nullptr so that the proxy class instance cannot be used again and the underlying (moved from) C++ object will be deleted after the function/constructor call has returned. 135 </p> 136 137 <p> 138 In this way, the SWIG proxy class works much like an exclusively owned smart pointer (think of <tt>std::unique_ptr</tt>), passing ownership to the called C++ function/constructor. 139 Let's consider an example in Java using the wrapped proxy class from above: 140 </p> 141 142 <div class="targetlang"><pre> 143 MyClass mc = new MyClass(); 144 MyClass mc1 = new MyClass(mc); // move constructor 145 MyClass mc2 = new MyClass(mc); // move constructor fails 146 </pre></div> 147 148 <p> 149 The second call to the move constructor will fail as the <tt>mc</tt> proxy instance has been moved. 150 Each target language handles the moved proxy class slightly differently when attempting to move it again, but typically you'll get an exception such as in Java: 151 </p> 152 153 <div class="shell"> 154 <pre> 155 Exception in thread "main" java.lang.RuntimeException: Cannot release ownership as memory is not owned 156 at MyClass.swigRelease(MyClass.java:27) 157 at MyClass.<init>(MyClass.java:55) 158 at runme.main(runme.java:18) 159 </pre> 160 </div> 161 162 163 <p> 164 Note that both normal copy assignment operators as well as move assignment operators are ignored by default in the target languages with the following warning: 165 </p> 166 167 <div class="shell"> 168 <pre> 169 example.i:18: Warning 503: Can't wrap 'operator =' unless renamed to a valid identifier. 170 </pre> 171 </div> 172 173 <p> 174 Using a <tt>%rename</tt> will remove the warning and also makes the move assignment operator available from the target language: 175 </p> 176 <div class="code"><pre> 177 %rename(MoveAssign) MyClass::operator=(MyClass &&); 178 </pre></div> 179 180 <p> 181 You can then use it, but like the move constructor example above, you cannot use 182 a proxy class once it has already been moved: 183 </p> 184 185 <div class="targetlang"><pre> 186 MyClass mc = new MyClass(); 187 MyClass mc2 = mc.MoveAssign(mc); 188 MyClass mc3 = mc.MoveAssign(mc); // Use of mc again will fail 189 </pre></div> 190 191 <p> 192 It is of course perfectly possible in C++ for a function/constructor to not move an object passed to it in an rvalue reference parameter. The assumption that SWIG makes would then not hold and customisation of the appropriate input typemaps would be required. 193 For scripting languages, this would be for the 'in' typemap and for the non-scripting languages additional typemaps such as the 'javain' typemap, which is used to set the memory ownership of the underlying C++ object for Java, would also need copying and modifying appropriately. 194 </p> 195 196 <p> 197 <b>Compatibility note:</b> 198 SWIG-4.1.0 changed the way that rvalue reference parameters were handled and implemented typemaps assuming that the 199 proxy class owns the underlying C++ object and transfers ownership of the object when a function/constructor with an rvalue reference parameter is called. 200 </p> 201 202 <H4><a name="CPlusPlus11_rvalue_reference_outputs">7.2.1.2 Rvalue reference outputs</a></H4> 203 204 205 <p> 206 While rvalue reference parameter inputs are not uncommon in C++ and can be usefully utilised from target languages, this cannot be said for rvalue reference outputs. 207 Firstly, it is quite unusual in C++ to have functions that return an rvalue reference. 208 Secondly, these cases are nigh on impossible to use from a target language. 209 The main problem is these references are for C++ compiler temporaries used on the stack and the target languages use objects on the heap 210 and the concept of compiler temporary objects doesn't make sense from another language. 211 </p> 212 213 <p> 214 Using <tt>MyClass</tt> from earlier and this C++ code: 215 </p> 216 217 <div class="code"><pre> 218 void use(MyClass &&mc); 219 MyClass && get1(); 220 MyClass & get2(); 221 </pre></div> 222 223 <p> 224 SWIG wraps the <tt>get1</tt> and <tt>get2</tt> functions more or less identically. 225 The returned references are converted into pointers that are not owned by the target language. 226 It means that the following perfectly valid C++ has no equivalent in any of the target languages: 227 </p> 228 229 <div class="code"><pre> 230 use(get1()); 231 use(std::move(get2())); 232 </pre></div> 233 234 <p> 235 An attempt to call the equivalent <tt>use(get1())</tt> from one of the target languages will result in the ownership failure mentioned in the previous section as the object being passed to the <tt>use</tt> function is not owned by the proxy class. 236 In order to own the object, it would need to be cloned for the object to move from the stack to the heap, for which an appropriate clone function would be required, but may not even be available. 237 Note that a move constructor or copy constructor may slice the object when inheritance is involved. 238 Alternatively, customising the input rvalue reference typemap, as mentioned in the previous section, could remove the ownership requirement. 239 Another alternative would be to modify the output rvalue reference typemap to always clone the rvalue reference object. 240 Fortunately you're highly unlikely to have to solve any of these issues! 241 </p> 242 243 <H4><a name="CPlusPlus11_move_only">7.2.1.3 Movable and move-only types by value</a></H4> 244 245 246 <p> 247 SWIG has traditionally relied on wrapped C++ types to be copy constructible or copy assignable, either via an explicit or implicit copy constructor and copy assignment operator. 248 Prior to C++11, a function could not return nor take a type by value that was not copyable. 249 In C++11 this is no longer the case. A type can also be movable if it has has a move constructor and a move assignment operator. 250 A move-only type is movable but not copyable; it has both the copy constructor and copy assignment operator deleted. 251 Movable types can appear in function signatures for passing 'by value' and in C++11 the object can then be moved rather than copied. 252 </p> 253 254 <p> 255 SWIG has support for both copyable and/or movable types. 256 Support for move semantics is quite seamless when returning by value from a function. 257 Support for move semantics is less so and may require some customisation when passing by value to a function. 258 First let's consider returning by value from a function. 259 </p> 260 261 <p> 262 The support for function return values is generically implemented in the "out" <tt>SWIGTYPE</tt> typemap which supports any type, including copyable, movable and move-only types. 263 The typemap code is very simple and written so that the compiler will call the move constructor if possible, 264 otherwise the copy constructor: 265 </p> 266 267 <div class="code"><pre> 268 %typemap(out) SWIGTYPE %{ 269 $result = new $1_ltype($1); 270 %} 271 </pre></div> 272 273 <p> 274 The above typemap is for C# and when used to wrap a move-only type such as: 275 </p> 276 277 <div class="code"><pre> 278 struct MoveOnly { 279 int val; 280 MoveOnly(): val(0) {} 281 282 MoveOnly(const MoveOnly &) = delete; 283 MoveOnly(MoveOnly &&) = default; 284 285 MoveOnly & operator=(const MoveOnly &) = delete; 286 MoveOnly & operator=(MoveOnly &&) = default; 287 288 static MoveOnly create() { return MoveOnly(); } 289 static void take(MoveOnly mo); 290 }; 291 </pre></div> 292 293 <p> 294 will generate wrapper code for the <tt>create</tt> factory method: 295 </p> 296 297 <div class="code"><pre> 298 SWIGEXPORT void * SWIGSTDCALL CSharp_MoveOnly_create() { 299 void * jresult ; 300 SwigValueWrapper< MoveOnly > result; 301 302 result = MoveOnly::create(); 303 jresult = new MoveOnly(result); 304 return jresult; 305 } 306 </pre></div> 307 308 <p> 309 <tt>SwigValueWrapper</tt> is covered in <a href="SWIGPlus.html#SWIGPlus_nn19">Pass and return by value</a>. 310 Note that the generated code could be optimised further using the <a href="Typemaps.html#Typemaps_optimal">"optimal" attribute</a> 311 in the "out" typemap, so if the above typemap is customised as follows (note that this is C# specific): 312 </p> 313 314 <div class="code"><pre> 315 %typemap(out, optimal="1") MoveOnly %{ 316 $result = new $1_ltype($1); 317 %} 318 </pre></div> 319 320 <p> 321 then the generated code will result in the object being optimally moved: 322 </p> 323 324 <div class="code"><pre> 325 SWIGEXPORT void * SWIGSTDCALL CSharp_MoveOnly_create() { 326 void * jresult ; 327 jresult = new MoveOnly(MoveOnly::create()); 328 return jresult; 329 } 330 </pre></div> 331 332 <p> 333 Now let's consider passing by value. 334 We'll consider three cases; namely types that are: 335 </p> 336 337 <ol> 338 <li> Copyable and not movable - <tt>CopyOnly</tt>.</li> 339 <li> Copyable and movable - <tt>MovableCopyable</tt>.</li> 340 <li> Movable and not copyable - <tt>MoveOnly</tt>.</li> 341 </ol> 342 343 <p> 344 and for clarification, define these two additional types as follows: 345 </p> 346 347 <div class="code"><pre> 348 struct CopyOnly { 349 int val; 350 CopyOnly(): val(0) {} 351 352 CopyOnly(const CopyOnly &) = default; 353 CopyOnly & operator=(const CopyOnly &) = default; 354 355 static CopyOnly create() { return CopyOnly(); } 356 static void take(CopyOnly co); 357 }; 358 359 struct MovableCopyable { 360 int val; 361 MovableCopyable(): val(0) {} 362 363 MovableCopyable(const MovableCopyable &) = default; 364 MovableCopyable(MovableCopyable &&) = default; 365 MovableCopyable & operator=(const MovableCopyable &) = default; 366 MovableCopyable & operator=(MovableCopyable &&) = default; 367 368 static MovableCopyable create() { return MovableCopyable(); } 369 static void take(MovableCopyable mc); 370 }; 371 </pre></div> 372 373 <p> 374 The generated code is shown below for <tt>CopyOnly::take</tt> (with additional comments for when constructors and assignment operators are called). 375 While the code shown is C# specific, the generated constructor and/or assignment operator calls are ultimately the same for all target languages. 376 </p> 377 378 <div class="code"><pre> 379 SWIGEXPORT void SWIGSTDCALL CSharp_CopyOnly_take(void * jarg1) { 380 CopyOnly arg1 ; // (a) Default constructor 381 CopyOnly *argp1 ; 382 383 argp1 = (CopyOnly *)jarg1; 384 if (!argp1) { 385 SWIG_CSharpSetPendingExceptionArgument(SWIG_CSharpArgumentNullException, "Attempt to dereference null CopyOnly", 0); 386 return ; 387 } 388 arg1 = *argp1; // (b) Copy assignment 389 CopyOnly::take(SWIG_STD_MOVE(arg1)); // (c) Copy constructor 390 } 391 </pre></div> 392 393 <p> 394 Note that <tt>SWIG_STD_MOVE</tt> is a macro defined as shown below to use <tt>std::move</tt> which is only available from C++11 onwards: 395 </p> 396 397 <div class="code"><pre> 398 #if __cplusplus >=201103L 399 # define SWIG_STD_MOVE(OBJ) std::move(OBJ) 400 #else 401 # define SWIG_STD_MOVE(OBJ) OBJ 402 #endif 403 </pre></div> 404 405 <p> 406 Also note: <i>(c) Copy constructor</i>. 407 Yes, when passing by value the copy constructor is called for all versions of C++, even C++11 and later even though std::move is specified. 408 It's a C++ language feature for types that don't have move semantics! 409 </p> 410 411 <p> 412 The generated code for <tt>MovableCopyable::take</tt> is the same as for <tt>CopyOnly::take</tt>, however, the C++ compiler will choose the move constructor this time where commented <i>(c) Move constructor</i>: 413 </p> 414 415 <div class="code"><pre> 416 SWIGEXPORT void SWIGSTDCALL CSharp_MovableCopyable_take(void * jarg1) { 417 MovableCopyable arg1 ; // (a) Default constructor 418 MovableCopyable *argp1 ; 419 420 argp1 = (MovableCopyable *)jarg1; 421 if (!argp1) { 422 SWIG_CSharpSetPendingExceptionArgument(SWIG_CSharpArgumentNullException, "Attempt to dereference null MovableCopyable", 0); 423 return ; 424 } 425 arg1 = *argp1; // (b) Copy assignment 426 MovableCopyable::take(SWIG_STD_MOVE(arg1)); // (c) Move constructor 427 } 428 </pre></div> 429 430 <p> 431 There are two optimisation opportunities available. 432 </p> 433 <ol> 434 <li> Remove the default constructor call with the <tt>%feature("valuewrapper")</tt> covered in <a href="SWIGPlus.html#SWIGPlus_nn19">Pass and return by value</a> and replace it with <tt>SwigValueWrapper</tt>. 435 </li> 436 <li> Apply the SWIGTYPE MOVE typemaps which are designed specifically to implement full move semantics when passing parameters by value. 437 They replace the copy assignment with a call to <tt>SwigValueWrapper::reset</tt>, which works much like <tt>std::unique_ptr::reset</tt>. 438 These typemaps could alternatively have replaced the copy assignment with a move assignment, but this is not maximally optimal. 439 </li> 440 </ol> 441 <p> 442 Simply add the following before the <tt>MovableCopyable::take</tt> method is parsed: 443 </p> 444 445 <div class="code"><pre> 446 %valuewrapper MovableCopyable; 447 %include <swigmove.i> 448 %apply SWIGTYPE MOVE { MovableCopyable } 449 </pre></div> 450 451 <p> 452 will result in this optimal code where just one move constructor is invoked: 453 </p> 454 455 <div class="code"><pre> 456 SWIGEXPORT void SWIGSTDCALL CSharp_MovableCopyable_take(void * jarg1) { 457 SwigValueWrapper< MovableCopyable > arg1 ; // (a) No constructors invoked 458 MovableCopyable *argp1 ; 459 460 argp1 = (MovableCopyable *)jarg1; 461 if (!argp1) { 462 SWIG_CSharpSetPendingExceptionArgument(SWIG_CSharpArgumentNullException, "Attempt to dereference null MovableCopyable", 0); 463 return ; 464 } 465 SwigValueWrapper< MovableCopyable >::reset(arg1, argp1); // (b) No constructor or assignment operator invoked 466 MovableCopyable::take(SWIG_STD_MOVE(arg1)); // (c) Move constructor 467 } 468 </pre></div> 469 470 <p> 471 Note that <tt>SwigValueWrapper</tt> will call the destructor for the pointer passed to it in the <tt>reset</tt> function. 472 This pointer is the underlying C++ object that the proxy class owns. 473 The details aren't shown, but the 'csin' typemap also generates C# code to ensure that the proxy class releases ownership of the object. 474 Please see the 'SWIGTYPE MOVE' typemaps in the swigmove.i file provided for each target language. 475 Therefore full move semantics are implemented; ownership is moved from the proxy class into the C++ layer and the net effect 476 is the same as using an <a href="#CPlusPlus11_rvalue_reference_inputs">rvalue reference parameter</a> discussed earlier. 477 </p> 478 479 <p> 480 Lastly, let's consider the <tt>MoveOnly::take</tt> function defined earlier. 481 By default the generated code fails to compile as <tt>MoveOnly</tt> does not have a copy assignment operator. 482 SWIG is not designed to select a different typemap automatically for move-only types and the user 483 must apply the SWIGTYPE MOVE typemaps to ensure that only move-only semantics are used. 484 However, SWIG is able to automatically use <tt>%feature("valuewrapper")</tt> for move-only 485 types so it is not necessary to explicitly use this feature. 486 So in this move-only case, simply add the following before <tt>MoveOnly::take</tt> is parsed, which results in the same optimal code shown above for <tt>MovableCopyable</tt>: 487 </p> 488 489 <div class="code"><pre> 490 %include <swigmove.i> 491 %apply SWIGTYPE MOVE { MoveOnly } 492 </pre></div> 493 494 <p> 495 <b>Compatibility note:</b> 496 SWIG-4.1.0 introduced support for taking advantage of types with move semantics and making it possible to easily use move only types. 497 </p> 498 499 500 <H3><a name="CPlusPlus11_generalized_constant_expressions">7.2.2 Generalized constant expressions</a></H3> 501 502 503 <p>SWIG parses and identifies the keyword <tt>constexpr</tt>, but cannot fully utilise it. 504 These C++ compile time constants are usable as runtime constants from the target languages. 505 Below shows example usage for assigning a C++ compile time constant from a compile time constant function: 506 </p> 507 508 <div class="code"><pre> 509 constexpr int XXX() { return 10; } 510 constexpr int YYY = XXX() + 100; 511 </pre></div> 512 513 <p> 514 When either of these is used from a target language, a runtime call is made to obtain the underlying constant. 515 </p> 516 517 <H3><a name="CPlusPlus11_extern_template">7.2.3 Extern template</a></H3> 518 519 520 <p>SWIG correctly parses <tt>extern template</tt> explicit instantiation declarations. 521 However, this template instantiation suppression in a translation unit has no relevance outside of the C++ compiler and so is not used by SWIG. 522 SWIG only uses <tt>%template</tt> for instantiating and wrapping templates. 523 Consider the class template below: 524 </p> 525 526 <div class="code"><pre> 527 // Class template 528 template class std::vector<int>; // C++03 template explicit instantiation definition in C++ 529 extern template class std::vector<int>; // C++11 template explicit instantiation declaration (extern template) 530 %template(VectorInt) std::vector<int>; // SWIG template instantiation 531 </pre></div> 532 533 <p> 534 The above result in warnings: 535 </p> 536 537 <div class="shell"> 538 <pre> 539 example.i:2: Warning 320: Explicit template instantiation ignored. 540 example.i:3: Warning 327: Extern template ignored. 541 </pre> 542 </div> 543 544 <p> 545 Similarly for the function template below: 546 </p> 547 548 <div class="code"><pre> 549 // Function template 550 template void Func<int>(); // C++03 template explicit instantiation definition in C++ 551 extern template void Func<int>(); // C++11 template explicit instantiation declaration (extern template) 552 %template(FuncInt) Func<int>; // SWIG template instantiation 553 </pre></div> 554 555 <H3><a name="CPlusPlus11_initializer_lists">7.2.4 Initializer lists</a></H3> 556 557 558 <p> 559 Initializer lists are very much a C++ compiler construct and are not very accessible from wrappers as 560 they are intended for compile time initialization of classes using the special <tt>std::initializer_list</tt> type. 561 SWIG detects usage of initializer lists and will emit a special informative warning each time one is used: 562 </p> 563 564 <div class="shell"> 565 <pre> 566 example.i:33: Warning 476: Initialization using std::initializer_list. 567 </pre> 568 </div> 569 570 <p> 571 Initializer lists usually appear in constructors but can appear in any function or method. 572 They often appear in constructors which are overloaded with alternative approaches to initializing a class, 573 such as the std container's push_back method for adding elements to a container. 574 The recommended approach then is to simply ignore the initializer-list constructor, for example: 575 </p> 576 577 <div class="code"><pre> 578 %ignore Container::Container(std::initializer_list<int>); 579 class Container { 580 public: 581 Container(std::initializer_list<int>); // initializer-list constructor 582 Container(); 583 void push_back(const int &); 584 ... 585 }; 586 </pre></div> 587 588 <p>Alternatively you could modify the class and add another constructor for initialization by some other means, 589 for example by a <tt>std::vector</tt>:</p> 590 591 <div class="code"><pre> 592 %include <std_vector.i> 593 class Container { 594 public: 595 Container(const std::vector<int> &); 596 Container(std::initializer_list<int>); // initializer-list constructor 597 Container(); 598 void push_back(const int &); 599 ... 600 }; 601 </pre></div> 602 603 <p>And then call this constructor from your target language, for example, in Python, the following will call the constructor taking the <tt>std::vector</tt>:</p> 604 605 <div class="targetlang"><pre> 606 >>> c = Container( [1, 2, 3, 4] ) 607 </pre></div> 608 609 <p> 610 If you are unable to modify the class being wrapped, consider ignoring the initializer-list constructor and using 611 %extend to add in an alternative constructor: 612 </p> 613 614 <div class="code"><pre> 615 %include <std_vector.i> 616 %extend Container { 617 Container(const std::vector<int> &elements) { 618 Container *c = new Container(); 619 for (int element : elements) 620 c->push_back(element); 621 return c; 622 } 623 } 624 625 %ignore Container::Container(std::initializer_list<int>); 626 627 class Container { 628 public: 629 Container(std::initializer_list<int>); // initializer-list constructor 630 Container(); 631 void push_back(const int &); 632 ... 633 }; 634 </pre></div> 635 636 <p> 637 The above makes the wrappers look is as if the class had been declared as follows: 638 </p> 639 640 <div class="code"><pre> 641 %include <std_vector.i> 642 class Container { 643 public: 644 Container(const std::vector<int> &); 645 // Container(std::initializer_list<int>); // initializer-list constructor (ignored) 646 Container(); 647 void push_back(const int &); 648 ... 649 }; 650 </pre></div> 651 652 <p> 653 <tt>std::initializer_list</tt> is simply a container that can only be initialized at compile time. 654 As it is just a C++ type, it is possible to write typemaps for a target language container to map onto 655 <tt>std::initializer_list</tt>. However, this can only be done for a fixed number of elements as 656 initializer lists are not designed to be constructed with a variable number of arguments at runtime. 657 The example below is a very simple approach which ignores any parameters passed in and merely initializes 658 with a fixed list of fixed integer values chosen at compile time: 659 </p> 660 661 <div class="code"><pre> 662 %typemap(in) std::initializer_list<int> { 663 $1 = {10, 20, 30, 40, 50}; 664 } 665 class Container { 666 public: 667 Container(std::initializer_list<int>); // initializer-list constructor 668 Container(); 669 void push_back(const int &); 670 ... 671 }; 672 </pre></div> 673 674 <p> 675 Any attempt at passing in values from the target language will be ignored and be replaced by <tt>{10, 20, 30, 40, 50}</tt>. 676 Needless to say, this approach is very limited, but could be improved upon, but only slightly. 677 A typemap could be written to map a fixed number of elements on to the <tt>std::initializer_list</tt>, 678 but with values decided at runtime. 679 The typemaps would be target language specific. 680 </p> 681 682 <p> 683 Note that the default typemap for <tt>std::initializer_list</tt> does nothing but issue the warning 684 and hence any user supplied typemaps will override it and suppress the warning. 685 </p> 686 687 <H3><a name="CPlusPlus11_uniform_initialization">7.2.5 Uniform initialization</a></H3> 688 689 690 <p>The curly brackets {} for member initialization are fully 691 supported by SWIG:</p> 692 693 <div class="code"><pre> 694 struct BasicStruct { 695 int x; 696 double y; 697 }; 698 699 struct AltStruct { 700 AltStruct(int x, double y) : x_{x}, y_{y} {} 701 702 int x_; 703 double y_; 704 }; 705 706 BasicStruct var1{5, 3.2}; // only fills the struct components 707 AltStruct var2{2, 4.3}; // calls the constructor 708 </pre></div> 709 710 <p>Uniform initialization does not affect usage from the target language, for example in Python:</p> 711 712 <div class="targetlang"><pre> 713 >>> a = AltStruct(10, 142.15) 714 >>> a.x_ 715 10 716 >>> a.y_ 717 142.15 718 </pre></div> 719 720 <H3><a name="CPlusPlus11_type_inference">7.2.6 Type inference</a></H3> 721 722 723 <p>SWIG supports <tt>decltype()</tt> with some limitations. Single 724 variables are allowed, however, expressions are not supported yet. For 725 example, the following code will work:</p> 726 <div class="code"><pre> 727 int i; 728 decltype(i) j; 729 </pre></div> 730 731 <p>However, using an expression inside the decltype results in syntax error:</p> 732 <div class="code"><pre> 733 int i; int j; 734 decltype(i+j) k; // syntax error 735 </pre></div> 736 737 <p>SWIG does not support <tt>auto</tt> as a type specifier for variables, only 738 for specifying the return type of <a href="#CPlusPlus11_lambda_functions_and_expressions">lambdas</a> 739 and <a href="#CPlusPlus11_alternate_function_syntax">functions</a>.</p> 740 741 <H3><a name="CPlusPlus11_range_based_for_loop">7.2.7 Range-based for-loop</a></H3> 742 743 744 <p>This feature is part of the implementation block only. SWIG 745 ignores it.</p> 746 747 <H3><a name="CPlusPlus11_lambda_functions_and_expressions">7.2.8 Lambda functions and expressions</a></H3> 748 749 750 <p>SWIG correctly parses most of the Lambda functions syntax. For example:</p> 751 <div class="code"><pre> 752 auto val = [] { return something; }; 753 auto sum = [](int x, int y) { return x+y; }; 754 auto sum = [](int x, int y) -> int { return x+y; }; 755 </pre></div> 756 757 <p>The lambda functions are removed from the wrappers for now, because of the lack of support 758 for closures (scope of the lambda functions) in the target languages.</p> 759 760 <p> 761 Lambda functions used to create variables can also be parsed, but due to limited support of <tt>auto</tt> when 762 the type is deduced from the expression, the variables are simply ignored. 763 </p> 764 765 <div class="code"><pre> 766 auto six = [](int x, int y) { return x+y; }(4, 2); 767 </pre></div> 768 769 <p> 770 Better support should be available in a later release. 771 </p> 772 773 <H3><a name="CPlusPlus11_alternate_function_syntax">7.2.9 Alternate function syntax</a></H3> 774 775 776 <p>SWIG fully supports the new definition of functions. For example:</p> 777 <div class="code"><pre> 778 struct SomeStruct { 779 int FuncName(int x, int y); 780 }; 781 </pre></div> 782 783 <p>can now be written as in C++11:</p> 784 785 <div class="code"><pre> 786 struct SomeStruct { 787 auto FuncName(int x, int y) -> int; 788 }; 789 790 auto SomeStruct::FuncName(int x, int y) -> int { 791 return x + y; 792 } 793 </pre></div> 794 795 <p>The usage in the target languages remains the same, for example in Python:</p> 796 797 <div class="targetlang"><pre> 798 >>> a = SomeStruct() 799 >>> a.FuncName(10, 5) 800 15 801 </pre></div> 802 803 <p>SWIG will also deal with type inference for the return type, as per the limitations described earlier. For example:</p> 804 <div class="code"><pre> 805 auto square(float a, float b) -> decltype(a); 806 </pre></div> 807 808 <H3><a name="CPlusPlus11_object_construction_improvement">7.2.10 Object construction improvement</a></H3> 809 810 811 <p> 812 There are three parts to object construction improvement. 813 The first improvement is constructor delegation such as the following: 814 </p> 815 816 <div class="code"><pre> 817 class A { 818 public: 819 int a; 820 int b; 821 int c; 822 823 A() : A(10) {} 824 A(int aa) : A(aa, 20) {} 825 A(int aa, int bb) : A(aa, bb, 30) {} 826 A(int aa, int bb, int cc) { a=aa; b=bb; c=cc; } 827 }; 828 </pre></div> 829 830 <p> 831 where peer constructors can be called. SWIG handles this without any issue. 832 </p> 833 834 <p> 835 The second improvement is constructor inheritance via a <tt>using</tt> declaration. 836 This is parsed correctly, but the additional constructors are not currently added to the derived proxy class in the target language. 837 An example is shown below: 838 <!-- 839 The extra constructors provided by the <tt>using</tt> syntax will add the appropriate constructors into the target language proxy derived classes. 840 In the example below a wrapper for the <tt>DerivedClass(int)</tt> is added to <tt>DerivedClass</tt>: 841 --> 842 </p> 843 844 <div class="code"><pre> 845 class BaseClass { 846 public: 847 BaseClass(int iValue); 848 }; 849 850 class DerivedClass: public BaseClass { 851 public: 852 using BaseClass::BaseClass; // Adds DerivedClass(int) constructor 853 }; 854 </pre></div> 855 856 <p> 857 The final part is member initialization at the site of the declaration. 858 This kind of initialization is handled by SWIG. 859 </p> 860 861 <div class="code"><pre> 862 class SomeClass { 863 public: 864 SomeClass() {} 865 explicit SomeClass(int new_value) : value(new_value) {} 866 867 int value = 5; 868 }; 869 </pre></div> 870 871 <H3><a name="CPlusPlus11_explicit_overrides_final">7.2.11 Explicit overrides and final</a></H3> 872 873 874 <p> 875 The special identifiers <tt>final</tt> and <tt>override</tt> can be used on methods and destructors, 876 such as in the following example: 877 </p> 878 879 <div class="code"><pre> 880 struct BaseStruct { 881 virtual void ab() const = 0; 882 virtual void cd(); 883 virtual void ef(); 884 virtual ~BaseStruct(); 885 }; 886 struct DerivedStruct : BaseStruct { 887 virtual void ab() const override; 888 virtual void cd() final; 889 virtual void ef() final override; 890 virtual ~DerivedStruct() override; 891 }; 892 </pre></div> 893 894 <p> 895 Classes can also be marked as final, such as 896 </p> 897 898 <div class="code"><pre> 899 struct FinalDerivedStruct final : BaseStruct { 900 virtual void ab() const override; 901 }; 902 </pre></div> 903 904 <p> 905 <b>Compatibility note:</b> Final methods were supported much earlier than final classes. SWIG-4.1.0 was the first version to support classes marked as final. 906 </p> 907 908 <H3><a name="CPlusPlus11_null_pointer_constant">7.2.12 Null pointer constant</a></H3> 909 910 911 <p>The <tt>nullptr</tt> constant is mostly unimportant in wrappers. In the few places it has an effect, it is treated like <tt>NULL</tt>.</p> 912 913 <H3><a name="CPlusPlus11_strongly_typed_enumerations">7.2.13 Strongly typed enumerations</a></H3> 914 915 916 <p>SWIG supports strongly typed enumerations and parses the new <tt>enum class</tt> syntax and forward declarator for the enums, such as:</p> 917 <div class="code"><pre> 918 enum class MyEnum : unsigned int; 919 </pre></div> 920 921 <p> 922 Strongly typed enums are often used to avoid name clashes such as the following: 923 </p> 924 925 <div class="code"><pre> 926 struct Color { 927 enum class RainbowColors : unsigned int { 928 Red, Orange, Yellow, Green, Blue, Indigo, Violet 929 }; 930 931 enum class WarmColors { 932 Yellow, Orange, Red 933 }; 934 935 // Note normal enum 936 enum PrimeColors { 937 Red=100, Green, Blue 938 }; 939 }; 940 </pre></div> 941 942 <p> 943 There are various ways that the target languages handle enums, so it is not possible to precisely state how they are handled in this section. 944 However, generally, most scripting languages mangle in the strongly typed enumeration's class name, 945 but do not use any additional mangling for normal enumerations. For example, in Python, the following code 946 </p> 947 948 <div class="targetlang"><pre> 949 print Color.RainbowColors_Red, Color.WarmColors_Red, Color.Red 950 </pre></div> 951 952 <p> 953 results in 954 </p> 955 956 <div class="shell"><pre> 957 0 2 100 958 </pre></div> 959 960 <p> 961 The strongly typed languages often wrap normal enums into an enum class and so treat normal enums and strongly typed enums the same. 962 The equivalent in Java is: 963 </p> 964 965 <div class="targetlang"><pre> 966 System.out.println(Color.RainbowColors.Red.swigValue() + " " + Color.WarmColors.Red.swigValue() + " " + Color.PrimeColors.Red.swigValue()); 967 </pre></div> 968 969 <H3><a name="CPlusPlus11_double_angle_brackets">7.2.14 Double angle brackets</a></H3> 970 971 972 <p>SWIG correctly parses the symbols >> as closing the 973 template block, if found inside it at the top level, or as the right 974 shift operator >> otherwise.</p> 975 976 <div class="code"><pre> 977 std::vector<std::vector<int>> myIntTable; 978 </pre></div> 979 980 <H3><a name="CPlusPlus11_explicit_conversion_operators">7.2.15 Explicit conversion operators</a></H3> 981 982 983 <p>SWIG correctly parses the keyword <tt>explicit</tt> for operators in addition to constructors now. 984 For example:</p> 985 986 <div class="code"><pre> 987 class U { 988 public: 989 int u; 990 }; 991 992 class V { 993 public: 994 int v; 995 }; 996 997 class TestClass { 998 public: 999 //implicit converting constructor 1000 TestClass(U const &val) { t=val.u; } 1001 1002 // explicit constructor 1003 explicit TestClass(V const &val) { t=val.v; } 1004 1005 int t; 1006 }; 1007 1008 struct Testable { 1009 // explicit conversion operator 1010 explicit operator bool() const { 1011 return false; 1012 } 1013 }; 1014 </pre></div> 1015 1016 <p> 1017 The effect of explicit constructors and operators has little relevance for the proxy classes as target 1018 languages don't have the same concepts of implicit conversions as C++. 1019 Conversion operators either with or without <tt>explicit</tt> need renaming to a valid identifier name in order to make 1020 them available as a normal proxy method. 1021 </p> 1022 1023 <H3><a name="CPlusPlus11_alias_templates">7.2.16 Type alias and alias templates</a></H3> 1024 1025 1026 <p> 1027 A type alias is a statement of the form: 1028 </p> 1029 1030 <div class="code"><pre> 1031 using PFD = void (*)(double); // New introduced syntax 1032 </pre></div> 1033 1034 <p> 1035 which is equivalent to the old style typedef: 1036 </p> 1037 1038 <div class="code"><pre> 1039 typedef void (*PFD)(double); // The old style 1040 </pre></div> 1041 1042 <p> 1043 The following is an example of an alias template: 1044 1045 <div class="code"><pre> 1046 template< typename T1, typename T2, int N > 1047 class SomeType { 1048 public: 1049 T1 a; 1050 T2 b; 1051 }; 1052 1053 template< typename T2 > 1054 using TypedefName = SomeType<char*, T2, 5>; 1055 </pre></div> 1056 1057 <p> 1058 SWIG supports both type aliasing and alias templates. 1059 However, in order to use an alias template, two <tt>%template</tt> directives must be used: 1060 </p> 1061 1062 <div class="code"><pre> 1063 %template(SomeTypeBool) SomeType<char*, bool, 5>; 1064 %template() TypedefName<bool>; 1065 </pre></div> 1066 1067 <p>Firstly, the actual template is instantiated with a name to be used by the target language, as per any template being wrapped. 1068 Secondly, the empty template instantiation, <tt>%template()</tt>, is required for the alias template. 1069 This second requirement is necessary to add the appropriate instantiated template type into the type system as SWIG does not automatically instantiate templates. 1070 See the <a href="SWIGPlus.html#SWIGPlus_nn30">Templates</a> section for more general information on wrapping templates. 1071 1072 <H3><a name="CPlusPlus11_unrestricted_unions">7.2.17 Unrestricted unions</a></H3> 1073 1074 1075 <p>SWIG fully supports any type inside a union even if it does not 1076 define a trivial constructor. For example, the wrapper for the following 1077 code correctly provides access to all members in the union:</p> 1078 1079 <div class="code"><pre> 1080 struct point { 1081 point() {} 1082 point(int x, int y) : x_(x), y_(y) {} 1083 int x_, y_; 1084 }; 1085 1086 #include <new> // For placement 'new' in the constructor below 1087 union P { 1088 int z; 1089 double w; 1090 point p; // Illegal in C++03; legal in C++11. 1091 // Due to the point member, a constructor definition is required. 1092 P() { 1093 new(&p) point(); 1094 } 1095 } p1; 1096 </pre></div> 1097 1098 <H3><a name="CPlusPlus11_variadic_templates">7.2.18 Variadic templates</a></H3> 1099 1100 1101 <p>SWIG supports the variadic templates syntax (inside the <> 1102 block, variadic class inheritance and variadic constructor and 1103 initializers) with some limitations. The following code is correctly parsed:</p> 1104 1105 <div class="code"><pre> 1106 template <typename... BaseClasses> class ClassName : public BaseClasses... { 1107 public: 1108 ClassName (BaseClasses &&... baseClasses) : BaseClasses(baseClasses)... {} 1109 } 1110 </pre></div> 1111 1112 <p> 1113 For now however, the <tt>%template</tt> directive only accepts one parameter substitution 1114 for the variable template parameters. 1115 </p> 1116 1117 <div class="code"><pre> 1118 %template(MyVariant1) ClassName<> // zero argument not supported yet 1119 %template(MyVariant2) ClassName<int> // ok 1120 %template(MyVariant3) ClassName<int, int> // too many arguments not supported yet 1121 </pre></div> 1122 1123 <p>Support for the variadic <tt>sizeof()</tt> function is correctly parsed:</p> 1124 1125 <div class="code"><pre> 1126 const int SIZE = sizeof...(ClassName<int, int>); 1127 </pre></div> 1128 1129 <p> 1130 In the above example <tt>SIZE</tt> is of course wrapped as a constant. 1131 </p> 1132 1133 <H3><a name="CPlusPlus11_new_char_literals">7.2.19 New character literals</a></H3> 1134 1135 1136 <p> 1137 C++11 adds support for UCS-2 and UCS-4 character literals. 1138 These character literals are preceded by either 'u' or 'U'. 1139 </p> 1140 1141 <div class="code"><pre> 1142 char16_t a = u'a'; 1143 char32_t b = U'b'; 1144 </pre></div> 1145 1146 <p> 1147 <b>Compatibility note:</b> SWIG-4.0.0 was the first version to support these Universal Coded Character Set (UCS) character literals. 1148 </p> 1149 1150 <H3><a name="CPlusPlus11_new_string_literals">7.2.20 New string literals</a></H3> 1151 1152 1153 <p>SWIG supports wide string and Unicode string constants and raw string literals.</p> 1154 1155 <div class="code"><pre> 1156 // New string literals 1157 wstring aa = L"Wide string"; 1158 const char *bb = u8"UTF-8 string"; 1159 const char16_t *cc = u"UTF-16 string"; 1160 const char32_t *dd = U"UTF-32 string"; 1161 1162 // Raw string literals 1163 const char *xx = ")I'm an \"ascii\" \\ string."; 1164 const char *ee = R"XXX()I'm an "ascii" \ string.)XXX"; // same as xx 1165 wstring ff = LR"XXX(I'm a "raw wide" \ string.)XXX"; 1166 const char *gg = u8R"XXX(I'm a "raw UTF-8" \ string.)XXX"; 1167 const char16_t *hh = uR"XXX(I'm a "raw UTF-16" \ string.)XXX"; 1168 const char32_t *ii = UR"XXX(I'm a "raw UTF-32" \ string.)XXX"; 1169 </pre></div> 1170 1171 <p> 1172 Non-ASCII string support varies quite a bit among the various target languages though. 1173 </p> 1174 1175 <p> 1176 Note: There is a bug currently where SWIG's preprocessor incorrectly parses an odd number of double quotes 1177 inside raw string literals. 1178 </p> 1179 1180 <H3><a name="CPlusPlus11_user_defined_literals">7.2.21 User-defined literals</a></H3> 1181 1182 1183 <p> 1184 SWIG parses the declaration of user-defined literals, that is, the <tt>operator "" _mysuffix()</tt> function syntax. 1185 </p> 1186 1187 <p> 1188 Some examples are the raw literal: 1189 </p> 1190 <div class="code"><pre> 1191 OutputType operator "" _myRawLiteral(const char * value); 1192 </pre></div> 1193 1194 <p> 1195 numeric cooked literals: 1196 </p> 1197 <div class="code"><pre> 1198 OutputType operator "" _mySuffixIntegral(unsigned long long); 1199 OutputType operator "" _mySuffixFloat(long double); 1200 </pre></div> 1201 1202 <p> 1203 and cooked string literals: 1204 </p> 1205 <div class="code"><pre> 1206 OutputType operator "" _mySuffix(const char * string_values, size_t num_chars); 1207 OutputType operator "" _mySuffix(const wchar_t * string_values, size_t num_chars); 1208 OutputType operator "" _mySuffix(const char16_t * string_values, size_t num_chars); 1209 OutputType operator "" _mySuffix(const char32_t * string_values, size_t num_chars); 1210 </pre></div> 1211 1212 <p> 1213 Like other operators that SWIG parses, a warning is given about renaming the operator in order for it to be wrapped: 1214 </p> 1215 1216 <div class="shell"><pre> 1217 example.i:27: Warning 503: Can't wrap 'operator "" _myRawLiteral' unless renamed to a valid identifier. 1218 </pre></div> 1219 1220 <p> 1221 If %rename is used, then it can be called like any other wrapped method. 1222 Currently you need to specify the full declaration including parameters for %rename: 1223 </p> 1224 1225 <div class="code"><pre> 1226 %rename(MyRawLiteral) operator"" _myRawLiteral(const char * value); 1227 </pre></div> 1228 1229 <p> 1230 Or if you just wish to ignore it altogether: 1231 </p> 1232 1233 <div class="code"><pre> 1234 %ignore operator "" _myRawLiteral(const char * value); 1235 </pre></div> 1236 1237 <p> 1238 Note that use of user-defined literals such as the following still give a syntax error: 1239 </p> 1240 1241 <div class="code"><pre> 1242 OutputType var1 = "1234"_suffix; 1243 OutputType var2 = 1234_suffix; 1244 OutputType var3 = 3.1416_suffix; 1245 </pre></div> 1246 1247 <H3><a name="CPlusPlus11_thread_local_storage">7.2.22 Thread-local storage</a></H3> 1248 1249 1250 <p>SWIG correctly parses the <tt>thread_local</tt> keyword. For example, variables 1251 reachable by the current thread can be defined as:</p> 1252 1253 <div class="code"><pre> 1254 struct A { 1255 static thread_local int val; 1256 }; 1257 thread_local int global_val; 1258 </pre></div> 1259 1260 <p> 1261 The use of the <tt>thread_local</tt> storage specifier does not affect the wrapping process; it does not modify 1262 the wrapper code compared to when it is not specified. 1263 A variable will be thread local if accessed from different threads from the target language in the 1264 same way that it will be thread local if accessed from C++ code. 1265 </p> 1266 1267 <H3><a name="CPlusPlus11_defaulted_deleted">7.2.23 Explicitly defaulted functions and deleted functions</a></H3> 1268 1269 1270 <p>SWIG handles explicitly defaulted functions, that is, <tt>= default</tt> added to a function declaration. Deleted definitions, which are also called deleted functions, have <tt>= delete</tt> added to the function declaration. 1271 For example:</p> 1272 1273 <div class="code"><pre> 1274 struct NonCopyable { 1275 NonCopyable & operator=(const NonCopyable &) = delete; /* Removes operator= */ 1276 NonCopyable(const NonCopyable &) = delete; /* Removes copy constructor */ 1277 NonCopyable() = default; /* Explicitly allows the empty constructor */ 1278 }; 1279 </pre></div> 1280 1281 <p> 1282 Wrappers for deleted functions will not be available in the target language. 1283 Wrappers for defaulted functions will of course be available in the target language. 1284 Explicitly defaulted functions have no direct effect for SWIG wrapping as the declaration is handled 1285 much like any other method declaration parsed by SWIG. 1286 </p> 1287 1288 <p> 1289 Deleted functions are also designed to prevent implicit conversions when calling the function. 1290 For example, the C++ compiler will not compile any code which attempts to use an int as the type of the parameter passed to <tt>f</tt> below: 1291 </p> 1292 1293 <div class="code"><pre> 1294 struct NoInt { 1295 void f(double i); 1296 void f(int) = delete; 1297 }; 1298 </pre></div> 1299 1300 <p> 1301 This is a C++ compile time check and SWIG does not make any attempt to detect if the target language is using an int instead of a double though, 1302 so in this case it is entirely possible to pass an int instead of a double to <tt>f</tt> from Java, Python etc. 1303 </p> 1304 1305 <H3><a name="CPlusPlus11_type_long_long_int">7.2.24 Type long long int</a></H3> 1306 1307 1308 <p>SWIG correctly parses and uses the new <tt>long long</tt> type already introduced in C99 some time ago.</p> 1309 1310 <H3><a name="CPlusPlus11_static_assertions">7.2.25 Static assertions</a></H3> 1311 1312 1313 <p> 1314 SWIG correctly parses the new <tt>static_assert</tt> declarations (though 3.0.12 and earlier 1315 had a bug which meant this wasn't accepted at file scope). 1316 This is a C++ compile time directive so there isn't anything useful that SWIG can do with it. 1317 </p> 1318 1319 <div class="code"><pre> 1320 template <typename T> 1321 struct Check { 1322 static_assert(sizeof(int) <= sizeof(T), "not big enough"); 1323 }; 1324 </pre></div> 1325 1326 <H3><a name="CPlusPlus11_sizeof">7.2.26 Allow sizeof to work on members of classes without an explicit object</a></H3> 1327 1328 1329 <p> 1330 SWIG can parse the new sizeof() on types as well as on objects. For example: 1331 </p> 1332 1333 <div class="code"><pre> 1334 struct A { 1335 int member; 1336 }; 1337 1338 const int SIZE = sizeof(A::member); // does not work with C++03. Okay with C++11 1339 </pre></div> 1340 1341 <p>In Python:</p> 1342 <div class="targetlang"><pre> 1343 >>> SIZE 1344 8 1345 </pre></div> 1346 1347 <H3><a name="CPlusPlus11_noexcept">7.2.27 Exception specifications and noexcept</a></H3> 1348 1349 1350 <p> 1351 C++11 added in the noexcept specification to exception specifications to indicate that a function simply may or may not throw an exception, without actually naming any exception. 1352 SWIG understands these, although there isn't any useful way that this information can be taken advantage of by target languages, 1353 so it is as good as ignored during the wrapping process. 1354 Below are some examples of noexcept in function declarations: 1355 </p> 1356 1357 <div class="code"><pre> 1358 static void noex1() noexcept; 1359 int noex2(int) noexcept(true); 1360 int noex3(int, bool) noexcept(false); 1361 </pre></div> 1362 1363 <H3><a name="CPlusPlus11_alignment">7.2.28 Control and query object alignment</a></H3> 1364 1365 1366 <p> 1367 An <tt>alignof</tt> operator is used mostly within C++ to return alignment in number of bytes, but could be used to initialize a variable as shown below. 1368 The variable's value will be available for access by the target language as any other variable's compile time initialised value. 1369 1370 <div class="code"><pre> 1371 const int align1 = alignof(A::member); 1372 </pre></div> 1373 1374 <p> 1375 The <tt>alignas</tt> specifier for variable alignment is not yet supported. 1376 Example usage: 1377 </p> 1378 1379 <div class="code"><pre> 1380 struct alignas(16) S { 1381 int num; 1382 }; 1383 alignas(double) unsigned char c[sizeof(double)]; 1384 </pre></div> 1385 1386 <p> 1387 Use the preprocessor to work around this for now: 1388 </p> 1389 1390 <div class="code"><pre> 1391 #define alignas(T) 1392 </pre></div> 1393 1394 1395 <H3><a name="CPlusPlus11_attributes">7.2.29 Attributes</a></H3> 1396 1397 1398 <p> 1399 Attributes such as those shown below, are supported since SWIG 4.1.0 but are 1400 currently crudely ignored by the parser's tokeniser so they have no effect on 1401 SWIG's code generation. 1402 </p> 1403 1404 <div class="code"><pre> 1405 int [[attr1]] i [[attr2, attr3]]; 1406 1407 [[noreturn, nothrow]] void f [[noreturn]] (); 1408 </pre></div> 1409 1410 1411 <H3><a name="CPlusPlus11_ref_qualifiers">7.2.30 Methods with ref-qualifiers</a></H3> 1412 1413 1414 <p> 1415 C++11 non-static member functions can be declared with ref-qualifiers. 1416 Member functions declared with a <tt>&</tt> lvalue ref-qualifiers are wrapped like any other function without ref-qualifiers. 1417 Member functions declared with a <tt>&&</tt> rvalue ref-qualifiers are ignored by default 1418 as they are unlikely to be required from non-C++ languages where the concept of <i>rvalue-ness</i> 1419 for the implied *this pointer does not apply. 1420 The warning is hidden by default, but can be displayed as described in the section on <a href="Warnings.html#Warnings_nn4">Enabling extra warnings</a>. 1421 </p> 1422 1423 <p> 1424 Consider: 1425 </p> 1426 1427 <div class="code"><pre> 1428 struct RQ { 1429 void m1(int x) &; 1430 void m2(int x) &&; 1431 }; 1432 </pre></div> 1433 1434 <p> 1435 The only wrapped method will be the lvalue ref-qualified method <tt>m1</tt> 1436 and if SWIG is run with the <tt>-Wextra</tt> command-line option, the following warning will be issued indicating <tt>m2</tt> is not wrapped: 1437 </p> 1438 1439 <div class="shell"> 1440 <pre> 1441 example.i:7: Warning 405: Method with rvalue ref-qualifier m2(int) && ignored. 1442 </pre> 1443 </div> 1444 1445 <p> 1446 If you unignore the method as follows, wrappers for <tt>m2</tt> will be generated: 1447 </p> 1448 1449 <div class="code"><pre> 1450 %feature("ignore", "0") RQ::m2(int x) &&; 1451 struct RQ { 1452 void m1(int x) &; 1453 void m2(int x) &&; 1454 }; 1455 </pre></div> 1456 1457 <p> 1458 Inspection of the generated C++ code, will show that <tt>std::move</tt> is used on the instance 1459 of the <tt>RQ *</tt> class: 1460 </p> 1461 1462 <div class="code"><pre> 1463 RQ *arg1 = (RQ *) 0 ; 1464 int arg2 ; 1465 1466 arg1 = ...marshalled from target language... 1467 arg2 = ...marshalled from target language... 1468 1469 std::move(*arg1).m2(arg2); 1470 </pre></div> 1471 1472 <p> 1473 This will compile but when run, the move effects may not be what you want. 1474 As stated earlier, rvalue ref-qualifiers aren't really applicable outside the world of C++. 1475 However, if you really know what you are doing, full control over the call to the method is 1476 possible via the low-level "action" feature. 1477 This feature completely replaces the call to the underlying function, that is, the last line in the snippet of code above. 1478 </p> 1479 1480 <div class="code"><pre> 1481 %feature("ignore", "0") RQ::m2(int x) &&; 1482 %feature("action") RQ::m2(int x) && %{ 1483 RQ().m2(arg2); 1484 %} 1485 struct RQ { 1486 void m1(int x) &; 1487 void m2(int x) &&; 1488 }; 1489 </pre></div> 1490 1491 <p> 1492 resulting in: 1493 </p> 1494 1495 <div class="code"><pre> 1496 RQ *arg1 = (RQ *) 0 ; 1497 int arg2 ; 1498 1499 arg1 = ...marshalled from target language... 1500 arg2 = ...marshalled from target language... 1501 1502 RQ().m2(arg2); 1503 </pre></div> 1504 1505 <p> 1506 <b>Compatibility note:</b> SWIG-4.0.0 was the first version to support ref-qualifiers. 1507 </p> 1508 <H2><a name="CPlusPlus11_standard_library_changes">7.3 Standard library changes</a></H2> 1509 1510 1511 <H3><a name="CPlusPlus11_threading_facilities">7.3.1 Threading facilities</a></H3> 1512 1513 1514 <p>SWIG does not currently wrap or use any of the new threading 1515 classes introduced (thread, mutex, locks, condition variables, task). The main reason is that 1516 SWIG target languages offer their own threading facilities so there is limited use for them. 1517 </p> 1518 1519 <H3><a name="CPlusPlus11_tuple_types">7.3.2 Tuple types</a></H3> 1520 1521 1522 <p> 1523 SWIG does not provide library files for the new tuple types yet. 1524 Variadic template support requires further work to provide substantial tuple wrappers. 1525 </p> 1526 1527 <H3><a name="CPlusPlus11_hash_tables">7.3.3 Hash tables</a></H3> 1528 1529 1530 <p> 1531 The new hash tables in the STL are <tt>unordered_set</tt>, <tt>unordered_multiset</tt>, <tt>unordered_map</tt>, <tt>unordered_multimap</tt>. 1532 These are not available in all target languages. 1533 Any missing support can in principle be easily implemented by adapting the current STL containers. 1534 </p> 1535 1536 <H3><a name="CPlusPlus11_regular_expressions">7.3.4 Regular expressions</a></H3> 1537 1538 1539 <p> 1540 While SWIG could provide wrappers for the new C++11 regular expressions classes, there is little need as the target languages have their own regular expression facilities. 1541 </p> 1542 1543 <H3><a name="CPlusPlus11_general_purpose_smart_pointers">7.3.5 General-purpose smart pointers</a></H3> 1544 1545 1546 <p> 1547 SWIG provides special smart pointer handling for <tt>std::shared_ptr</tt> in the same way it has support for <tt>boost::shared_ptr</tt>. 1548 Please see the <a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a> 1549 and <a href="Library.html#Library_std_unique_ptr">unique_ptr smart pointer</a> library sections. 1550 There is no special smart pointer handling available for <tt>std::weak_ptr</tt>. 1551 1552 </p> 1553 1554 <H3><a name="CPlusPlus11_extensible_random_number_facility">7.3.6 Extensible random number facility</a></H3> 1555 1556 1557 <p>This feature extends and standardizes the standard library only and does not effect the C++ language nor SWIG.</p> 1558 1559 <H3><a name="CPlusPlus11_wrapper_reference">7.3.7 Wrapper reference</a></H3> 1560 1561 1562 <p> 1563 Wrapper references are similar to normal C++ references but are copy-constructible and copy-assignable. 1564 They could conceivably be used in public APIs. 1565 There is no special support for <tt>std::reference_wrapper</tt> in SWIG though. 1566 Users would need to write their own typemaps if wrapper references are being used and these would be similar to the plain C++ reference typemaps. 1567 </p> 1568 1569 1570 <H3><a name="CPlusPlus11_polymorphous_wrappers_for_function_objects">7.3.8 Polymorphic wrappers for function objects</a></H3> 1571 1572 1573 <p> 1574 SWIG supports functor classes in a few languages in a very natural way. 1575 However nothing is provided yet for the new <tt>std::function</tt> template. 1576 SWIG will parse usage of the template like any other template. 1577 </p> 1578 1579 <div class="code"><pre> 1580 %rename(__call__) Test::operator(); // Default renaming used for Python 1581 1582 struct Test { 1583 bool operator()(int x, int y); // function object 1584 }; 1585 1586 #include <functional> 1587 std::function<void (int, int)> pF = Test; // function template wrapper 1588 1589 </pre></div> 1590 1591 <p> 1592 Example of supported usage of the plain functor from Python is shown below. 1593 It does not involve <tt>std::function</tt>. 1594 </p> 1595 1596 <div class="targetlang"><pre> 1597 t = Test() 1598 b = t(1, 2) # invoke C++ function object 1599 </pre></div> 1600 1601 <H3><a name="CPlusPlus11_type_traits_for_metaprogramming">7.3.9 Type traits for metaprogramming</a></H3> 1602 1603 1604 <p>The type_traits functions to support C++ metaprogramming is useful at compile time and is aimed specifically at C++ development:</p> 1605 1606 <div class="code"><pre> 1607 #include <type_traits> 1608 1609 // First way of operating. 1610 template< bool B > struct algorithm { 1611 template< class T1, class T2 > static int do_it(T1 &, T2 &) { /*...*/ return 1; } 1612 }; 1613 1614 // Second way of operating. 1615 template<> struct algorithm<true> { 1616 template< class T1, class T2 > static int do_it(T1, T2) { /*...*/ return 2; } 1617 }; 1618 1619 // Instantiating 'elaborate' will automatically instantiate the correct way to operate, depending on the types used. 1620 template< class T1, class T2 > int elaborate(T1 A, T2 B) { 1621 // Use the second way only if 'T1' is an integer and if 'T2' is a floating point, 1622 // otherwise use the first way. 1623 return algorithm< std::is_integral<T1>::value && std::is_floating_point<T2>::value >::do_it(A, B); 1624 } 1625 </pre></div> 1626 1627 <p> 1628 SWIG correctly parses the template specialization, template types etc. 1629 However, metaprogramming and the additional support in the type_traits header is really for compile time and is not much use at runtime for the target languages. 1630 For example, as SWIG requires explicit instantiation of templates via <tt>%template</tt>, there isn't much that <tt>std::is_integral<int></tt> is going to provide by itself. 1631 However, template functions using such metaprogramming techniques might be useful to wrap. 1632 For example, the following instantiations could be made: 1633 </p> 1634 1635 <div class="code"><pre> 1636 %template(Elaborate) elaborate<int, int>; 1637 %template(Elaborate) elaborate<int, double>; 1638 </pre></div> 1639 1640 <p> 1641 Then the appropriate algorithm can be called for the subset of types given by the above <tt>%template</tt> instantiations from a target language, such as Python: 1642 </p> 1643 1644 <div class="targetlang"><pre> 1645 >>> Elaborate(0, 0) 1646 1 1647 >>> Elaborate(0, 0.0) 1648 2 1649 </pre></div> 1650 1651 <H3><a name="CPlusPlus11_uniform_method_for_computing_return_type_of_function_objects">7.3.10 Uniform method for computing return type of function objects</a></H3> 1652 1653 1654 <p> 1655 The new <tt>std::result_of</tt> class introduced in the <functional> header provides a generic way to obtain the return type of a function type via <tt>std::result_of::type</tt>. 1656 There isn't any library interface file to support this type. 1657 With a bit of work, SWIG will deduce the return type of functions when used in <tt>std::result_of</tt> using the approach shown below. 1658 The technique basically forward declares the <tt>std::result_of</tt> template class, then partially specializes it for the function types of interest. 1659 SWIG will use the partial specialization and hence correctly use the <tt>std::result_of::type</tt> provided in the partial specialization. 1660 </p> 1661 1662 <div class="code"><pre> 1663 %inline %{ 1664 #include <functional> 1665 typedef double(*fn_ptr)(double); 1666 %} 1667 1668 namespace std { 1669 // Forward declaration of result_of 1670 template<typename Func> struct result_of; 1671 // Add in a partial specialization of result_of 1672 template<> struct result_of< fn_ptr(double) > { 1673 typedef double type; 1674 }; 1675 } 1676 1677 %template() std::result_of< fn_ptr(double) >; 1678 1679 %inline %{ 1680 1681 double square(double x) { 1682 return (x * x); 1683 } 1684 1685 template<class Fun, class Arg> 1686 typename std::result_of<Fun(Arg)>::type test_result_impl(Fun fun, Arg arg) { 1687 return fun(arg); 1688 } 1689 %} 1690 1691 %template(test_result) test_result_impl< fn_ptr, double >; 1692 %constant double (*SQUARE)(double) = square; 1693 </pre></div> 1694 1695 <p> 1696 Note the first use of <tt>%template</tt> which SWIG requires to instantiate the template. 1697 The empty template instantiation suffices as no proxy class is required for <tt>std::result_of<Fun(Arg)>::type</tt> as this type is really just a <tt>double</tt>. 1698 The second <tt>%template</tt> instantiates the template function which is being wrapped for use as a callback. 1699 The <tt>%constant</tt> can then be used for any callback function as described in <a href="SWIG.html#SWIG_nn30">Pointers to functions and callbacks</a>. 1700 </p> 1701 1702 <p> 1703 Example usage from Python should give the not too surprising result: 1704 </p> 1705 1706 <div class="targetlang"><pre> 1707 >>> test_result(SQUARE, 5.0) 1708 25.0 1709 </pre></div> 1710 1711 <p> 1712 Phew, that is a lot of hard work to get a callback working. 1713 You could just go with the more attractive option of just using <tt>double</tt> as the return type in the function declaration instead of <tt>result_of</tt>! 1714 </p> 1715 1716 1717 </body> 1718 </html>