main/r/reference/nanoarrow_pointer_is_valid.html - arrow-nanoarrow - Git at Google

 <!DOCTYPE html>
 <!-- Generated by pkgdown: do not edit by hand --><html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"><title>Danger zone: low-level pointer operations — nanoarrow_pointer_is_valid • nanoarrow</title><script src="../deps/jquery-3.6.0/jquery-3.6.0.min.js"></script><meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"><link href="../deps/bootstrap-5.3.1/bootstrap.min.css" rel="stylesheet"><script src="../deps/bootstrap-5.3.1/bootstrap.bundle.min.js"></script><link href="../deps/font-awesome-6.4.2/css/all.min.css" rel="stylesheet"><link href="../deps/font-awesome-6.4.2/css/v4-shims.min.css" rel="stylesheet"><script src="../deps/headroom-0.11.0/headroom.min.js"></script><script src="../deps/headroom-0.11.0/jQuery.headroom.min.js"></script><script src="../deps/bootstrap-toc-1.0.1/bootstrap-toc.min.js"></script><script src="../deps/clipboard.js-2.0.11/clipboard.min.js"></script><script src="../deps/search-1.0.0/autocomplete.jquery.min.js"></script><script src="../deps/search-1.0.0/fuse.min.js"></script><script src="../deps/search-1.0.0/mark.min.js"></script><!-- pkgdown --><script src="../pkgdown.js"></script><meta property="og:title" content="Danger zone: low-level pointer operations — nanoarrow_pointer_is_valid"><meta name="description" content="The nanoarrow_schema,
 nanoarrow_array,
 and nanoarrow_array_stream classes are
 represented in R as external pointers (EXTPTRSXP). When these objects
 go out of scope (i.e., when they are garbage collected or shortly
 thereafter), the underlying object's release() callback is called if
 the underlying pointer is non-null and if the release() callback is
 non-null."><meta property="og:description" content="The nanoarrow_schema,
 nanoarrow_array,
 and nanoarrow_array_stream classes are
 represented in R as external pointers (EXTPTRSXP). When these objects
 go out of scope (i.e., when they are garbage collected or shortly
 thereafter), the underlying object's release() callback is called if
 the underlying pointer is non-null and if the release() callback is
 non-null."></head><body>
     <a href="#main" class="visually-hidden-focusable">Skip to contents</a>


     <nav class="navbar navbar-expand-lg fixed-top bg-light" data-bs-theme="light" aria-label="Site navigation"><div class="container">

     <a class="navbar-brand me-2" href="../index.html">nanoarrow</a>

     <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">0.5.0.9000</small>


     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
       <span class="navbar-toggler-icon"></span>
     </button>

     <div id="navbar" class="collapse navbar-collapse ms-3">
       <ul class="navbar-nav me-auto"><li class="active nav-item"><a class="nav-link" href="../reference/index.html">Reference</a></li>
 <li class="nav-item"><a class="nav-link" href="../news/index.html">Changelog</a></li>
       </ul><ul class="navbar-nav"><li class="nav-item"><form class="form-inline" role="search">
  <input class="form-control" type="search" name="search-input" id="search-input" autocomplete="off" aria-label="Search site" placeholder="Search for" data-search-index="../search.json"></form></li>
 <li class="nav-item"><a class="external-link nav-link" href="https://github.com/apache/arrow-nanoarrow/" aria-label="GitHub"><span class="fa fab fa-github fa-lg"></span></a></li>
       </ul></div>


   </div>
 </nav><div class="container template-reference-topic">
 <div class="row">
   <main id="main" class="col-md-9"><div class="page-header">

       <h1>Danger zone: low-level pointer operations</h1>
       <small class="dont-index">Source: <a href="https://github.com/apache/arrow-nanoarrow/blob/main/r/R/pointers.R" class="external-link"><code>R/pointers.R</code></a></small>
       <div class="d-none name"><code>nanoarrow_pointer_is_valid.Rd</code></div>
     </div>

     <div class="ref-description section level2">
     <p>The <a href="as_nanoarrow_schema.html">nanoarrow_schema</a>,
 <a href="as_nanoarrow_array.html">nanoarrow_array</a>,
 and <a href="as_nanoarrow_array_stream.html">nanoarrow_array_stream</a> classes are
 represented in R as external pointers (<code>EXTPTRSXP</code>). When these objects
 go out of scope (i.e., when they are garbage collected or shortly
 thereafter), the underlying object's <code>release()</code> callback is called if
 the underlying pointer is non-null and if the <code>release()</code> callback is
 non-null.</p>
     </div>

     <div class="section level2">
     <h2 id="ref-usage">Usage<a class="anchor" aria-label="anchor" href="#ref-usage"></a></h2>
     <div class="sourceCode"><pre class="sourceCode r"><code><span><span class="fu">nanoarrow_pointer_is_valid</span><span class="op">(</span><span class="va">ptr</span><span class="op">)</span></span>
 <span></span>
 <span><span class="fu">nanoarrow_pointer_addr_dbl</span><span class="op">(</span><span class="va">ptr</span><span class="op">)</span></span>
 <span></span>
 <span><span class="fu">nanoarrow_pointer_addr_chr</span><span class="op">(</span><span class="va">ptr</span><span class="op">)</span></span>
 <span></span>
 <span><span class="fu">nanoarrow_pointer_addr_pretty</span><span class="op">(</span><span class="va">ptr</span><span class="op">)</span></span>
 <span></span>
 <span><span class="fu">nanoarrow_pointer_release</span><span class="op">(</span><span class="va">ptr</span><span class="op">)</span></span>
 <span></span>
 <span><span class="fu">nanoarrow_pointer_move</span><span class="op">(</span><span class="va">ptr_src</span>, <span class="va">ptr_dst</span><span class="op">)</span></span>
 <span></span>
 <span><span class="fu">nanoarrow_pointer_export</span><span class="op">(</span><span class="va">ptr_src</span>, <span class="va">ptr_dst</span><span class="op">)</span></span>
 <span></span>
 <span><span class="fu">nanoarrow_allocate_schema</span><span class="op">(</span><span class="op">)</span></span>
 <span></span>
 <span><span class="fu">nanoarrow_allocate_array</span><span class="op">(</span><span class="op">)</span></span>
 <span></span>
 <span><span class="fu">nanoarrow_allocate_array_stream</span><span class="op">(</span><span class="op">)</span></span>
 <span></span>
 <span><span class="fu">nanoarrow_pointer_set_protected</span><span class="op">(</span><span class="va">ptr_src</span>, <span class="va">protected</span><span class="op">)</span></span></code></pre></div>
     </div>

     <div class="section level2">
     <h2 id="arguments">Arguments<a class="anchor" aria-label="anchor" href="#arguments"></a></h2>


 <dl><dt id="arg-ptr-ptr-src-ptr-dst">ptr, ptr_src, ptr_dst<a class="anchor" aria-label="anchor" href="#arg-ptr-ptr-src-ptr-dst"></a></dt>
 <dd><p>An external pointer to a <code>struct ArrowSchema</code>,
 <code>struct ArrowArray</code>, or <code>struct ArrowArrayStream</code>.</p></dd>


 <dt id="arg-protected">protected<a class="anchor" aria-label="anchor" href="#arg-protected"></a></dt>
 <dd><p>An object whose scope must outlive that of <code>ptr</code>. This is
 useful for array streams since at least two specifications involving the
 array stream specify that the stream is only valid for the lifecycle of
 another object (e.g., an AdbcStatement or OGRDataset).</p></dd>

 </dl></div>
     <div class="section level2">
     <h2 id="value">Value<a class="anchor" aria-label="anchor" href="#value"></a></h2>

 <ul><li><p><code>nanoarrow_pointer_is_valid()</code> returns TRUE if the pointer is non-null
 and has a non-null release callback.</p></li>
 <li><p><code>nanoarrow_pointer_addr_dbl()</code> and <code>nanoarrow_pointer_addr_chr()</code> return
 pointer representations that may be helpful to facilitate moving or
 exporting nanoarrow objects to other libraries.</p></li>
 <li><p><code>nanoarrow_pointer_addr_pretty()</code> gives a pointer representation suitable
 for printing or error messages.</p></li>
 <li><p><code>nanoarrow_pointer_release()</code> returns <code>ptr</code>, invisibly.</p></li>
 <li><p><code>nanoarrow_pointer_move()</code> and <code>nanoarrow_pointer_export()</code> reeturn
 <code>ptr_dst</code>, invisibly.</p></li>
 <li><p><code>nanoarrow_allocate_array()</code>, <code>nanoarrow_allocate_schema()</code>, and
 <code>nanoarrow_allocate_array_stream()</code> return an
 <a href="as_nanoarrow_array.html">array</a>, a <a href="as_nanoarrow_schema.html">schema</a>, and an
 <a href="as_nanoarrow_array_stream.html">array stream</a>, respectively.</p></li>
 </ul></div>
     <div class="section level2">
     <h2 id="details">Details<a class="anchor" aria-label="anchor" href="#details"></a></h2>
     <p>When interacting with other C Data Interface implementations, it is
 important to keep in mind that the R object wrapping these pointers is
 always passed by reference (because it is an external pointer) and may
 be referred to by another R object (e.g., an element in a <code><a href="https://rdrr.io/r/base/list.html" class="external-link">list()</a></code> or as a
 variable assigned in a user's environment). When importing a schema,
 array, or array stream into nanoarrow this is not a problem: the R object
 takes ownership of the lifecycle and memory is released when the R
 object is garbage collected. In this case, one can use
 <code>nanoarrow_pointer_move()</code> where <code>ptr_dst</code> was created using
 <code>nanoarrow_allocate_*()</code>.</p>
 <p>The case of exporting is more complicated and as such has a dedicated
 function, <code>nanoarrow_pointer_export()</code>, that implements different logic
 schemas, arrays, and array streams:</p><ul><li><p>Schema objects are (deep) copied such that a fresh copy of the schema
 is exported and made the responsibility of some other C data interface
 implementation.</p></li>
 <li><p>Array objects are exported as a shell around the original array that
 preserves a reference to the R object. This ensures that the buffers
 and children pointed to by the array are not copied and that any references
 to the original array are not invalidated.</p></li>
 <li><p>Array stream objects are moved: the responsibility for the object is
 transferred to the other C data interface implementation and any
 references to the original R object are invalidated. Because these
 objects are mutable, this is typically what you want (i.e., you should
 not be pulling arrays from a stream accidentally from two places).</p></li>
 </ul><p>If you know the lifecycle of your object (i.e., you created the R object
 yourself and never passed references to it elsewhere), you can slightly
 more efficiently call <code>nanoarrow_pointer_move()</code> for all three pointer
 types.</p>
     </div>

   </main><aside class="col-md-3"><nav id="toc" aria-label="Table of contents"><h2>On this page</h2>
     </nav></aside></div>


     <footer><div class="pkgdown-footer-left">
   <p>Developed by Dewey Dunnington, Apache Arrow.</p>
 </div>

 <div class="pkgdown-footer-right">
   <p>Site built with <a href="https://pkgdown.r-lib.org/" class="external-link">pkgdown</a> 2.1.0.</p>
 </div>

     </footer></div>


   </body></html>
	<!DOCTYPE html>
	<!-- Generated by pkgdown: do not edit by hand --><html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"><title>Danger zone: low-level pointer operations — nanoarrow_pointer_is_valid • nanoarrow</title><script src="../deps/jquery-3.6.0/jquery-3.6.0.min.js"></script><meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"><link href="../deps/bootstrap-5.3.1/bootstrap.min.css" rel="stylesheet"><script src="../deps/bootstrap-5.3.1/bootstrap.bundle.min.js"></script><link href="../deps/font-awesome-6.4.2/css/all.min.css" rel="stylesheet"><link href="../deps/font-awesome-6.4.2/css/v4-shims.min.css" rel="stylesheet"><script src="../deps/headroom-0.11.0/headroom.min.js"></script><script src="../deps/headroom-0.11.0/jQuery.headroom.min.js"></script><script src="../deps/bootstrap-toc-1.0.1/bootstrap-toc.min.js"></script><script src="../deps/clipboard.js-2.0.11/clipboard.min.js"></script><script src="../deps/search-1.0.0/autocomplete.jquery.min.js"></script><script src="../deps/search-1.0.0/fuse.min.js"></script><script src="../deps/search-1.0.0/mark.min.js"></script><!-- pkgdown --><script src="../pkgdown.js"></script><meta property="og:title" content="Danger zone: low-level pointer operations — nanoarrow_pointer_is_valid"><meta name="description" content="The nanoarrow_schema,
	nanoarrow_array,
	and nanoarrow_array_stream classes are
	represented in R as external pointers (EXTPTRSXP). When these objects
	go out of scope (i.e., when they are garbage collected or shortly
	thereafter), the underlying object's release() callback is called if
	the underlying pointer is non-null and if the release() callback is
	non-null."><meta property="og:description" content="The nanoarrow_schema,
	nanoarrow_array,
	and nanoarrow_array_stream classes are
	represented in R as external pointers (EXTPTRSXP). When these objects
	go out of scope (i.e., when they are garbage collected or shortly
	thereafter), the underlying object's release() callback is called if
	the underlying pointer is non-null and if the release() callback is
	non-null."></head><body>
	<a href="#main" class="visually-hidden-focusable">Skip to contents</a>


	<nav class="navbar navbar-expand-lg fixed-top bg-light" data-bs-theme="light" aria-label="Site navigation"><div class="container">

	<a class="navbar-brand me-2" href="../index.html">nanoarrow</a>

	<small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">0.5.0.9000</small>


	<button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
	<span class="navbar-toggler-icon"></span>
	</button>

	<div id="navbar" class="collapse navbar-collapse ms-3">
	<ul class="navbar-nav me-auto"><li class="active nav-item"><a class="nav-link" href="../reference/index.html">Reference</a></li>
	<li class="nav-item"><a class="nav-link" href="../news/index.html">Changelog</a></li>
	</ul><ul class="navbar-nav"><li class="nav-item"><form class="form-inline" role="search">
	<input class="form-control" type="search" name="search-input" id="search-input" autocomplete="off" aria-label="Search site" placeholder="Search for" data-search-index="../search.json"></form></li>
	<li class="nav-item"><a class="external-link nav-link" href="https://github.com/apache/arrow-nanoarrow/" aria-label="GitHub"><span class="fa fab fa-github fa-lg"></span></a></li>
	</ul></div>


	</div>
	</nav><div class="container template-reference-topic">
	<div class="row">
	<main id="main" class="col-md-9"><div class="page-header">

	<h1>Danger zone: low-level pointer operations</h1>
	<small class="dont-index">Source: <a href="https://github.com/apache/arrow-nanoarrow/blob/main/r/R/pointers.R" class="external-link"><code>R/pointers.R</code></a></small>
	<div class="d-none name"><code>nanoarrow_pointer_is_valid.Rd</code></div>
	</div>

	<div class="ref-description section level2">
	<p>The <a href="as_nanoarrow_schema.html">nanoarrow_schema</a>,
	<a href="as_nanoarrow_array.html">nanoarrow_array</a>,
	and <a href="as_nanoarrow_array_stream.html">nanoarrow_array_stream</a> classes are
	represented in R as external pointers (<code>EXTPTRSXP</code>). When these objects
	go out of scope (i.e., when they are garbage collected or shortly
	thereafter), the underlying object's <code>release()</code> callback is called if
	the underlying pointer is non-null and if the <code>release()</code> callback is
	non-null.</p>
	</div>

	<div class="section level2">
	<h2 id="ref-usage">Usage<a class="anchor" aria-label="anchor" href="#ref-usage"></a></h2>
	<div class="sourceCode"><pre class="sourceCode r"><code><span><span class="fu">nanoarrow_pointer_is_valid</span><span class="op">(</span><span class="va">ptr</span><span class="op">)</span></span>
	<span></span>
	<span><span class="fu">nanoarrow_pointer_addr_dbl</span><span class="op">(</span><span class="va">ptr</span><span class="op">)</span></span>
	<span></span>
	<span><span class="fu">nanoarrow_pointer_addr_chr</span><span class="op">(</span><span class="va">ptr</span><span class="op">)</span></span>
	<span></span>
	<span><span class="fu">nanoarrow_pointer_addr_pretty</span><span class="op">(</span><span class="va">ptr</span><span class="op">)</span></span>
	<span></span>
	<span><span class="fu">nanoarrow_pointer_release</span><span class="op">(</span><span class="va">ptr</span><span class="op">)</span></span>
	<span></span>
	<span><span class="fu">nanoarrow_pointer_move</span><span class="op">(</span><span class="va">ptr_src</span>, <span class="va">ptr_dst</span><span class="op">)</span></span>
	<span></span>
	<span><span class="fu">nanoarrow_pointer_export</span><span class="op">(</span><span class="va">ptr_src</span>, <span class="va">ptr_dst</span><span class="op">)</span></span>
	<span></span>
	<span><span class="fu">nanoarrow_allocate_schema</span><span class="op">(</span><span class="op">)</span></span>
	<span></span>
	<span><span class="fu">nanoarrow_allocate_array</span><span class="op">(</span><span class="op">)</span></span>
	<span></span>
	<span><span class="fu">nanoarrow_allocate_array_stream</span><span class="op">(</span><span class="op">)</span></span>
	<span></span>
	<span><span class="fu">nanoarrow_pointer_set_protected</span><span class="op">(</span><span class="va">ptr_src</span>, <span class="va">protected</span><span class="op">)</span></span></code></pre></div>
	</div>

	<div class="section level2">
	<h2 id="arguments">Arguments<a class="anchor" aria-label="anchor" href="#arguments"></a></h2>


	<dl><dt id="arg-ptr-ptr-src-ptr-dst">ptr, ptr_src, ptr_dst<a class="anchor" aria-label="anchor" href="#arg-ptr-ptr-src-ptr-dst"></a></dt>
	<dd><p>An external pointer to a <code>struct ArrowSchema</code>,
	<code>struct ArrowArray</code>, or <code>struct ArrowArrayStream</code>.</p></dd>


	<dt id="arg-protected">protected<a class="anchor" aria-label="anchor" href="#arg-protected"></a></dt>
	<dd><p>An object whose scope must outlive that of <code>ptr</code>. This is
	useful for array streams since at least two specifications involving the
	array stream specify that the stream is only valid for the lifecycle of
	another object (e.g., an AdbcStatement or OGRDataset).</p></dd>

	</dl></div>
	<div class="section level2">
	<h2 id="value">Value<a class="anchor" aria-label="anchor" href="#value"></a></h2>

	<ul><li><p><code>nanoarrow_pointer_is_valid()</code> returns TRUE if the pointer is non-null
	and has a non-null release callback.</p></li>
	<li><p><code>nanoarrow_pointer_addr_dbl()</code> and <code>nanoarrow_pointer_addr_chr()</code> return
	pointer representations that may be helpful to facilitate moving or
	exporting nanoarrow objects to other libraries.</p></li>
	<li><p><code>nanoarrow_pointer_addr_pretty()</code> gives a pointer representation suitable
	for printing or error messages.</p></li>
	<li><p><code>nanoarrow_pointer_release()</code> returns <code>ptr</code>, invisibly.</p></li>
	<li><p><code>nanoarrow_pointer_move()</code> and <code>nanoarrow_pointer_export()</code> reeturn
	<code>ptr_dst</code>, invisibly.</p></li>
	<li><p><code>nanoarrow_allocate_array()</code>, <code>nanoarrow_allocate_schema()</code>, and
	<code>nanoarrow_allocate_array_stream()</code> return an
	<a href="as_nanoarrow_array.html">array</a>, a <a href="as_nanoarrow_schema.html">schema</a>, and an
	<a href="as_nanoarrow_array_stream.html">array stream</a>, respectively.</p></li>
	</ul></div>
	<div class="section level2">
	<h2 id="details">Details<a class="anchor" aria-label="anchor" href="#details"></a></h2>
	<p>When interacting with other C Data Interface implementations, it is
	important to keep in mind that the R object wrapping these pointers is
	always passed by reference (because it is an external pointer) and may
	be referred to by another R object (e.g., an element in a <code><a href="https://rdrr.io/r/base/list.html" class="external-link">list()</a></code> or as a
	variable assigned in a user's environment). When importing a schema,
	array, or array stream into nanoarrow this is not a problem: the R object
	takes ownership of the lifecycle and memory is released when the R
	object is garbage collected. In this case, one can use
	<code>nanoarrow_pointer_move()</code> where <code>ptr_dst</code> was created using
	<code>nanoarrow_allocate_*()</code>.</p>
	<p>The case of exporting is more complicated and as such has a dedicated
	function, <code>nanoarrow_pointer_export()</code>, that implements different logic
	schemas, arrays, and array streams:</p><ul><li><p>Schema objects are (deep) copied such that a fresh copy of the schema
	is exported and made the responsibility of some other C data interface
	implementation.</p></li>
	<li><p>Array objects are exported as a shell around the original array that
	preserves a reference to the R object. This ensures that the buffers
	and children pointed to by the array are not copied and that any references
	to the original array are not invalidated.</p></li>
	<li><p>Array stream objects are moved: the responsibility for the object is
	transferred to the other C data interface implementation and any
	references to the original R object are invalidated. Because these
	objects are mutable, this is typically what you want (i.e., you should
	not be pulling arrays from a stream accidentally from two places).</p></li>
	</ul><p>If you know the lifecycle of your object (i.e., you created the R object
	yourself and never passed references to it elsewhere), you can slightly
	more efficiently call <code>nanoarrow_pointer_move()</code> for all three pointer
	types.</p>
	</div>

	</main><aside class="col-md-3"><nav id="toc" aria-label="Table of contents"><h2>On this page</h2>
	</nav></aside></div>


	<footer><div class="pkgdown-footer-left">
	<p>Developed by Dewey Dunnington, Apache Arrow.</p>
	</div>

	<div class="pkgdown-footer-right">
	<p>Site built with <a href="https://pkgdown.r-lib.org/" class="external-link">pkgdown</a> 2.1.0.</p>
	</div>

	</footer></div>





	</body></html>