deploy: ruby-rice/rice@3360646

Author: cfis

4.x/architecture/incomplete_types/index.html

@@ -3627,6 +3627,8 @@ <h2 id="key-components">Key Components<a class="headerlink" href="#key-component
   Implementing Ruby-style iteration for C++ containers.</p>
 <p><a href="../procs_and_blocks/">Procs and Blocks</a>
   Bridging Ruby procs/blocks and C++ function pointers.</p>
+<p><a href="../incomplete_types/">Incomplete Types</a>
+  Support for forward-declared types (PIMPL idiom, opaque handles).</p>
 <h2 id="thread-safety">Thread Safety<a class="headerlink" href="#thread-safety" title="Permanent link">&para;</a></h2>
 <p>Rice itself is thread-safe for reading (method invocation). However:</p>
 <ul>

4.x/architecture/overview/index.html

@@ -3731,6 +3731,9 @@ <h3 id="inheriting-from-c-classes">Inheriting from C++ Classes<a class="headerli
 <a id="__codelineno-5-25" name="__codelineno-5-25" href="#__codelineno-5-25"></a><span class="p">}</span>
 </code></pre></div>
 <p>The second template parameter tells Rice about the inheritance relationship, enabling proper type conversions and polymorphic behavior.</p>
+<blockquote>
+<p><strong>Note:</strong> Rice requires RTTI to be enabled for polymorphism to work correctly. When a C++ method returns a <code>Base*</code> that actually points to a <code>Derived</code> object, Rice uses RTTI to wrap it as the correct Ruby class. See <a href="../../packaging/build_settings/#rtti">RTTI</a> for details.</p>
+</blockquote>
 <p>If you want to create Ruby classes that inherit from wrapped C++ classes and override virtual methods, see the <a href="../directors/">Directors</a> section.</p>
 <h2 id="method-chaining">Method Chaining<a class="headerlink" href="#method-chaining" title="Permanent link">&para;</a></h2>
 <p>Most methods on <code>Class</code> and <code>Data_Type</code> return a reference to self, allowing you to chain method calls:</p>

4.x/architecture/registries/index.html

@@ -1334,6 +1334,45 @@
     </span>
   </a>
 
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#iterator-requirements" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Iterator Requirements
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Iterator Requirements">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#missing-iterator-traits" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Missing Iterator Traits
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#common-iterator-categories" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Common Iterator Categories
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
 
         <li class="md-nav__item">
@@ -3598,21 +3637,78 @@ <h2 id="enumerable-support-internal-iterators">Enumerable Support (Internal Iter
 <a id="__codelineno-3-8" name="__codelineno-3-8" href="#__codelineno-3-8"></a><span class="k">end</span>
 </code></pre></div>
 <p>Where the result will be <code>[6, 4, 2]</code>.</p>
+<h2 id="iterator-requirements">Iterator Requirements<a class="headerlink" href="#iterator-requirements" title="Permanent link">&para;</a></h2>
+<p>Rice uses <code>std::iterator_traits</code> to determine the value type, reference type, and other properties of iterators. This means your iterator must either:</p>
+<ol>
+<li>Define the standard iterator typedefs (<code>value_type</code>, <code>reference</code>, <code>pointer</code>, <code>difference_type</code>, <code>iterator_category</code>), or</li>
+<li>Have a specialization of <code>std::iterator_traits</code> defined for it</li>
+</ol>
+<p>Most STL iterators and well-designed C++ iterators already satisfy these requirements. However, some libraries define iterators that lack these typedefs.</p>
+<h3 id="missing-iterator-traits">Missing Iterator Traits<a class="headerlink" href="#missing-iterator-traits" title="Permanent link">&para;</a></h3>
+<p>If you encounter a compiler error like:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a>error C2039: &#39;value_type&#39;: is not a member of &#39;std::iterator_traits&lt;MyIterator&gt;&#39;
+</code></pre></div>
+<p>You need to provide a <code>std::iterator_traits</code> specialization for that iterator. For example:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a><span class="cp">#include</span><span class="w"> </span><span class="cpf">&lt;iterator&gt;</span>
+<a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a>
+<a id="__codelineno-5-3" name="__codelineno-5-3" href="#__codelineno-5-3"></a><span class="c1">// Specialization for an iterator that lacks proper traits</span>
+<a id="__codelineno-5-4" name="__codelineno-5-4" href="#__codelineno-5-4"></a><span class="k">namespace</span><span class="w"> </span><span class="nn">std</span>
+<a id="__codelineno-5-5" name="__codelineno-5-5" href="#__codelineno-5-5"></a><span class="p">{</span>
+<a id="__codelineno-5-6" name="__codelineno-5-6" href="#__codelineno-5-6"></a><span class="w">  </span><span class="k">template</span><span class="o">&lt;&gt;</span>
+<a id="__codelineno-5-7" name="__codelineno-5-7" href="#__codelineno-5-7"></a><span class="w">  </span><span class="k">struct</span><span class="w"> </span><span class="nc">iterator_traits</span><span class="o">&lt;</span><span class="n">MyNamespace</span><span class="o">::</span><span class="n">MyIterator</span><span class="o">&gt;</span>
+<a id="__codelineno-5-8" name="__codelineno-5-8" href="#__codelineno-5-8"></a><span class="w">  </span><span class="p">{</span>
+<a id="__codelineno-5-9" name="__codelineno-5-9" href="#__codelineno-5-9"></a><span class="w">    </span><span class="k">using</span><span class="w"> </span><span class="n">iterator_category</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">forward_iterator_tag</span><span class="p">;</span>
+<a id="__codelineno-5-10" name="__codelineno-5-10" href="#__codelineno-5-10"></a><span class="w">    </span><span class="k">using</span><span class="w"> </span><span class="n">value_type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">MyValueType</span><span class="p">;</span>
+<a id="__codelineno-5-11" name="__codelineno-5-11" href="#__codelineno-5-11"></a><span class="w">    </span><span class="k">using</span><span class="w"> </span><span class="n">difference_type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">ptrdiff_t</span><span class="p">;</span>
+<a id="__codelineno-5-12" name="__codelineno-5-12" href="#__codelineno-5-12"></a><span class="w">    </span><span class="k">using</span><span class="w"> </span><span class="n">pointer</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">MyValueType</span><span class="o">*</span><span class="p">;</span>
+<a id="__codelineno-5-13" name="__codelineno-5-13" href="#__codelineno-5-13"></a><span class="w">    </span><span class="k">using</span><span class="w"> </span><span class="n">reference</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">MyValueType</span><span class="o">&amp;</span><span class="p">;</span>
+<a id="__codelineno-5-14" name="__codelineno-5-14" href="#__codelineno-5-14"></a><span class="w">  </span><span class="p">};</span>
+<a id="__codelineno-5-15" name="__codelineno-5-15" href="#__codelineno-5-15"></a><span class="p">}</span>
+</code></pre></div>
+<p>Place this specialization before your Rice bindings code, typically right after the includes.</p>
+<h3 id="common-iterator-categories">Common Iterator Categories<a class="headerlink" href="#common-iterator-categories" title="Permanent link">&para;</a></h3>
+<p>Choose the appropriate <code>iterator_category</code> based on your iterator's capabilities:</p>
+<table>
+<thead>
+<tr>
+<th>Category</th>
+<th>Operations Supported</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>input_iterator_tag</code></td>
+<td>Read-only, single-pass (<code>++</code>, <code>*</code>, <code>==</code>)</td>
+</tr>
+<tr>
+<td><code>forward_iterator_tag</code></td>
+<td>Read/write, multi-pass (<code>++</code>, <code>*</code>, <code>==</code>)</td>
+</tr>
+<tr>
+<td><code>bidirectional_iterator_tag</code></td>
+<td>Forward + backward (<code>++</code>, <code>--</code>, <code>*</code>, <code>==</code>)</td>
+</tr>
+<tr>
+<td><code>random_access_iterator_tag</code></td>
+<td>Bidirectional + random access (<code>+</code>, <code>-</code>, <code>[]</code>, <code>&lt;</code>)</td>
+</tr>
+</tbody>
+</table>
 <h2 id="enumerator-support-external-iterators">Enumerator Support (External Iterators)<a class="headerlink" href="#enumerator-support-external-iterators" title="Permanent link">&para;</a></h2>
 <p>Ruby supports external iterators via the <a href="https://ruby-doc.org/3.2.2/Enumerator.html">Enumerator</a> class. The <code>define_iterator</code> method automatically adds support for Enumerators.</p>
 <p>Enumerators can be created by calling an iterator method without a block, in the same way you can call <code>Array#each</code> or other methods without a block. For example:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a><span class="n">intVector</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="no">IntVector</span><span class="o">.</span><span class="n">new</span>
-<a id="__codelineno-4-2" name="__codelineno-4-2" href="#__codelineno-4-2"></a><span class="n">intVector</span><span class="o">.</span><span class="n">push_back</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
-<a id="__codelineno-4-3" name="__codelineno-4-3" href="#__codelineno-4-3"></a><span class="n">intVector</span><span class="o">.</span><span class="n">push_back</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>
-<a id="__codelineno-4-4" name="__codelineno-4-4" href="#__codelineno-4-4"></a><span class="n">intVector</span><span class="o">.</span><span class="n">push_back</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>
-<a id="__codelineno-4-5" name="__codelineno-4-5" href="#__codelineno-4-5"></a>
-<a id="__codelineno-4-6" name="__codelineno-4-6" href="#__codelineno-4-6"></a><span class="c1"># Get an enumerator</span>
-<a id="__codelineno-4-7" name="__codelineno-4-7" href="#__codelineno-4-7"></a><span class="n">enumerator</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">intVector</span><span class="o">.</span><span class="n">each</span>
-<a id="__codelineno-4-8" name="__codelineno-4-8" href="#__codelineno-4-8"></a>
-<a id="__codelineno-4-9" name="__codelineno-4-9" href="#__codelineno-4-9"></a><span class="c1"># Now  use it</span>
-<a id="__codelineno-4-10" name="__codelineno-4-10" href="#__codelineno-4-10"></a><span class="n">enumerator</span><span class="o">.</span><span class="n">map</span><span class="w"> </span><span class="o">|</span><span class="n">i</span><span class="o">|</span>
-<a id="__codelineno-4-11" name="__codelineno-4-11" href="#__codelineno-4-11"></a><span class="w">  </span><span class="n">i</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="mi">2</span>
-<a id="__codelineno-4-12" name="__codelineno-4-12" href="#__codelineno-4-12"></a><span class="k">end</span>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a><span class="n">intVector</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="no">IntVector</span><span class="o">.</span><span class="n">new</span>
+<a id="__codelineno-6-2" name="__codelineno-6-2" href="#__codelineno-6-2"></a><span class="n">intVector</span><span class="o">.</span><span class="n">push_back</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
+<a id="__codelineno-6-3" name="__codelineno-6-3" href="#__codelineno-6-3"></a><span class="n">intVector</span><span class="o">.</span><span class="n">push_back</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>
+<a id="__codelineno-6-4" name="__codelineno-6-4" href="#__codelineno-6-4"></a><span class="n">intVector</span><span class="o">.</span><span class="n">push_back</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>
+<a id="__codelineno-6-5" name="__codelineno-6-5" href="#__codelineno-6-5"></a>
+<a id="__codelineno-6-6" name="__codelineno-6-6" href="#__codelineno-6-6"></a><span class="c1"># Get an enumerator</span>
+<a id="__codelineno-6-7" name="__codelineno-6-7" href="#__codelineno-6-7"></a><span class="n">enumerator</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">intVector</span><span class="o">.</span><span class="n">each</span>
+<a id="__codelineno-6-8" name="__codelineno-6-8" href="#__codelineno-6-8"></a>
+<a id="__codelineno-6-9" name="__codelineno-6-9" href="#__codelineno-6-9"></a><span class="c1"># Now  use it</span>
+<a id="__codelineno-6-10" name="__codelineno-6-10" href="#__codelineno-6-10"></a><span class="n">enumerator</span><span class="o">.</span><span class="n">map</span><span class="w"> </span><span class="o">|</span><span class="n">i</span><span class="o">|</span>
+<a id="__codelineno-6-11" name="__codelineno-6-11" href="#__codelineno-6-11"></a><span class="w">  </span><span class="n">i</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="mi">2</span>
+<a id="__codelineno-6-12" name="__codelineno-6-12" href="#__codelineno-6-12"></a><span class="k">end</span>
 </code></pre></div>
 
 

4.x/bindings/classes/index.html

@@ -3914,7 +3914,9 @@ <h2 id="492-unreleased">4.9.2 (unreleased)<a class="headerlink" href="#492-unrel
 <p>Enhancements:
 * Add support for incomplete types (PIMPL/opaque handle patterns). Rice now uses <code>typeid(T*)</code> for forward-declared types that are never fully defined.
 * Add support for <code>noexcept</code> functions, static members, and static member functions
-* Add support for <code>Buffer&lt;void*&gt;</code> and <code>Pointer&lt;void*&gt;</code></p>
+* Add support for <code>Buffer&lt;void*&gt;</code> and <code>Pointer&lt;void*&gt;</code>
+* Add support for <code>std::function</code>. Ruby procs, lambdas, and blocks can be wrapped in <code>std::function</code> objects and passed to C++ methods. C++ functions returning <code>std::function</code> are automatically wrapped.
+* Add support for <code>std::ostream</code>, <code>std::ostringstream</code>, and <code>std::ofstream</code>. Ruby can write to C++ streams and pass them to C++ functions. Standard streams are exposed as <code>Std::COUT</code> and <code>Std::CERR</code>.</p>
 <p>Internal:
 * Refactor type handling by merging <code>TypeMapper</code> into <code>TypeDetail</code> and simplifying class hierarchy</p>
 <h2 id="491-2026-01-04">4.9.1 (2026-01-04)<a class="headerlink" href="#491-2026-01-04" title="Permanent link">&para;</a></h2>

4.x/bindings/iterators/index.html

@@ -3575,7 +3575,7 @@ <h2 id="option-2-copy-header-files">Option 2: Copy Header Files<a class="headerl
 </ul>
 <p>When copying headers, use a specific release tag rather than the master branch to ensure stability.</p>
 <h2 id="compiler-requirements">Compiler Requirements<a class="headerlink" href="#compiler-requirements" title="Permanent link">&para;</a></h2>
-<p>Rice requires a C++17 compliant compiler. See <a href="../packaging/build_settings/#compiler-settings">Compiler Settings</a> for the specific flags needed for each compiler.</p>
+<p>Rice requires a C++17 compliant compiler and RTTI to be enabled. See <a href="../packaging/build_settings/#compiler-settings">Compiler Settings</a> for the specific flags needed for each compiler.</p>
 
 
 

4.x/changelog/index.html

@@ -3188,6 +3188,17 @@
     </span>
   </a>
 
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#rtti" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        RTTI
+      
+    </span>
+  </a>
+  
 </li>
 
       </ul>
@@ -3719,6 +3730,13 @@ <h3 id="exception-handling-model">Exception Handling Model<a class="headerlink"
 <p>For Visual C++, the default exception <a href="https://learn.microsoft.com/en-us/cpp/build/reference/eh-exception-handling-model?view=msvc-170">model</a> setting of <code>/EHsc</code> crashes Ruby when calling longjmp with optimizations enabled (/O2). Therefore you must <code>/EHs</code> instead.</p>
 <h3 id="template-backtrace">Template Backtrace<a class="headerlink" href="#template-backtrace" title="Permanent link">&para;</a></h3>
 <p>For g++, you must set <code>-ftemplate-backtrace-limit=0</code> to avoid compilation errors.</p>
+<h3 id="rtti">RTTI<a class="headerlink" href="#rtti" title="Permanent link">&para;</a></h3>
+<p>Rice requires RTTI (Run-Time Type Information) to be enabled. RTTI is enabled by default on all major compilers, but if you have explicitly disabled it, you must re-enable it:</p>
+<ul>
+<li><strong>GCC/Clang</strong>: <code>-frtti</code> (default is enabled; do not use <code>-fno-rtti</code>)</li>
+<li><strong>MSVC</strong>: <code>/GR</code> (default is enabled; do not use <code>/GR-</code>)</li>
+</ul>
+<p>RTTI is essential for Rice's polymorphism support. When a C++ method returns a base class pointer that actually points to a derived class, Rice uses <code>typeid</code> to determine the correct Ruby class to wrap it as. Without RTTI, all objects would be wrapped as their static (declared) type rather than their actual runtime type.</p>
 <h2 id="linker-settings">Linker Settings<a class="headerlink" href="#linker-settings" title="Permanent link">&para;</a></h2>
 <p>Ruby extensions are shared libraries that the Ruby interpreter loads at runtime using <code>dlopen</code>. These extensions reference symbols from the Ruby C API (such as <code>rb_define_class</code>, <code>rb_funcall</code>, etc.) that are provided by the Ruby interpreter itself. Since these symbols are not available at link time, the linker must be told to allow unresolved symbols.</p>
 <h3 id="macos">macOS<a class="headerlink" href="#macos" title="Permanent link">&para;</a></h3>

4.x/installation/index.html

@@ -44,6 +44,10 @@
          <loc>https://ruby-rice.github.io/rice/architecture/enumerators/</loc>
          <lastmod>2026-01-13</lastmod>
     </url>
+    <url>
+         <loc>https://ruby-rice.github.io/rice/architecture/incomplete_types/</loc>
+         <lastmod>2026-01-13</lastmod>
+    </url>
     <url>
          <loc>https://ruby-rice.github.io/rice/architecture/method_binding/</loc>
          <lastmod>2026-01-13</lastmod>
@@ -268,6 +272,10 @@
          <loc>https://ruby-rice.github.io/rice/stl/exception_ptr/</loc>
          <lastmod>2026-01-13</lastmod>
     </url>
+    <url>
+         <loc>https://ruby-rice.github.io/rice/stl/function/</loc>
+         <lastmod>2026-01-13</lastmod>
+    </url>
     <url>
          <loc>https://ruby-rice.github.io/rice/stl/map/</loc>
          <lastmod>2026-01-13</lastmod>
@@ -280,6 +288,10 @@
          <loc>https://ruby-rice.github.io/rice/stl/optional/</loc>
          <lastmod>2026-01-13</lastmod>
     </url>
+    <url>
+         <loc>https://ruby-rice.github.io/rice/stl/ostream/</loc>
+         <lastmod>2026-01-13</lastmod>
+    </url>
     <url>
          <loc>https://ruby-rice.github.io/rice/stl/pair/</loc>
          <lastmod>2026-01-13</lastmod>