diff --git a/arrow-cast/src/base64.rs b/arrow-cast/src/base64.rs index 319c76548286..50c7423626ed 100644 --- a/arrow-cast/src/base64.rs +++ b/arrow-cast/src/base64.rs @@ -15,7 +15,9 @@ // specific language governing permissions and limitations // under the License. -//! Functions for Base64 encoding/decoding +//! Functions for converting data in [`GenericBinaryArray`] such as [`StringArray`] to/from base64 encoded strings +//! +//! [`StringArray`]: arrow_array::StringArray use arrow_array::{Array, GenericBinaryArray, GenericStringArray, OffsetSizeTrait}; use arrow_buffer::OffsetBuffer; @@ -25,7 +27,7 @@ use base64::engine::Config; pub use base64::prelude::*; -/// Bas64 encode each element of `array` with the provided `engine` +/// Bas64 encode each element of `array` with the provided [`Engine`] pub fn b64_encode( engine: &E, array: &GenericBinaryArray, @@ -51,7 +53,7 @@ pub fn b64_encode( unsafe { GenericStringArray::new_unchecked(offsets, buffer.into(), array.nulls().cloned()) } } -/// Base64 decode each element of `array` with the provided `engine` +/// Base64 decode each element of `array` with the provided [`Engine`] pub fn b64_decode( engine: &E, array: &GenericBinaryArray, diff --git a/arrow-cast/src/display.rs b/arrow-cast/src/display.rs index edde288e9c35..804cf8a831e1 100644 --- a/arrow-cast/src/display.rs +++ b/arrow-cast/src/display.rs @@ -15,10 +15,14 @@ // specific language governing permissions and limitations // under the License. -//! Functions for printing array values, as strings, for debugging -//! purposes. See the `pretty` crate for additional functions for +//! Functions for printing array values as human-readable strings. +//! +//! This is often used for debugging or logging purposes. +//! +//! See the [`pretty`] crate for additional functions for //! record batch pretty printing. - +//! +//! [`pretty`]: crate::pretty use std::fmt::{Display, Formatter, Write}; use std::ops::Range; diff --git a/arrow-cast/src/lib.rs b/arrow-cast/src/lib.rs index 71ebe6c0ed8b..188a74e0aa52 100644 --- a/arrow-cast/src/lib.rs +++ b/arrow-cast/src/lib.rs @@ -15,8 +15,7 @@ // specific language governing permissions and limitations // under the License. -//! Cast kernel for [Apache Arrow](https://docs.rs/arrow) - +//! Functions fcr converting from one data type to another in [Apache Arrow](https://docs.rs/arrow) pub mod cast; pub use cast::*; pub mod display; diff --git a/arrow-cast/src/parse.rs b/arrow-cast/src/parse.rs index b74d9590ae41..9bd5c72cc4f8 100644 --- a/arrow-cast/src/parse.rs +++ b/arrow-cast/src/parse.rs @@ -15,6 +15,9 @@ // specific language governing permissions and limitations // under the License. +//! [`Parser`] implementations for converting strings to Arrow types +//! +//! Used by the CSV and JSON readers to convert strings to Arrow types use arrow_array::timezone::Tz; use arrow_array::types::*; use arrow_array::ArrowNativeTypeOp; @@ -405,8 +408,29 @@ fn string_to_time(s: &str) -> Option { ) } -/// Specialized parsing implementations -/// used by csv and json reader +/// Specialized parsing implementations used by csv and json reader +/// +/// You can also use this to parse strings to Arrow types. +/// +/// # Example +/// +/// To parse a string to a [`Date32Type`]: +/// +/// ``` +/// use arrow_cast::parse::Parser; +/// use arrow_array::types::Date32Type; +/// let date = Date32Type::parse("2021-01-01").unwrap(); +/// assert_eq!(date, 18628); +/// ``` +/// +/// To parse a string to a [`TimestampNanosecondType`]: +/// +/// ``` +/// use arrow_cast::parse::Parser; +/// use arrow_array::types::TimestampNanosecondType; +/// let ts = TimestampNanosecondType::parse("2021-01-01T00:00:00.123456789Z").unwrap(); +/// assert_eq!(ts, 1609459200123456789); +/// ``` pub trait Parser: ArrowPrimitiveType { fn parse(string: &str) -> Option; diff --git a/arrow-cast/src/pretty.rs b/arrow-cast/src/pretty.rs index 49fb359b9d42..9383b9f73f61 100644 --- a/arrow-cast/src/pretty.rs +++ b/arrow-cast/src/pretty.rs @@ -15,8 +15,12 @@ // specific language governing permissions and limitations // under the License. -//! Utilities for pretty printing record batches. Note this module is not -//! available unless `feature = "prettyprint"` is enabled. +//! Utilities for pretty printing [`RecordBatch`]es and [`Array`]s. +//! +//! Note this module is not available unless `feature = "prettyprint"` is enabled. +//! +//! [`RecordBatch`]: arrow_array::RecordBatch +//! [`Array`]: arrow_array::Array use std::fmt::Display;