You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@arrow.apache.org by ks...@apache.org on 2018/09/06 11:37:49 UTC
[arrow] branch master updated: ARROW-3172: [Rust] Update
documentation for datatypes.rs
This is an automated email from the ASF dual-hosted git repository.
kszucs pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/arrow.git
The following commit(s) were added to refs/heads/master by this push:
new e0c07f4 ARROW-3172: [Rust] Update documentation for datatypes.rs
e0c07f4 is described below
commit e0c07f4dfe4305aadfd7288403f6f3c6272a8369
Author: Paddy Horan <pa...@hotmail.com>
AuthorDate: Thu Sep 6 13:37:40 2018 +0200
ARROW-3172: [Rust] Update documentation for datatypes.rs
Author: Paddy Horan <pa...@hotmail.com>
Closes #2513 from paddyhoran/ARROW-3172 and squashes the following commits:
148e34dd <Paddy Horan> Fix lint.
42e039b0 <Paddy Horan> Changed to more conventional doc comment style
171b526a <Paddy Horan> Fixed grammatical errors
c2a1a765 <Paddy Horan> Fixing lints.
f9a28442 <Paddy Horan> Updated documentation for datatypes.rs
---
rust/src/datatypes.rs | 70 ++++++++++++++++++++++++++++++++++++++++++---------
1 file changed, 58 insertions(+), 12 deletions(-)
diff --git a/rust/src/datatypes.rs b/rust/src/datatypes.rs
index 63db786..4ffb8e4 100644
--- a/rust/src/datatypes.rs
+++ b/rust/src/datatypes.rs
@@ -15,6 +15,12 @@
// specific language governing permissions and limitations
// under the License.
+//! Defines the data-types of Arrow arrays.
+//!
+//! For an overview of the terminology used within the arrow project and more general information
+//! regarding data-types and memory layouts see
+//! [here](https://arrow.apache.org/docs/memory_layout.html).
+
use std::fmt;
use std::mem::size_of;
use std::slice::from_raw_parts;
@@ -22,7 +28,17 @@ use std::slice::from_raw_parts;
use error::{ArrowError, Result};
use serde_json::Value;
-/// Arrow data type
+/// The possible relative types that are supported.
+///
+/// The variants of this enum include primitive fixed size types as well as parametric or nested
+/// types.
+/// Currently the Rust implementation supports the following nested types:
+/// - `List<T>`
+/// - `Struct<T, U, V, ...>`
+///
+/// Nested types can themselves be nested within other arrays.
+/// For more information on these types please see
+/// [here](https://arrow.apache.org/docs/memory_layout.html).
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum DataType {
Boolean,
@@ -42,7 +58,9 @@ pub enum DataType {
Struct(Vec<Field>),
}
-/// Arrow struct/schema field
+/// Contains the meta-data for a single relative type.
+///
+/// The `Schema` object is an ordered collection of `Field` objects.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Field {
name: String,
@@ -50,7 +68,10 @@ pub struct Field {
nullable: bool,
}
-/// Primitive type (ints, floats, strings)
+/// Trait indicating a primitive fixed-width type (bool, ints and floats).
+///
+/// This trait is a marker trait to indicate a primitive type, i.e. a type that occupies a fixed
+/// size in memory as indicated in bit or byte width.
pub trait ArrowPrimitiveType: Send + Sync + Copy + PartialOrd + 'static {}
impl ArrowPrimitiveType for bool {}
@@ -65,8 +86,9 @@ impl ArrowPrimitiveType for i64 {}
impl ArrowPrimitiveType for f32 {}
impl ArrowPrimitiveType for f64 {}
+/// Allows conversion from supported Arrow types to a byte slice.
pub trait ToByteSlice {
- /// Converts this instance into a byte slice.
+ /// Converts this instance into a byte slice
fn to_byte_slice(&self) -> &[u8];
}
@@ -189,6 +211,7 @@ impl DataType {
}
impl Field {
+ /// Creates a new field
pub fn new(name: &str, data_type: DataType, nullable: bool) -> Self {
Field {
name: name.to_string(),
@@ -197,19 +220,22 @@ impl Field {
}
}
+ /// Returns an immutable reference to the `Field`'s name
pub fn name(&self) -> &String {
&self.name
}
+ /// Returns an immutable reference to the `Field`'s data-type
pub fn data_type(&self) -> &DataType {
&self.data_type
}
+ /// Indicates whether this `Field` supports null values
pub fn is_nullable(&self) -> bool {
self.nullable
}
- /// Parse a field definition from a JSON representation
+ /// Parse a `Field` definition from a JSON representation
pub fn from(json: &Value) -> Result<Self> {
match *json {
Value::Object(ref map) => {
@@ -249,7 +275,7 @@ impl Field {
}
}
- /// Generate a JSON representation of the field
+ /// Generate a JSON representation of the `Field`
pub fn to_json(&self) -> Value {
json!({
"name": self.name,
@@ -258,6 +284,7 @@ impl Field {
})
}
+ /// Converts to a `String` representation of the the `Field`
pub fn to_string(&self) -> String {
format!("{}: {:?}", self.name, self.data_type)
}
@@ -265,35 +292,54 @@ impl Field {
impl fmt::Display for Field {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
- write!(f, "{}: {:?}", self.name, self.data_type)
+ write!(f, "{}", self.to_string())
}
}
-/// Arrow Schema
+/// Describes the meta-data of an ordered sequence of relative types.
+///
+/// Note that this information is only part of the meta-data and not part of the physical memory
+/// layout.
#[derive(Debug, Clone)]
pub struct Schema {
columns: Vec<Field>,
}
impl Schema {
- /// create an empty schema
+ /// Creates an empty `Schema`
pub fn empty() -> Self {
- Schema { columns: vec![] }
+ Self { columns: vec![] }
}
+ /// Creates a new `Schema` from a sequence of `Field` values
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// # extern crate arrow;
+ /// # use arrow::datatypes::{Field, DataType, Schema};
+ /// let field_a = Field::new("a", DataType::Int64, false);
+ /// let field_b = Field::new("b", DataType::Boolean, false);
+ ///
+ /// let schema = Schema::new(vec![field_a, field_b]);
+ /// ```
pub fn new(columns: Vec<Field>) -> Self {
- Schema { columns }
+ Self { columns }
}
+ /// Returns an immutable reference of the vector of `Field` instances
pub fn columns(&self) -> &Vec<Field> {
&self.columns
}
+ /// Returns an immutable reference of a specific `Field` instance selected using an offset
+ /// within the internal `columns` vector
pub fn column(&self, i: usize) -> &Field {
&self.columns[i]
}
- /// look up a column by name and return a reference to the column along with it's index
+ /// Look up a column by name and return a immutable reference to the column along with
+ /// it's index
pub fn column_with_name(&self, name: &str) -> Option<(usize, &Field)> {
self.columns
.iter()