This is an automated email from the ASF dual-hosted git repository.
tustvold pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/arrow-rs.git
The following commit(s) were added to refs/heads/master by this push:
new 2cf4cd8f1 More docs (#2305)
2cf4cd8f1 is described below
commit 2cf4cd8f1c570b91880cdc043624bb7be40a3657
Author: Raphael Taylor-Davies <[email protected]>
AuthorDate: Wed Aug 3 19:20:53 2022 +0100
More docs (#2305)
---
arrow/src/lib.rs | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 53 insertions(+)
diff --git a/arrow/src/lib.rs b/arrow/src/lib.rs
index 95c69ca0b..45092ef4c 100644
--- a/arrow/src/lib.rs
+++ b/arrow/src/lib.rs
@@ -18,6 +18,42 @@
//! A complete, safe, native Rust implementation of [Apache
Arrow](https://arrow.apache.org), a cross-language
//! development platform for in-memory data.
//!
+//! # Performance Tips
+//!
+//! Arrow aims to be as fast as possible out of the box, whilst not
compromising on safety. However,
+//! it relies heavily on LLVM auto-vectorisation to achieve this.
Unfortunately the LLVM defaults,
+//! particularly for x86_64, favour portability over performance, and LLVM
will consequently avoid
+//! using more recent instructions that would result in errors on older CPUs.
+//!
+//! To address this it is recommended that you specify the override the LLVM
defaults either
+//! by setting the `RUSTFLAGS` environment variable, or by setting `rustflags`
in your
+//! [Cargo
configuration](https://doc.rust-lang.org/cargo/reference/config.html)
+//!
+//! Enable all features supported by the current CPU
+//!
+//! ```ignore
+//! RUSTFLAGS="-C target-cpu=native"
+//! ```
+//!
+//! Enable all features supported by the current CPU, and enable full use of
AVX512
+//!
+//! ```ignore
+//! RUSTFLAGS="-C target-cpu=native -C target-feature=-prefer-256-bit"
+//! ```
+//!
+//! Enable all features supported by CPUs more recent than haswell (2013)
+//!
+//! ```ignore
+//! RUSTFLAGS="-C target-cpu=haswell"
+//! ```
+//!
+//! For a full list of features and target CPUs use
+//!
+//! ```ignore
+//! $ rustc --print target-cpus
+//! $ rustc --print target-features
+//! ```
+//!
//! # Columnar Format
//!
//! The [`array`] module provides statically typed implementations of all the
array
@@ -57,6 +93,23 @@
//! assert_eq!(sum(&TimestampNanosecondArray::from(vec![1, 2, 3])), 6);
//! ```
//!
+//! And the following is generic over all arrays with comparable values
+//!
+//! ```rust
+//! # use arrow::array::{ArrayAccessor, ArrayIter, Int32Array, StringArray};
+//! # use arrow::datatypes::ArrowPrimitiveType;
+//! #
+//! fn min<T: ArrayAccessor>(array: T) -> Option<T::Item>
+//! where
+//! T::Item: Ord
+//! {
+//! ArrayIter::new(array).filter_map(|v| v).min()
+//! }
+//!
+//! assert_eq!(min(&Int32Array::from(vec![4, 2, 1, 6])), Some(1));
+//! assert_eq!(min(&StringArray::from(vec!["b", "a", "c"])), Some("a"));
+//! ```
+//!
//! For more examples, consult the [`array`] docs.
//!
//! # Type Erasure / Trait Objects
