/xbmc/visualizations/Vortex/angelscript/docs/doxygen/source/doc_as_vs_cpp_types.h

http://github.com/xbmc/xbmc · C++ Header · 131 lines · 0 code · 0 blank · 131 comment · 0 complexity · fe950b68c78b6f4dbc8f84c3d9d487e5 MD5 · raw file

  1. /**
  2. \page doc_as_vs_cpp_types Datatypes in AngelScript and C++
  3. \section doc_as_vs_cpp_types_1 Primitives
  4. Primitives in AngelScript have direct matches in C++.
  5. <table border=0 cellspacing=0 cellpadding=0>
  6. <tr><td width=100><b>AngelScript</b></td><td width=150><b>C++</b></td><td width=100><b>Size (bits)</b></tr>
  7. <tr><td>void </td><td>void </td><td>0 </td></tr>
  8. <tr><td>int8 </td><td>signed char </td><td>8 </td></tr>
  9. <tr><td>int16 </td><td>signed short </td><td>16 </td></tr>
  10. <tr><td>int </td><td>signed long (*) </td><td>32 </td></tr>
  11. <tr><td>int64 </td><td>signed long long </td><td>64 </td></tr>
  12. <tr><td>uint8 </td><td>unsigned char </td><td>8 </td></tr>
  13. <tr><td>uint16</td><td>unsigned short </td><td>16 </td></tr>
  14. <tr><td>uint </td><td>unsigned long (*) </td><td>32 </td></tr>
  15. <tr><td>uint64</td><td>unsigned long long</td><td>64 </td></tr>
  16. <tr><td>float </td><td>float </td><td>32 </td></tr>
  17. <tr><td>double</td><td>double </td><td>64 </td></tr>
  18. <tr><td>bool </td><td>bool </td><td>8 (**)</td></tr>
  19. </table>
  20. %*) If the target CPU is 32 bit, the C++ type long is 32 bit, but on 64 bit CPUs
  21. it is commonly 64 bit, but in AngelScript an int is always 32 bits.
  22. %**) On 32 bit PowerPC platforms the bool type commonly have the size of 32 bit,
  23. when compiled on such platforms AngelScript also uses 32 bits for the bool type
  24. \section doc_as_vs_cpp_types_5 Strings
  25. AngelScript expects the application to register its own \ref doc_strings "string type",
  26. so the string types should match perfectly.
  27. The char* string type that is so convenient in C++ is however very difficult to use
  28. in a scripted environment where you do not have full control over how it is used. For that
  29. reason it is recommended that you wrap any functions that use the char* string type so
  30. that the string is properly converted to an object that can be safely handled by both
  31. the application and the script engine, e.g. std::string or another class of your preference.
  32. \section doc_as_vs_cpp_types_2 Arrays
  33. The AngelScript arrays are not directly matched by C++ arrays. The arrays
  34. are stored in an special object, accessed through the \ref asIScriptArray interface.
  35. Thus you can normally not directly exchange a script with a C++ function expecting
  36. a C++ array, or vice versa. Nor can the application register C++ arrays as properties
  37. and expect AngelScript to be able to understand them.
  38. It is however possible to override AngelScript's built-in array objects
  39. with application specified objects, on a per array type basis.
  40. \section doc_as_vs_cpp_types_3 Object handles
  41. The AngelScript object handles are reference counted pointers to objects.
  42. This means that for object handles to work, the object must have some way of
  43. counting references, for example an AddRef/Release method pair.
  44. When AngelScript passes an object handle by value to a function it
  45. increases the reference count to count for the argument instance, thus the
  46. function is responsible for releasing the reference once it is finished with
  47. it. In the same manner AngelScript expects any handle returned from a function
  48. to already have the reference accounted for.
  49. However, when registering functions/methods with AngelScript the
  50. application can tell the library that it should automatically take care of
  51. releasing the handle references once a function return, likewise for returned
  52. handles. This is done by adding a + sign to the \@ type modifier. When doing
  53. this an object handle can be safely passed to a C++ function that expects a
  54. normal pointer, but don't release it afterwards.
  55. \see \ref doc_obj_handle
  56. \section doc_as_vs_cpp_types_4 Parameter references
  57. Because AngelScript needs to guarantee validity of pointers at all times,
  58. it doesn't always pass references to the true object to the function
  59. parameter. Instead it creates a copy of the object, whose reference is passed
  60. to the function, and if the reference is marked to return a value, the clone
  61. is copied back to the original object (if it still exists) once the function
  62. returns.
  63. Because of this, AngelScript's parameter references are mostly compatible
  64. with C++ references, or pointers, except that the address normally shouldn't be
  65. stored for later use, since the object may be destroyed once the function returns.
  66. If it is necessary to store the address of the object, then object handles
  67. should be used instead.
  68. <table border=0 cellspacing=0 cellpadding=0>
  69. <tr><td width=100 valign=top><b>Reference</b></td><td valign=top><b>Description</b></td></tr>
  70. <tr><td valign=top>&in</td><td>A copy of the value is always taken and the
  71. reference to the copy is passed to the function. For script functions this is not
  72. useful, but it is maintained for compatibility with application registered functions.</td></tr>
  73. <tr><td valign=top>const &in</td><td>If the life time of the value can be
  74. guaranteed to be valid during the execution of the function, the reference to the
  75. true object is passed to the function, otherwise a copy is made.</td></tr>
  76. <tr><td valign=top>&out</td><td>A reference to an unitialized value is passed
  77. to the function. When the function returns the value is copied to the true reference.
  78. The argument expression is evaluated only after the function call. This is the best
  79. way to have functions return multiple values.</td></tr>
  80. <tr><td valign=top>const &out</td><td>Useless as the function wouldn't be able
  81. to modify the value.</td></tr>
  82. <tr><td valign=top>&inout</td><td>The true reference is always passed to the
  83. function. If the life time of the value cannot be guaranteed, a compile time error
  84. is generated and the script writer will have to copy the value to a local variable
  85. first. Objects that support object handles are best suitable for this type as they
  86. can always be guaranteed.</td></tr>
  87. <tr><td valign=top>const &inout</td><td>The reference cannot be changed by the
  88. function.</td></tr>
  89. </table>
  90. If the application wants parameter references that work like they do in C++,
  91. then the engine property asEP_ALLOW_UNSAFE_REFERENCES can be set. When this is done,
  92. the parameter references can be declared without the <code>in</code>, <code>out</code>,
  93. or <code>inout</code>. The parameter references declared without any of the keywords
  94. will always pass the address to the original value, and will not have any restrictions
  95. to the expressions that can be used. The parameter references with the <code>in</code>
  96. and <code>out</code> keywords will still work like before, but the references with the
  97. <code>inout</code> keyword will have the restrictions removed so that they work just
  98. like normal C++ references.
  99. The application writer and script writer has to be aware that it is possible to
  100. write scripts that access invalid references when the library is compiled in this
  101. mode, just like it is possible to do so in C++.
  102. */