| |
| |
| <!DOCTYPE html> |
| |
| |
| <html lang="en" data-content_root="" > |
| |
| <head> |
| <meta charset="utf-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" /> |
| |
| <title>Arrays — Apache Arrow v17.0.0.dev52</title> |
| |
| |
| |
| <script data-cfasync="false"> |
| document.documentElement.dataset.mode = localStorage.getItem("mode") || ""; |
| document.documentElement.dataset.theme = localStorage.getItem("theme") || "light"; |
| </script> |
| |
| <!-- Loaded before other Sphinx assets --> |
| <link href="../_static/styles/theme.css?digest=8d27b9dea8ad943066ae" rel="stylesheet" /> |
| <link href="../_static/styles/bootstrap.css?digest=8d27b9dea8ad943066ae" rel="stylesheet" /> |
| <link href="../_static/styles/pydata-sphinx-theme.css?digest=8d27b9dea8ad943066ae" rel="stylesheet" /> |
| |
| |
| <link href="../_static/vendor/fontawesome/6.5.1/css/all.min.css?digest=8d27b9dea8ad943066ae" rel="stylesheet" /> |
| <link rel="preload" as="font" type="font/woff2" crossorigin href="../_static/vendor/fontawesome/6.5.1/webfonts/fa-solid-900.woff2" /> |
| <link rel="preload" as="font" type="font/woff2" crossorigin href="../_static/vendor/fontawesome/6.5.1/webfonts/fa-brands-400.woff2" /> |
| <link rel="preload" as="font" type="font/woff2" crossorigin href="../_static/vendor/fontawesome/6.5.1/webfonts/fa-regular-400.woff2" /> |
| |
| <link rel="stylesheet" type="text/css" href="../_static/pygments.css" /> |
| <link rel="stylesheet" type="text/css" href="../_static/copybutton.css" /> |
| <link rel="stylesheet" type="text/css" href="../_static/design-style.1e8bd061cd6da7fc9cf755528e8ffc24.min.css" /> |
| <link rel="stylesheet" type="text/css" href="../_static/theme_overrides.css" /> |
| |
| <!-- Pre-loaded scripts that we'll load fully later --> |
| <link rel="preload" as="script" href="../_static/scripts/bootstrap.js?digest=8d27b9dea8ad943066ae" /> |
| <link rel="preload" as="script" href="../_static/scripts/pydata-sphinx-theme.js?digest=8d27b9dea8ad943066ae" /> |
| <script src="../_static/vendor/fontawesome/6.5.1/js/all.min.js?digest=8d27b9dea8ad943066ae"></script> |
| |
| <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> |
| <script src="../_static/doctools.js"></script> |
| <script src="../_static/sphinx_highlight.js"></script> |
| <script src="../_static/clipboard.min.js"></script> |
| <script src="../_static/copybutton.js"></script> |
| <script src="../_static/design-tabs.js"></script> |
| <script>DOCUMENTATION_OPTIONS.pagename = 'cpp/arrays';</script> |
| <script> |
| DOCUMENTATION_OPTIONS.theme_version = '0.15.2'; |
| DOCUMENTATION_OPTIONS.theme_switcher_json_url = '/docs/_static/versions.json'; |
| DOCUMENTATION_OPTIONS.theme_switcher_version_match = 'dev/'; |
| DOCUMENTATION_OPTIONS.show_version_warning_banner = true; |
| </script> |
| <link rel="canonical" href="https://arrow.apache.org/docs/cpp/arrays.html" /> |
| <link rel="icon" href="../_static/favicon.ico"/> |
| <link rel="index" title="Index" href="../genindex.html" /> |
| <link rel="search" title="Search" href="../search.html" /> |
| <link rel="next" title="Data Types" href="datatypes.html" /> |
| <link rel="prev" title="Memory Management" href="memory.html" /> |
| |
| <meta name="viewport" content="width=device-width, initial-scale=1"/> |
| <meta name="docsearch:language" content="en"/> |
| |
| <!-- Matomo --> |
| <script> |
| var _paq = window._paq = window._paq || []; |
| /* tracker methods like "setCustomDimension" should be called before "trackPageView" */ |
| /* We explicitly disable cookie tracking to avoid privacy issues */ |
| _paq.push(['disableCookies']); |
| _paq.push(['trackPageView']); |
| _paq.push(['enableLinkTracking']); |
| (function() { |
| var u="https://analytics.apache.org/"; |
| _paq.push(['setTrackerUrl', u+'matomo.php']); |
| _paq.push(['setSiteId', '20']); |
| var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0]; |
| g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s); |
| })(); |
| </script> |
| <!-- End Matomo Code --> |
| |
| </head> |
| |
| |
| <body data-bs-spy="scroll" data-bs-target=".bd-toc-nav" data-offset="180" data-bs-root-margin="0px 0px -60%" data-default-mode=""> |
| |
| |
| |
| <a id="pst-skip-link" class="skip-link" href="#main-content">Skip to main content</a> |
| |
| <div id="pst-scroll-pixel-helper"></div> |
| |
| <button type="button" class="btn rounded-pill" id="pst-back-to-top"> |
| <i class="fa-solid fa-arrow-up"></i> |
| Back to top |
| </button> |
| |
| |
| <input type="checkbox" |
| class="sidebar-toggle" |
| name="__primary" |
| id="__primary"/> |
| <label class="overlay overlay-primary" for="__primary"></label> |
| |
| <input type="checkbox" |
| class="sidebar-toggle" |
| name="__secondary" |
| id="__secondary"/> |
| <label class="overlay overlay-secondary" for="__secondary"></label> |
| |
| <div class="search-button__wrapper"> |
| <div class="search-button__overlay"></div> |
| <div class="search-button__search-container"> |
| <form class="bd-search d-flex align-items-center" |
| action="../search.html" |
| method="get"> |
| <i class="fa-solid fa-magnifying-glass"></i> |
| <input type="search" |
| class="form-control" |
| name="q" |
| id="search-input" |
| placeholder="Search the docs ..." |
| aria-label="Search the docs ..." |
| autocomplete="off" |
| autocorrect="off" |
| autocapitalize="off" |
| spellcheck="false"/> |
| <span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd>K</kbd></span> |
| </form></div> |
| </div> |
| |
| <header class="bd-header navbar navbar-expand-lg bd-navbar"> |
| <div class="bd-header__inner bd-page-width"> |
| <label class="sidebar-toggle primary-toggle" for="__primary"> |
| <span class="fa-solid fa-bars"></span> |
| </label> |
| |
| |
| <div class="col-lg-3 navbar-header-items__start"> |
| |
| <div class="navbar-item"> |
| |
| |
| |
| <a class="navbar-brand logo" href="../index.html"> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <img src="../_static/arrow.png" class="logo__image only-light" alt="Apache Arrow v17.0.0.dev52 - Home"/> |
| <script>document.write(`<img src="../_static/arrow-dark.png" class="logo__image only-dark" alt="Apache Arrow v17.0.0.dev52 - Home"/>`);</script> |
| |
| |
| </a></div> |
| |
| </div> |
| |
| <div class="col-lg-9 navbar-header-items"> |
| |
| <div class="me-auto navbar-header-items__center"> |
| |
| <div class="navbar-item"> |
| <nav class="navbar-nav"> |
| <ul class="bd-navbar-elements navbar-nav"> |
| |
| <li class="nav-item"> |
| <a class="nav-link nav-internal" href="../format/index.html"> |
| Specifications |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link nav-internal" href="../developers/index.html"> |
| Development |
| </a> |
| </li> |
| |
| <li class="nav-item dropdown"> |
| <button class="btn dropdown-toggle nav-item" type="button" data-bs-toggle="dropdown" aria-expanded="false" aria-controls="pst-nav-more-links"> |
| Implementations |
| </button> |
| <ul id="pst-nav-more-links" class="dropdown-menu"> |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../c_glib/index.html"> |
| C/GLib |
| </a> |
| </li> |
| |
| |
| <li class="nav-item current active"> |
| <a class="nav-link dropdown-item nav-internal" href="index.html"> |
| C++ |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/csharp/README.md"> |
| C# |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://pkg.go.dev/github.com/apache/arrow/go/v17"> |
| Go |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../java/index.html"> |
| Java |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../js/index.html"> |
| JavaScript |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/julia/"> |
| Julia |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/matlab/README.md"> |
| MATLAB |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/nanoarrow/"> |
| nanoarrow |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../python/index.html"> |
| Python |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../r/index.html"> |
| R |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/ruby/README.md"> |
| Ruby |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://docs.rs/crate/arrow/"> |
| Rust |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../status.html"> |
| Implementation Status |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/cpp/"> |
| C++ cookbook |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/java/"> |
| Java cookbook |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/py/"> |
| Python cookbook |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/r/"> |
| R cookbook |
| </a> |
| </li> |
| |
| </ul> |
| </li> |
| |
| </ul> |
| </nav></div> |
| |
| </div> |
| |
| |
| <div class="navbar-header-items__end"> |
| |
| <div class="navbar-item navbar-persistent--container"> |
| |
| |
| <script> |
| document.write(` |
| <button class="btn navbar-btn search-button-field search-button__button" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip"> |
| <i class="fa-solid fa-magnifying-glass"></i> |
| <span class="search-button__default-text">Search</span> |
| <span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span> |
| </button> |
| `); |
| </script> |
| </div> |
| |
| |
| <div class="navbar-item"> |
| <script> |
| document.write(` |
| <div class="version-switcher__container dropdown"> |
| <button id="pst-version-switcher-button-2" |
| type="button" |
| class="version-switcher__button btn btn-sm navbar-btn dropdown-toggle" |
| data-bs-toggle="dropdown" |
| aria-haspopup="listbox" |
| aria-controls="pst-version-switcher-list-2" |
| aria-label="Version switcher list" |
| > |
| Choose version <!-- this text may get changed later by javascript --> |
| <span class="caret"></span> |
| </button> |
| <div id="pst-version-switcher-list-2" |
| class="version-switcher__menu dropdown-menu list-group-flush py-0" |
| role="listbox" aria-labelledby="pst-version-switcher-button-2"> |
| <!-- dropdown will be populated by javascript on page load --> |
| </div> |
| </div> |
| `); |
| </script></div> |
| |
| <div class="navbar-item"> |
| |
| <script> |
| document.write(` |
| <button class="btn btn-sm navbar-btn theme-switch-button" title="light/dark" aria-label="light/dark" data-bs-placement="bottom" data-bs-toggle="tooltip"> |
| <span class="theme-switch nav-link" data-mode="light"><i class="fa-solid fa-sun fa-lg"></i></span> |
| <span class="theme-switch nav-link" data-mode="dark"><i class="fa-solid fa-moon fa-lg"></i></span> |
| <span class="theme-switch nav-link" data-mode="auto"><i class="fa-solid fa-circle-half-stroke fa-lg"></i></span> |
| </button> |
| `); |
| </script></div> |
| |
| <div class="navbar-item"><ul class="navbar-icon-links navbar-nav" |
| aria-label="Icon Links"> |
| <li class="nav-item"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="https://github.com/apache/arrow" title="GitHub" class="nav-link" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><span><i class="fa-brands fa-square-github fa-lg" aria-hidden="true"></i></span> |
| <span class="sr-only">GitHub</span></a> |
| </li> |
| <li class="nav-item"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="https://twitter.com/ApacheArrow" title="X" class="nav-link" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><span><i class="fa-brands fa-square-x-twitter fa-lg" aria-hidden="true"></i></span> |
| <span class="sr-only">X</span></a> |
| </li> |
| </ul></div> |
| |
| </div> |
| |
| </div> |
| |
| |
| <div class="navbar-persistent--mobile"> |
| |
| <script> |
| document.write(` |
| <button class="btn navbar-btn search-button-field search-button__button" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip"> |
| <i class="fa-solid fa-magnifying-glass"></i> |
| <span class="search-button__default-text">Search</span> |
| <span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span> |
| </button> |
| `); |
| </script> |
| </div> |
| |
| |
| |
| <label class="sidebar-toggle secondary-toggle" for="__secondary" tabindex="0"> |
| <span class="fa-solid fa-outdent"></span> |
| </label> |
| |
| </div> |
| |
| </header> |
| |
| |
| <div class="bd-container"> |
| <div class="bd-container__inner bd-page-width"> |
| |
| |
| |
| <div class="bd-sidebar-primary bd-sidebar"> |
| |
| |
| |
| <div class="sidebar-header-items sidebar-primary__section"> |
| |
| |
| <div class="sidebar-header-items__center"> |
| |
| <div class="navbar-item"> |
| <nav class="navbar-nav"> |
| <ul class="bd-navbar-elements navbar-nav"> |
| |
| <li class="nav-item"> |
| <a class="nav-link nav-internal" href="../format/index.html"> |
| Specifications |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link nav-internal" href="../developers/index.html"> |
| Development |
| </a> |
| </li> |
| |
| <li class="nav-item dropdown"> |
| <button class="btn dropdown-toggle nav-item" type="button" data-bs-toggle="dropdown" aria-expanded="false" aria-controls="pst-nav-more-links-2"> |
| Implementations |
| </button> |
| <ul id="pst-nav-more-links-2" class="dropdown-menu"> |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../c_glib/index.html"> |
| C/GLib |
| </a> |
| </li> |
| |
| |
| <li class="nav-item current active"> |
| <a class="nav-link dropdown-item nav-internal" href="index.html"> |
| C++ |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/csharp/README.md"> |
| C# |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://pkg.go.dev/github.com/apache/arrow/go/v17"> |
| Go |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../java/index.html"> |
| Java |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../js/index.html"> |
| JavaScript |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/julia/"> |
| Julia |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/matlab/README.md"> |
| MATLAB |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/nanoarrow/"> |
| nanoarrow |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../python/index.html"> |
| Python |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../r/index.html"> |
| R |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/ruby/README.md"> |
| Ruby |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://docs.rs/crate/arrow/"> |
| Rust |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../status.html"> |
| Implementation Status |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/cpp/"> |
| C++ cookbook |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/java/"> |
| Java cookbook |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/py/"> |
| Python cookbook |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/r/"> |
| R cookbook |
| </a> |
| </li> |
| |
| </ul> |
| </li> |
| |
| </ul> |
| </nav></div> |
| |
| </div> |
| |
| |
| |
| <div class="sidebar-header-items__end"> |
| |
| <div class="navbar-item"> |
| <script> |
| document.write(` |
| <div class="version-switcher__container dropdown"> |
| <button id="pst-version-switcher-button-3" |
| type="button" |
| class="version-switcher__button btn btn-sm navbar-btn dropdown-toggle" |
| data-bs-toggle="dropdown" |
| aria-haspopup="listbox" |
| aria-controls="pst-version-switcher-list-3" |
| aria-label="Version switcher list" |
| > |
| Choose version <!-- this text may get changed later by javascript --> |
| <span class="caret"></span> |
| </button> |
| <div id="pst-version-switcher-list-3" |
| class="version-switcher__menu dropdown-menu list-group-flush py-0" |
| role="listbox" aria-labelledby="pst-version-switcher-button-3"> |
| <!-- dropdown will be populated by javascript on page load --> |
| </div> |
| </div> |
| `); |
| </script></div> |
| |
| <div class="navbar-item"> |
| |
| <script> |
| document.write(` |
| <button class="btn btn-sm navbar-btn theme-switch-button" title="light/dark" aria-label="light/dark" data-bs-placement="bottom" data-bs-toggle="tooltip"> |
| <span class="theme-switch nav-link" data-mode="light"><i class="fa-solid fa-sun fa-lg"></i></span> |
| <span class="theme-switch nav-link" data-mode="dark"><i class="fa-solid fa-moon fa-lg"></i></span> |
| <span class="theme-switch nav-link" data-mode="auto"><i class="fa-solid fa-circle-half-stroke fa-lg"></i></span> |
| </button> |
| `); |
| </script></div> |
| |
| <div class="navbar-item"><ul class="navbar-icon-links navbar-nav" |
| aria-label="Icon Links"> |
| <li class="nav-item"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="https://github.com/apache/arrow" title="GitHub" class="nav-link" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><span><i class="fa-brands fa-square-github fa-lg" aria-hidden="true"></i></span> |
| <span class="sr-only">GitHub</span></a> |
| </li> |
| <li class="nav-item"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="https://twitter.com/ApacheArrow" title="X" class="nav-link" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><span><i class="fa-brands fa-square-x-twitter fa-lg" aria-hidden="true"></i></span> |
| <span class="sr-only">X</span></a> |
| </li> |
| </ul></div> |
| |
| </div> |
| |
| </div> |
| |
| <div class="sidebar-primary-items__start sidebar-primary__section"> |
| <div class="sidebar-primary-item"> |
| <nav class="bd-docs-nav bd-links" |
| aria-label="Section Navigation"> |
| <p class="bd-links__title" role="heading" aria-level="1">Section Navigation</p> |
| <div class="bd-toc-item navbar-nav"><ul class="current nav bd-sidenav"> |
| <li class="toctree-l1 has-children"><a class="reference internal" href="getting_started.html">Getting Started</a><input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-1"><i class="fa-solid fa-chevron-down"></i></label><ul> |
| <li class="toctree-l2"><a class="reference internal" href="build_system.html">Using Arrow C++ in your own project</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="conventions.html">Conventions</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="tutorials/basic_arrow.html">Basic Arrow Data Structures</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="tutorials/io_tutorial.html">Arrow File I/O</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="tutorials/compute_tutorial.html">Arrow Compute</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="tutorials/datasets_tutorial.html">Arrow Datasets</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l1 current active has-children"><a class="reference internal" href="user_guide.html">User Guide</a><input checked="" class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-2"><i class="fa-solid fa-chevron-down"></i></label><ul class="current"> |
| <li class="toctree-l2"><a class="reference internal" href="overview.html">High-Level Overview</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="memory.html">Memory Management</a></li> |
| <li class="toctree-l2 current active"><a class="current reference internal" href="#">Arrays</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="datatypes.html">Data Types</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="tables.html">Tabular Data</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="compute.html">Compute Functions</a></li> |
| <li class="toctree-l2 has-children"><a class="reference internal" href="gandiva.html">The Gandiva Expression Compiler</a><input class="toctree-checkbox" id="toctree-checkbox-3" name="toctree-checkbox-3" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-3"><i class="fa-solid fa-chevron-down"></i></label><ul> |
| <li class="toctree-l3"><a class="reference internal" href="gandiva/expr_projector_filter.html">Gandiva Expression, Projector, and Filter</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="gandiva/external_func.html">Gandiva External Functions Development Guide</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l2 has-children"><a class="reference internal" href="streaming_execution.html">Acero: A C++ streaming execution engine</a><input class="toctree-checkbox" id="toctree-checkbox-4" name="toctree-checkbox-4" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-4"><i class="fa-solid fa-chevron-down"></i></label><ul> |
| <li class="toctree-l3"><a class="reference internal" href="acero/overview.html">Acero Overview</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="acero/user_guide.html">Acero User’s Guide</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="acero/substrait.html">Using Acero with Substrait</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="acero/developer_guide.html">Developer’s Guide</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l2"><a class="reference internal" href="io.html">Input / output and filesystems</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="ipc.html">Reading and writing the Arrow IPC format</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="orc.html">Reading and Writing ORC files</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="parquet.html">Reading and writing Parquet files</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="csv.html">Reading and Writing CSV files</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="json.html">Reading JSON files</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="dataset.html">Tabular Datasets</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="flight.html">Arrow Flight RPC</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="gdb.html">Debugging code using Arrow</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="threading.html">Thread Management</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="opentelemetry.html">OpenTelemetry</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="env_vars.html">Environment Variables</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l1 has-children"><a class="reference internal" href="examples/index.html">Examples</a><input class="toctree-checkbox" id="toctree-checkbox-5" name="toctree-checkbox-5" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-5"><i class="fa-solid fa-chevron-down"></i></label><ul> |
| <li class="toctree-l2"><a class="reference internal" href="examples/cmake_minimal_build.html">Minimal build using CMake</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="examples/compute_and_write_example.html">Compute and Write CSV Example</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="examples/dataset_documentation_example.html">Arrow Datasets example</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="examples/dataset_skyhook_scan_example.html">Arrow Skyhook example</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="examples/row_columnar_conversion.html">Row to columnar conversion</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="examples/tuple_range_conversion.html">std::tuple-like ranges to Arrow</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="examples/converting_recordbatch_to_tensor.html">Converting RecordBatch to Tensor</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l1 has-children"><a class="reference internal" href="api.html">API Reference</a><input class="toctree-checkbox" id="toctree-checkbox-6" name="toctree-checkbox-6" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-6"><i class="fa-solid fa-chevron-down"></i></label><ul> |
| <li class="toctree-l2"><a class="reference internal" href="api/support.html">Programming Support</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="api/memory.html">Memory (management)</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="api/thread.html">Thread (management)</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="api/datatype.html">Data Types</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="api/array.html">Arrays</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="api/scalar.html">Scalars</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="api/builder.html">Array Builders</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="api/table.html">Two-dimensional Datasets</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="api/c_abi.html">C Interfaces</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="api/compute.html">Compute Functions</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="api/acero.html">Streaming Execution (Acero)</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="api/gandiva.html">Gandiva Expression Compiler</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="api/tensor.html">Tensors</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="api/utilities.html">Utilities</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="api/async.html">Asynchronous programming</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="api/io.html">Input / output</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="api/ipc.html">Arrow IPC</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="api/formats.html">File Formats</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="api/cuda.html">CUDA support</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="api/flight.html">Arrow Flight RPC</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="api/flightsql.html">Arrow Flight SQL</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="api/filesystem.html">Filesystems</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="api/dataset.html">Dataset</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l1"><a class="reference external" href="https://arrow.apache.org/cookbook/cpp/">C++ cookbook</a></li> |
| </ul> |
| </div> |
| </nav></div> |
| </div> |
| |
| |
| <div class="sidebar-primary-items__end sidebar-primary__section"> |
| </div> |
| |
| <div id="rtd-footer-container"></div> |
| |
| |
| </div> |
| |
| <main id="main-content" class="bd-main"> |
| |
| |
| <div class="bd-content"> |
| <div class="bd-article-container"> |
| |
| <div class="bd-header-article"> |
| <div class="header-article-items header-article__inner"> |
| |
| <div class="header-article-items__start"> |
| |
| <div class="header-article-item"> |
| |
| |
| |
| <nav aria-label="Breadcrumb"> |
| <ul class="bd-breadcrumbs"> |
| |
| <li class="breadcrumb-item breadcrumb-home"> |
| <a href="../index.html" class="nav-link" aria-label="Home"> |
| <i class="fa-solid fa-home"></i> |
| </a> |
| </li> |
| |
| <li class="breadcrumb-item"><a href="index.html" class="nav-link">C++ Implementation</a></li> |
| |
| |
| <li class="breadcrumb-item"><a href="user_guide.html" class="nav-link">User Guide</a></li> |
| |
| <li class="breadcrumb-item active" aria-current="page">Arrays</li> |
| </ul> |
| </nav> |
| </div> |
| |
| </div> |
| |
| |
| </div> |
| </div> |
| |
| |
| |
| |
| <div id="searchbox"></div> |
| <article class="bd-article"> |
| |
| <section id="arrays"> |
| <h1>Arrays<a class="headerlink" href="#arrays" title="Permalink to this heading">#</a></h1> |
| <div class="admonition seealso"> |
| <p class="admonition-title">See also</p> |
| <p><a class="reference internal" href="api/array.html"><span class="doc">Array API reference</span></a></p> |
| </div> |
| <p>The central type in Arrow is the class <a class="reference internal" href="api/array.html#_CPPv4N5arrow5ArrayE" title="arrow::Array"><code class="xref cpp cpp-class docutils literal notranslate"><span class="pre">arrow::Array</span></code></a>. An array |
| represents a known-length sequence of values all having the same type. |
| Internally, those values are represented by one or several buffers, the |
| number and meaning of which depend on the array’s data type, as documented |
| in <a class="reference internal" href="../format/Columnar.html#format-layout"><span class="std std-ref">the Arrow data layout specification</span></a>.</p> |
| <p>Those buffers consist of the value data itself and an optional bitmap buffer |
| that indicates which array entries are null values. The bitmap buffer |
| can be entirely omitted if the array is known to have zero null values.</p> |
| <p>There are concrete subclasses of <a class="reference internal" href="api/array.html#_CPPv4N5arrow5ArrayE" title="arrow::Array"><code class="xref cpp cpp-class docutils literal notranslate"><span class="pre">arrow::Array</span></code></a> for each data type, |
| that help you access individual values of the array.</p> |
| <section id="building-an-array"> |
| <h2>Building an array<a class="headerlink" href="#building-an-array" title="Permalink to this heading">#</a></h2> |
| <section id="available-strategies"> |
| <h3>Available strategies<a class="headerlink" href="#available-strategies" title="Permalink to this heading">#</a></h3> |
| <p>As Arrow objects are immutable, they cannot be populated directly like for |
| example a <code class="docutils literal notranslate"><span class="pre">std::vector</span></code>. Instead, several strategies can be used:</p> |
| <ul> |
| <li><p>if the data already exists in memory with the right layout, you can wrap |
| said memory inside <a class="reference internal" href="api/memory.html#_CPPv4N5arrow6BufferE" title="arrow::Buffer"><code class="xref cpp cpp-class docutils literal notranslate"><span class="pre">arrow::Buffer</span></code></a> instances and then construct |
| a <a class="reference internal" href="api/array.html#_CPPv4N5arrow9ArrayDataE" title="arrow::ArrayData"><code class="xref cpp cpp-class docutils literal notranslate"><span class="pre">arrow::ArrayData</span></code></a> describing the array;</p> |
| <div class="admonition seealso"> |
| <p class="admonition-title">See also</p> |
| <p><a class="reference internal" href="memory.html#cpp-memory-management"><span class="std std-ref">Memory Management</span></a></p> |
| </div> |
| </li> |
| <li><p>otherwise, the <a class="reference internal" href="api/builder.html#_CPPv4N5arrow12ArrayBuilderE" title="arrow::ArrayBuilder"><code class="xref cpp cpp-class docutils literal notranslate"><span class="pre">arrow::ArrayBuilder</span></code></a> base class and its concrete |
| subclasses help building up array data incrementally, without having to |
| deal with details of the Arrow format yourself.</p></li> |
| </ul> |
| </section> |
| <section id="using-arraybuilder-and-its-subclasses"> |
| <h3>Using ArrayBuilder and its subclasses<a class="headerlink" href="#using-arraybuilder-and-its-subclasses" title="Permalink to this heading">#</a></h3> |
| <p>To build an <code class="docutils literal notranslate"><span class="pre">Int64</span></code> Arrow array, we can use the <code class="xref cpp cpp-class docutils literal notranslate"><span class="pre">arrow::Int64Builder</span></code> |
| class. In the following example, we build an array of the range 1 to 8 where |
| the element that should hold the value 4 is nulled:</p> |
| <div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="n">arrow</span><span class="o">::</span><span class="n">Int64Builder</span><span class="w"> </span><span class="n">builder</span><span class="p">;</span> |
| <span class="n">builder</span><span class="p">.</span><span class="n">Append</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span> |
| <span class="n">builder</span><span class="p">.</span><span class="n">Append</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span> |
| <span class="n">builder</span><span class="p">.</span><span class="n">Append</span><span class="p">(</span><span class="mi">3</span><span class="p">);</span> |
| <span class="n">builder</span><span class="p">.</span><span class="n">AppendNull</span><span class="p">();</span> |
| <span class="n">builder</span><span class="p">.</span><span class="n">Append</span><span class="p">(</span><span class="mi">5</span><span class="p">);</span> |
| <span class="n">builder</span><span class="p">.</span><span class="n">Append</span><span class="p">(</span><span class="mi">6</span><span class="p">);</span> |
| <span class="n">builder</span><span class="p">.</span><span class="n">Append</span><span class="p">(</span><span class="mi">7</span><span class="p">);</span> |
| <span class="n">builder</span><span class="p">.</span><span class="n">Append</span><span class="p">(</span><span class="mi">8</span><span class="p">);</span> |
| |
| <span class="k">auto</span><span class="w"> </span><span class="n">maybe_array</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">builder</span><span class="p">.</span><span class="n">Finish</span><span class="p">();</span> |
| <span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="o">!</span><span class="n">maybe_array</span><span class="p">.</span><span class="n">ok</span><span class="p">())</span><span class="w"> </span><span class="p">{</span> |
| <span class="w"> </span><span class="c1">// ... do something on array building failure</span> |
| <span class="p">}</span> |
| <span class="n">std</span><span class="o">::</span><span class="n">shared_ptr</span><span class="o"><</span><span class="n">arrow</span><span class="o">::</span><span class="n">Array</span><span class="o">></span><span class="w"> </span><span class="n">array</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">*</span><span class="n">maybe_array</span><span class="p">;</span> |
| </pre></div> |
| </div> |
| <p>The resulting Array (which can be casted to the concrete <code class="xref cpp cpp-class docutils literal notranslate"><span class="pre">arrow::Int64Array</span></code> |
| subclass if you want to access its values) then consists of two |
| <a class="reference internal" href="api/memory.html#_CPPv4N5arrow6BufferE" title="arrow::Buffer"><code class="xref cpp cpp-class docutils literal notranslate"><span class="pre">arrow::Buffer</span></code></a>s. |
| The first buffer holds the null bitmap, which consists here of a single byte with |
| the bits <code class="docutils literal notranslate"><span class="pre">1|1|1|1|0|1|1|1</span></code>. As we use <a class="reference external" href="https://en.wikipedia.org/wiki/Bit_numbering">least-significant bit (LSB) numbering</a>, |
| this indicates that the fourth entry in the array is null. The second |
| buffer is simply an <code class="docutils literal notranslate"><span class="pre">int64_t</span></code> array containing all the above values. |
| As the fourth entry is null, the value at that position in the buffer is |
| undefined.</p> |
| <p>Here is how you could access the concrete array’s contents:</p> |
| <div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="c1">// Cast the Array to its actual type to access its data</span> |
| <span class="k">auto</span><span class="w"> </span><span class="n">int64_array</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">std</span><span class="o">::</span><span class="n">static_pointer_cast</span><span class="o"><</span><span class="n">arrow</span><span class="o">::</span><span class="n">Int64Array</span><span class="o">></span><span class="p">(</span><span class="n">array</span><span class="p">);</span> |
| |
| <span class="c1">// Get the pointer to the null bitmap</span> |
| <span class="k">const</span><span class="w"> </span><span class="kt">uint8_t</span><span class="o">*</span><span class="w"> </span><span class="n">null_bitmap</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">int64_array</span><span class="o">-></span><span class="n">null_bitmap_data</span><span class="p">();</span> |
| |
| <span class="c1">// Get the pointer to the actual data</span> |
| <span class="k">const</span><span class="w"> </span><span class="kt">int64_t</span><span class="o">*</span><span class="w"> </span><span class="n">data</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">int64_array</span><span class="o">-></span><span class="n">raw_values</span><span class="p">();</span> |
| |
| <span class="c1">// Alternatively, given an array index, query its null bit and value directly</span> |
| <span class="kt">int64_t</span><span class="w"> </span><span class="n">index</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="p">;</span> |
| <span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="o">!</span><span class="n">int64_array</span><span class="o">-></span><span class="n">IsNull</span><span class="p">(</span><span class="n">index</span><span class="p">))</span><span class="w"> </span><span class="p">{</span> |
| <span class="w"> </span><span class="kt">int64_t</span><span class="w"> </span><span class="n">value</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">int64_array</span><span class="o">-></span><span class="n">Value</span><span class="p">(</span><span class="n">index</span><span class="p">);</span> |
| <span class="p">}</span> |
| </pre></div> |
| </div> |
| <div class="admonition note"> |
| <p class="admonition-title">Note</p> |
| <p><code class="xref cpp cpp-class docutils literal notranslate"><span class="pre">arrow::Int64Array</span></code> (respectively <code class="xref cpp cpp-class docutils literal notranslate"><span class="pre">arrow::Int64Builder</span></code>) is |
| just a <code class="docutils literal notranslate"><span class="pre">typedef</span></code>, provided for convenience, of <code class="docutils literal notranslate"><span class="pre">arrow::NumericArray<Int64Type></span></code> |
| (respectively <code class="docutils literal notranslate"><span class="pre">arrow::NumericBuilder<Int64Type></span></code>).</p> |
| </div> |
| </section> |
| <section id="performance"> |
| <h3>Performance<a class="headerlink" href="#performance" title="Permalink to this heading">#</a></h3> |
| <p>While it is possible to build an array value-by-value as in the example above, |
| to attain highest performance it is recommended to use the bulk appending |
| methods (usually named <code class="docutils literal notranslate"><span class="pre">AppendValues</span></code>) in the concrete <a class="reference internal" href="api/builder.html#_CPPv4N5arrow12ArrayBuilderE" title="arrow::ArrayBuilder"><code class="xref cpp cpp-class docutils literal notranslate"><span class="pre">arrow::ArrayBuilder</span></code></a> |
| subclasses.</p> |
| <p>If you know the number of elements in advance, it is also recommended to |
| presize the working area by calling the <a class="reference internal" href="api/builder.html#_CPPv4N5arrow12ArrayBuilder6ResizeE7int64_t" title="arrow::ArrayBuilder::Resize"><code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">Resize()</span></code></a> |
| or <a class="reference internal" href="api/builder.html#_CPPv4N5arrow12ArrayBuilder7ReserveE7int64_t" title="arrow::ArrayBuilder::Reserve"><code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">Reserve()</span></code></a> methods.</p> |
| <p>Here is how one could rewrite the above example to take advantage of those |
| APIs:</p> |
| <div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="n">arrow</span><span class="o">::</span><span class="n">Int64Builder</span><span class="w"> </span><span class="n">builder</span><span class="p">;</span> |
| <span class="c1">// Make place for 8 values in total</span> |
| <span class="n">builder</span><span class="p">.</span><span class="n">Reserve</span><span class="p">(</span><span class="mi">8</span><span class="p">);</span> |
| <span class="c1">// Bulk append the given values (with a null in 4th place as indicated by the</span> |
| <span class="c1">// validity vector)</span> |
| <span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="kt">bool</span><span class="o">></span><span class="w"> </span><span class="n">validity</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="nb">true</span><span class="p">,</span><span class="w"> </span><span class="nb">true</span><span class="p">,</span><span class="w"> </span><span class="nb">true</span><span class="p">,</span><span class="w"> </span><span class="nb">false</span><span class="p">,</span><span class="w"> </span><span class="nb">true</span><span class="p">,</span><span class="w"> </span><span class="nb">true</span><span class="p">,</span><span class="w"> </span><span class="nb">true</span><span class="p">,</span><span class="w"> </span><span class="nb">true</span><span class="p">};</span> |
| <span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="kt">int64_t</span><span class="o">></span><span class="w"> </span><span class="n">values</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="mi">5</span><span class="p">,</span><span class="w"> </span><span class="mi">6</span><span class="p">,</span><span class="w"> </span><span class="mi">7</span><span class="p">,</span><span class="w"> </span><span class="mi">8</span><span class="p">};</span> |
| <span class="n">builder</span><span class="p">.</span><span class="n">AppendValues</span><span class="p">(</span><span class="n">values</span><span class="p">,</span><span class="w"> </span><span class="n">validity</span><span class="p">);</span> |
| |
| <span class="k">auto</span><span class="w"> </span><span class="n">maybe_array</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">builder</span><span class="p">.</span><span class="n">Finish</span><span class="p">();</span> |
| </pre></div> |
| </div> |
| <p>If you still must append values one by one, some concrete builder subclasses |
| have methods marked “Unsafe” that assume the working area has been correctly |
| presized, and offer higher performance in exchange:</p> |
| <div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="n">arrow</span><span class="o">::</span><span class="n">Int64Builder</span><span class="w"> </span><span class="n">builder</span><span class="p">;</span> |
| <span class="c1">// Make place for 8 values in total</span> |
| <span class="n">builder</span><span class="p">.</span><span class="n">Reserve</span><span class="p">(</span><span class="mi">8</span><span class="p">);</span> |
| <span class="n">builder</span><span class="p">.</span><span class="n">UnsafeAppend</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span> |
| <span class="n">builder</span><span class="p">.</span><span class="n">UnsafeAppend</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span> |
| <span class="n">builder</span><span class="p">.</span><span class="n">UnsafeAppend</span><span class="p">(</span><span class="mi">3</span><span class="p">);</span> |
| <span class="n">builder</span><span class="p">.</span><span class="n">UnsafeAppendNull</span><span class="p">();</span> |
| <span class="n">builder</span><span class="p">.</span><span class="n">UnsafeAppend</span><span class="p">(</span><span class="mi">5</span><span class="p">);</span> |
| <span class="n">builder</span><span class="p">.</span><span class="n">UnsafeAppend</span><span class="p">(</span><span class="mi">6</span><span class="p">);</span> |
| <span class="n">builder</span><span class="p">.</span><span class="n">UnsafeAppend</span><span class="p">(</span><span class="mi">7</span><span class="p">);</span> |
| <span class="n">builder</span><span class="p">.</span><span class="n">UnsafeAppend</span><span class="p">(</span><span class="mi">8</span><span class="p">);</span> |
| |
| <span class="k">auto</span><span class="w"> </span><span class="n">maybe_array</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">builder</span><span class="p">.</span><span class="n">Finish</span><span class="p">();</span> |
| </pre></div> |
| </div> |
| </section> |
| </section> |
| <section id="size-limitations-and-recommendations"> |
| <h2>Size Limitations and Recommendations<a class="headerlink" href="#size-limitations-and-recommendations" title="Permalink to this heading">#</a></h2> |
| <p>Some array types are structurally limited to 32-bit sizes. This is the case |
| for list arrays (which can hold up to 2^31 elements), string arrays and binary |
| arrays (which can hold up to 2GB of binary data), at least. Some other array |
| types can hold up to 2^63 elements in the C++ implementation, but other Arrow |
| implementations can have a 32-bit size limitation for those array types as well.</p> |
| <p>For these reasons, it is recommended that huge data be chunked in subsets of |
| more reasonable size.</p> |
| </section> |
| <section id="chunked-arrays"> |
| <h2>Chunked Arrays<a class="headerlink" href="#chunked-arrays" title="Permalink to this heading">#</a></h2> |
| <p>A <a class="reference internal" href="api/array.html#_CPPv4N5arrow12ChunkedArrayE" title="arrow::ChunkedArray"><code class="xref cpp cpp-class docutils literal notranslate"><span class="pre">arrow::ChunkedArray</span></code></a> is, like an array, a logical sequence of values; |
| but unlike a simple array, a chunked array does not require the entire sequence |
| to be physically contiguous in memory. Also, the constituents of a chunked array |
| need not have the same size, but they must all have the same data type.</p> |
| <p>A chunked array is constructed by aggregating any number of arrays. Here we’ll |
| build a chunked array with the same logical values as in the example above, |
| but in two separate chunks:</p> |
| <div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">shared_ptr</span><span class="o"><</span><span class="n">arrow</span><span class="o">::</span><span class="n">Array</span><span class="o">>></span><span class="w"> </span><span class="n">chunks</span><span class="p">;</span> |
| <span class="n">std</span><span class="o">::</span><span class="n">shared_ptr</span><span class="o"><</span><span class="n">arrow</span><span class="o">::</span><span class="n">Array</span><span class="o">></span><span class="w"> </span><span class="n">array</span><span class="p">;</span> |
| |
| <span class="c1">// Build first chunk</span> |
| <span class="n">arrow</span><span class="o">::</span><span class="n">Int64Builder</span><span class="w"> </span><span class="n">builder</span><span class="p">;</span> |
| <span class="n">builder</span><span class="p">.</span><span class="n">Append</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span> |
| <span class="n">builder</span><span class="p">.</span><span class="n">Append</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span> |
| <span class="n">builder</span><span class="p">.</span><span class="n">Append</span><span class="p">(</span><span class="mi">3</span><span class="p">);</span> |
| <span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="o">!</span><span class="n">builder</span><span class="p">.</span><span class="n">Finish</span><span class="p">(</span><span class="o">&</span><span class="n">array</span><span class="p">).</span><span class="n">ok</span><span class="p">())</span><span class="w"> </span><span class="p">{</span> |
| <span class="w"> </span><span class="c1">// ... do something on array building failure</span> |
| <span class="p">}</span> |
| <span class="n">chunks</span><span class="p">.</span><span class="n">push_back</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">move</span><span class="p">(</span><span class="n">array</span><span class="p">));</span> |
| |
| <span class="c1">// Build second chunk</span> |
| <span class="n">builder</span><span class="p">.</span><span class="n">Reset</span><span class="p">();</span> |
| <span class="n">builder</span><span class="p">.</span><span class="n">AppendNull</span><span class="p">();</span> |
| <span class="n">builder</span><span class="p">.</span><span class="n">Append</span><span class="p">(</span><span class="mi">5</span><span class="p">);</span> |
| <span class="n">builder</span><span class="p">.</span><span class="n">Append</span><span class="p">(</span><span class="mi">6</span><span class="p">);</span> |
| <span class="n">builder</span><span class="p">.</span><span class="n">Append</span><span class="p">(</span><span class="mi">7</span><span class="p">);</span> |
| <span class="n">builder</span><span class="p">.</span><span class="n">Append</span><span class="p">(</span><span class="mi">8</span><span class="p">);</span> |
| <span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="o">!</span><span class="n">builder</span><span class="p">.</span><span class="n">Finish</span><span class="p">(</span><span class="o">&</span><span class="n">array</span><span class="p">).</span><span class="n">ok</span><span class="p">())</span><span class="w"> </span><span class="p">{</span> |
| <span class="w"> </span><span class="c1">// ... do something on array building failure</span> |
| <span class="p">}</span> |
| <span class="n">chunks</span><span class="p">.</span><span class="n">push_back</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">move</span><span class="p">(</span><span class="n">array</span><span class="p">));</span> |
| |
| <span class="k">auto</span><span class="w"> </span><span class="n">chunked_array</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">std</span><span class="o">::</span><span class="n">make_shared</span><span class="o"><</span><span class="n">arrow</span><span class="o">::</span><span class="n">ChunkedArray</span><span class="o">></span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">move</span><span class="p">(</span><span class="n">chunks</span><span class="p">));</span> |
| |
| <span class="n">assert</span><span class="p">(</span><span class="n">chunked_array</span><span class="o">-></span><span class="n">num_chunks</span><span class="p">()</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span> |
| <span class="c1">// Logical length in number of values</span> |
| <span class="n">assert</span><span class="p">(</span><span class="n">chunked_array</span><span class="o">-></span><span class="n">length</span><span class="p">()</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="mi">8</span><span class="p">);</span> |
| <span class="n">assert</span><span class="p">(</span><span class="n">chunked_array</span><span class="o">-></span><span class="n">null_count</span><span class="p">()</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="mi">1</span><span class="p">);</span> |
| </pre></div> |
| </div> |
| </section> |
| <section id="slicing"> |
| <h2>Slicing<a class="headerlink" href="#slicing" title="Permalink to this heading">#</a></h2> |
| <p>Like for physical memory buffers, it is possible to make zero-copy slices |
| of arrays and chunked arrays, to obtain an array or chunked array referring |
| to some logical subsequence of the data. This is done by calling the |
| <a class="reference internal" href="api/array.html#_CPPv4NK5arrow5Array5SliceE7int64_t7int64_t" title="arrow::Array::Slice"><code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">arrow::Array::Slice()</span></code></a> and <a class="reference internal" href="api/array.html#_CPPv4NK5arrow12ChunkedArray5SliceE7int64_t7int64_t" title="arrow::ChunkedArray::Slice"><code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">arrow::ChunkedArray::Slice()</span></code></a> methods, |
| respectively.</p> |
| </section> |
| </section> |
| |
| |
| </article> |
| |
| |
| |
| |
| |
| <footer class="prev-next-footer"> |
| |
| <div class="prev-next-area"> |
| <a class="left-prev" |
| href="memory.html" |
| title="previous page"> |
| <i class="fa-solid fa-angle-left"></i> |
| <div class="prev-next-info"> |
| <p class="prev-next-subtitle">previous</p> |
| <p class="prev-next-title">Memory Management</p> |
| </div> |
| </a> |
| <a class="right-next" |
| href="datatypes.html" |
| title="next page"> |
| <div class="prev-next-info"> |
| <p class="prev-next-subtitle">next</p> |
| <p class="prev-next-title">Data Types</p> |
| </div> |
| <i class="fa-solid fa-angle-right"></i> |
| </a> |
| </div> |
| </footer> |
| |
| </div> |
| |
| |
| |
| <div class="bd-sidebar-secondary bd-toc"><div class="sidebar-secondary-items sidebar-secondary__inner"> |
| |
| |
| <div class="sidebar-secondary-item"> |
| <div |
| id="pst-page-navigation-heading-2" |
| class="page-toc tocsection onthispage"> |
| <i class="fa-solid fa-list"></i> On this page |
| </div> |
| <nav class="bd-toc-nav page-toc" aria-labelledby="pst-page-navigation-heading-2"> |
| <ul class="visible nav section-nav flex-column"> |
| <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#building-an-array">Building an array</a><ul class="visible nav section-nav flex-column"> |
| <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#available-strategies">Available strategies</a></li> |
| <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#using-arraybuilder-and-its-subclasses">Using ArrayBuilder and its subclasses</a></li> |
| <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#performance">Performance</a></li> |
| </ul> |
| </li> |
| <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#size-limitations-and-recommendations">Size Limitations and Recommendations</a></li> |
| <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#chunked-arrays">Chunked Arrays</a></li> |
| <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#slicing">Slicing</a></li> |
| </ul> |
| </nav></div> |
| |
| <div class="sidebar-secondary-item"> |
| |
| |
| <div class="tocsection editthispage"> |
| <a href="https://github.com/apache/arrow/edit/main/docs/source/cpp/arrays.rst"> |
| <i class="fa-solid fa-pencil"></i> |
| |
| |
| |
| Edit on GitHub |
| |
| |
| </a> |
| </div> |
| </div> |
| |
| </div></div> |
| |
| |
| </div> |
| <footer class="bd-footer-content"> |
| |
| </footer> |
| |
| </main> |
| </div> |
| </div> |
| |
| <!-- Scripts loaded after <body> so the DOM is not blocked --> |
| <script src="../_static/scripts/bootstrap.js?digest=8d27b9dea8ad943066ae"></script> |
| <script src="../_static/scripts/pydata-sphinx-theme.js?digest=8d27b9dea8ad943066ae"></script> |
| |
| <footer class="bd-footer"> |
| <div class="bd-footer__inner bd-page-width"> |
| |
| <div class="footer-items__start"> |
| |
| <div class="footer-item"> |
| |
| <p class="copyright"> |
| |
| © Copyright 2016-2024 Apache Software Foundation. |
| Apache Arrow, Arrow, Apache, the Apache feather logo, and the Apache Arrow project logo are either registered trademarks or trademarks of The Apache Software Foundation in the United States and other countries. |
| <br/> |
| |
| </p> |
| </div> |
| |
| <div class="footer-item"> |
| |
| <p class="sphinx-version"> |
| Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 6.2.0. |
| <br/> |
| </p> |
| </div> |
| |
| </div> |
| |
| |
| |
| <div class="footer-items__end"> |
| |
| <div class="footer-item"> |
| <p class="theme-version"> |
| Built with the <a href="https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html">PyData Sphinx Theme</a> 0.15.2. |
| </p></div> |
| |
| </div> |
| |
| </div> |
| |
| </footer> |
| </body> |
| </html> |
