From a6386bdabed83d87e5d1746666652108b6b2682d Mon Sep 17 00:00:00 2001
From: Mike Pall <mike>
Date: Sat, 25 May 2024 15:48:07 +0200
Subject: [PATCH] FFI: Clarify scalar boxing behavior.

Prevent misunderstandings like in #1216
---
 doc/ext_ffi_semantics.html | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/doc/ext_ffi_semantics.html b/doc/ext_ffi_semantics.html
index 5ba82a1e..b56e57a1 100644
--- 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>