FFI: Clarify scalar boxing behavior.

Prevent misunderstandings like in #1216

diff --git a/doc/ext_ffi_semantics.html b/doc/ext_ffi_semantics.html
index 5ba82a1e77b32c310220b73c28b305a4637df734..b56e57a162f23e6d6db58b6adde404669e3ff21c 100644 (file)
--- a/doc/ext_ffi_semantics.html
+++ b/doc/ext_ffi_semantics.html
@@ -440,6 +440,19 @@ If you don't do this, the default Lua number &rarr; <tt>double</tt>
 conversion rule applies. A vararg C&nbsp;function expecting an integer
 will see a garbled or uninitialized value.
 </p>
+<p>
+Note: this is the only place where creating a boxed scalar number type is
+actually useful. <b>Never use <tt>ffi.new("int")</tt>, <tt>ffi.new("float")</tt>
+etc. anywhere else!</b>
+</p>
+<p style="font-size: 8pt;">
+Ditto for <tt>ffi.cast()</tt>. Explicitly boxing scalars <b>does not</b>
+improve performance or force <tt>int</tt> or <tt>float</tt> arithmetic! It
+just adds costly boxing, unboxing and conversions steps. And it may lead
+to surprise results, because
+<a href="#cdata_arith">cdata arithmetic on scalar numbers</a>
+is always performed on 64 bit integers.
+</p>
 
 <h2 id="init">Initializers</h2>
 <p>