blob: ae6aa660abac2199e988807ee820aeb753024e80 [file] [log] [blame]
<!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>Modify nanoarrow arrays — nanoarrow_array_init • 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="Modify nanoarrow arrays — nanoarrow_array_init"><meta name="description" content="Create a new array or from an existing array, modify one or more parameters.
When importing an array from elsewhere, nanoarrow_array_set_schema() is
useful to attach the data type information to the array (without this
information there is little that nanoarrow can do with the array since its
content cannot be otherwise interpreted). nanoarrow_array_modify() can
create a shallow copy and modify various parameters to create a new array,
including setting children and buffers recursively. These functions power the
$&amp;lt;- operator, which can modify one parameter at a time."><meta property="og:description" content="Create a new array or from an existing array, modify one or more parameters.
When importing an array from elsewhere, nanoarrow_array_set_schema() is
useful to attach the data type information to the array (without this
information there is little that nanoarrow can do with the array since its
content cannot be otherwise interpreted). nanoarrow_array_modify() can
create a shallow copy and modify various parameters to create a new array,
including setting children and buffers recursively. These functions power the
$&amp;lt;- operator, which can modify one parameter at a time."></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>Modify nanoarrow arrays</h1>
<small class="dont-index">Source: <a href="https://github.com/apache/arrow-nanoarrow/blob/main/r/R/array.R" class="external-link"><code>R/array.R</code></a></small>
<div class="d-none name"><code>nanoarrow_array_init.Rd</code></div>
</div>
<div class="ref-description section level2">
<p>Create a new array or from an existing array, modify one or more parameters.
When importing an array from elsewhere, <code>nanoarrow_array_set_schema()</code> is
useful to attach the data type information to the array (without this
information there is little that nanoarrow can do with the array since its
content cannot be otherwise interpreted). <code>nanoarrow_array_modify()</code> can
create a shallow copy and modify various parameters to create a new array,
including setting children and buffers recursively. These functions power the
<code>$&lt;-</code> operator, which can modify one parameter at a time.</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_array_init</span><span class="op">(</span><span class="va">schema</span><span class="op">)</span></span>
<span></span>
<span><span class="fu">nanoarrow_array_set_schema</span><span class="op">(</span><span class="va">array</span>, <span class="va">schema</span>, validate <span class="op">=</span> <span class="cn">TRUE</span><span class="op">)</span></span>
<span></span>
<span><span class="fu">nanoarrow_array_modify</span><span class="op">(</span><span class="va">array</span>, <span class="va">new_values</span>, validate <span class="op">=</span> <span class="cn">TRUE</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-schema">schema<a class="anchor" aria-label="anchor" href="#arg-schema"></a></dt>
<dd><p>A <a href="as_nanoarrow_schema.html">nanoarrow_schema</a> to attach to this
<code>array</code>.</p></dd>
<dt id="arg-array">array<a class="anchor" aria-label="anchor" href="#arg-array"></a></dt>
<dd><p>A <a href="as_nanoarrow_array.html">nanoarrow_array</a>.</p></dd>
<dt id="arg-validate">validate<a class="anchor" aria-label="anchor" href="#arg-validate"></a></dt>
<dd><p>Use <code>FALSE</code> to skip validation. Skipping validation may
result in creating an array that will crash R.</p></dd>
<dt id="arg-new-values">new_values<a class="anchor" aria-label="anchor" href="#arg-new-values"></a></dt>
<dd><p>A named <code><a href="https://rdrr.io/r/base/list.html" class="external-link">list()</a></code> of values to replace.</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_array_init()</code> returns a possibly invalid but initialized
array with a given <code>schema</code>.</p></li>
<li><p><code>nanoarrow_array_set_schema()</code> returns <code>array</code>, invisibly. Note that
<code>array</code> is modified in place by reference.</p></li>
<li><p><code>nanoarrow_array_modify()</code> returns a shallow copy of <code>array</code> with the
modified parameters such that the original array remains valid.</p></li>
</ul></div>
<div class="section level2">
<h2 id="ref-examples">Examples<a class="anchor" aria-label="anchor" href="#ref-examples"></a></h2>
<div class="sourceCode"><pre class="sourceCode r"><code><span class="r-in"><span><span class="fu">nanoarrow_array_init</span><span class="op">(</span><span class="fu"><a href="na_type.html">na_string</a></span><span class="op">(</span><span class="op">)</span><span class="op">)</span></span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span> &lt;nanoarrow_array string[0]&gt;</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> $ length : int 0</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> $ null_count: int 0</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> $ offset : int 0</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> $ buffers :List of 3</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> ..$ :&lt;nanoarrow_buffer validity&lt;bool&gt;[0][0 b]&gt; ``</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> ..$ :&lt;nanoarrow_buffer data_offset&lt;int32&gt;[0][0 b]&gt; ``</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> ..$ :&lt;nanoarrow_buffer data&lt;string&gt;[0 b]&gt; ``</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> $ dictionary: NULL</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> $ children : list()</span>
<span class="r-in"><span></span></span>
<span class="r-in"><span><span class="co"># Modify an array using $ and &lt;-</span></span></span>
<span class="r-in"><span><span class="va">array</span> <span class="op">&lt;-</span> <span class="fu"><a href="as_nanoarrow_array.html">as_nanoarrow_array</a></span><span class="op">(</span><span class="fl">1</span><span class="op">:</span><span class="fl">5</span><span class="op">)</span></span></span>
<span class="r-in"><span><span class="va">array</span><span class="op">$</span><span class="va">length</span> <span class="op">&lt;-</span> <span class="fl">4</span></span></span>
<span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/base/vector.html" class="external-link">as.vector</a></span><span class="op">(</span><span class="va">array</span><span class="op">)</span></span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span> [1] 1 2 3 4</span>
<span class="r-in"><span></span></span>
<span class="r-in"><span><span class="co"># Modify potentially more than one component at a time</span></span></span>
<span class="r-in"><span><span class="va">array</span> <span class="op">&lt;-</span> <span class="fu"><a href="as_nanoarrow_array.html">as_nanoarrow_array</a></span><span class="op">(</span><span class="fl">1</span><span class="op">:</span><span class="fl">5</span><span class="op">)</span></span></span>
<span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/base/vector.html" class="external-link">as.vector</a></span><span class="op">(</span><span class="fu">nanoarrow_array_modify</span><span class="op">(</span><span class="va">array</span>, <span class="fu"><a href="https://rdrr.io/r/base/list.html" class="external-link">list</a></span><span class="op">(</span>length <span class="op">=</span> <span class="fl">4</span><span class="op">)</span><span class="op">)</span><span class="op">)</span></span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span> [1] 1 2 3 4</span>
<span class="r-in"><span></span></span>
<span class="r-in"><span><span class="co"># Attach a schema to an array</span></span></span>
<span class="r-in"><span><span class="va">array</span> <span class="op">&lt;-</span> <span class="fu"><a href="as_nanoarrow_array.html">as_nanoarrow_array</a></span><span class="op">(</span><span class="op">-</span><span class="fl">1L</span><span class="op">)</span></span></span>
<span class="r-in"><span><span class="fu">nanoarrow_array_set_schema</span><span class="op">(</span><span class="va">array</span>, <span class="fu"><a href="na_type.html">na_uint32</a></span><span class="op">(</span><span class="op">)</span><span class="op">)</span></span></span>
<span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/base/vector.html" class="external-link">as.vector</a></span><span class="op">(</span><span class="va">array</span><span class="op">)</span></span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span> [1] 4294967295</span>
<span class="r-in"><span></span></span>
</code></pre></div>
</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>