PageRenderTime 50ms CodeModel.GetById 19ms RepoModel.GetById 1ms app.codeStats 0ms

/tags/ttn-post-libtool-1-4-3-upgrade/SWIG/Examples/java/reference/index.html

#
HTML | 149 lines | 117 code | 32 blank | 0 comment | 0 complexity | 49252a6e8e3fa627dac4606f3995f7a5 MD5 | raw file
Possible License(s): LGPL-2.1, Cube, GPL-3.0, 0BSD, GPL-2.0
  1. <html>
  2. <head>
  3. <title>SWIG:Examples:java:reference</title>
  4. </head>
  5. <body bgcolor="#ffffff">
  6. <tt>SWIG/Examples/java/reference/</tt>
  7. <hr>
  8. <H2>C++ Reference Handling</H2>
  9. <tt>$Header$</tt><br>
  10. <p>
  11. This example tests SWIG's handling of C++ references. Since C++
  12. references are closely related to pointers (as both refer to a
  13. location in memory), SWIG simply collapses all references into
  14. pointers when creating wrappers.
  15. <h2>Some examples</h2>
  16. References are most commonly used as function parameter. For example,
  17. you might have an operator like this:
  18. <blockquote>
  19. <pre>
  20. Vector operator+(const Vector &a, const Vector &b) {
  21. Vector result;
  22. result.x = a.x + b.x;
  23. result.y = a.y + b.y;
  24. result.z = a.z + b.z;
  25. return result;
  26. }
  27. </pre>
  28. </blockquote>
  29. or a function:
  30. <blockquote>
  31. <pre>
  32. Vector addv(const Vector &a, const Vector &b) {
  33. Vector result;
  34. result.x = a.x + b.x;
  35. result.y = a.y + b.y;
  36. result.z = a.z + b.z;
  37. return result;
  38. }
  39. </pre>
  40. </blockquote>
  41. In these cases, SWIG transforms everything into a pointer and creates a wrapper
  42. that looks like this:
  43. <blockquote>
  44. <pre>
  45. Vector wrap_addv(Vector *a, Vector *b) {
  46. return addv(*a,*b);
  47. }
  48. </pre>
  49. </blockquote>
  50. Occasionally, a reference is used as a return value of a function
  51. when the return result is to be used as an lvalue in an expression.
  52. The prototypical example is an operator like this:
  53. <blockquote>
  54. <pre>
  55. Vector &operator[](int index);
  56. </pre>
  57. </blockquote>
  58. or a method:
  59. <blockquote>
  60. <pre>
  61. Vector &get(int index);
  62. </pre>
  63. </blockquote>
  64. For functions returning references, a wrapper like this is created:
  65. <blockquote>
  66. <pre>
  67. Vector *wrap_Object_get(Object *self, int index) {
  68. Vector &result = self->get(index);
  69. return &result;
  70. }
  71. </pre>
  72. </blockquote>
  73. The following <a href="example.h">header file</a> contains some class
  74. definitions with some operators and use of references.
  75. <h2>SWIG Interface</h2>
  76. SWIG does NOT support overloaded operators so it can not directly build
  77. an interface to the classes in the above file. However, a number of workarounds
  78. can be made. For example, an overloaded operator can be stuck behind a function
  79. call such as the <tt>addv()</tt> function above. Array access can be handled
  80. with a pair of set/get functions like this:
  81. <blockquote>
  82. <pre>
  83. class VectorArray {
  84. public:
  85. ...
  86. %addmethods {
  87. Vector &get(int index) {
  88. return (*self)[index];
  89. }
  90. void set(int index, Vector &a) {
  91. (*self)[index] = a;
  92. }
  93. }
  94. ...
  95. }
  96. </pre>
  97. </blockquote>
  98. Click <a href="example.i">here</a> to see a SWIG interface file with these additions.
  99. <h2>Sample Java program</h2>
  100. Click <a href="main.java">here</a> to see a Java program that manipulates some C++ references.
  101. <h2>Notes:</h2>
  102. <ul>
  103. <li>C++ references primarily provide notational convenience for C++
  104. source code. However, Java only supports the 'x.a'
  105. notation so it doesn't much matter.
  106. <p>
  107. <li>When a program returns a reference, a pointer is returned.
  108. Unlike return by value, memory is not allocated to hold the
  109. return result.
  110. <p>
  111. <li>SWIG has particular trouble handling various combinations of references
  112. and pointers. This is side effect of an old parsing scheme and
  113. type representation that will be replaced in future versions.
  114. </ul>
  115. <hr>
  116. </body>
  117. </html>