You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@arrow.apache.org by uw...@apache.org on 2018/04/12 09:37:51 UTC
[arrow] branch master updated: ARROW-2445: [Rust] Add documentation
and make some fields private
This is an automated email from the ASF dual-hosted git repository.
uwe 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 6e8ecb5 ARROW-2445: [Rust] Add documentation and make some fields private
6e8ecb5 is described below
commit 6e8ecb5e595b002fbadee8ff2db473aecc956b7d
Author: Andy Grove <an...@gmail.com>
AuthorDate: Thu Apr 12 11:37:43 2018 +0200
ARROW-2445: [Rust] Add documentation and make some fields private
No functional changes.
Author: Andy Grove <an...@gmail.com>
Closes #1881 from andygrove/documentation and squashes the following commits:
1fc0ad4 <Andy Grove> add comments to many structs and make some fields private and add accessor methods
05592f8 <Andy Grove> Merge remote-tracking branch 'upstream/master'
8c0e698 <Andy Grove> Merge remote-tracking branch 'upstream/master'
31ef90b <Andy Grove> Merge remote-tracking branch 'upstream/master'
2f87c70 <Andy Grove> Fix build - add missing import
---
rust/src/array.rs | 51 ++++++++++++++++++++++++++++++------------------
rust/src/buffer.rs | 4 ++++
rust/src/builder.rs | 2 ++
rust/src/datatypes.rs | 13 +++++++++---
rust/src/list.rs | 28 +++++++++++++++++++++++---
rust/src/list_builder.rs | 10 ++++++----
6 files changed, 79 insertions(+), 29 deletions(-)
diff --git a/rust/src/array.rs b/rust/src/array.rs
index 1b619d5..63d1130 100644
--- a/rust/src/array.rs
+++ b/rust/src/array.rs
@@ -69,10 +69,14 @@ arraydata_from_primitive!(u32, UInt32);
arraydata_from_primitive!(u64, UInt64);
pub struct Array {
- pub len: i32,
- pub null_count: i32,
- pub validity_bitmap: Option<Bitmap>,
- pub data: ArrayData,
+ /// number of elements in the array
+ len: i32,
+ /// number of null elements in the array
+ null_count: i32,
+ /// If null_count is greater than zero then the validity_bitmap will be Some(Bitmap)
+ validity_bitmap: Option<Bitmap>,
+ /// The array of elements
+ data: ArrayData,
}
impl Array {
@@ -86,13 +90,25 @@ impl Array {
}
}
+ /// Get a reference to the array data
pub fn data(&self) -> &ArrayData {
&self.data
}
+ /// number of elements in the array
pub fn len(&self) -> usize {
self.len as usize
}
+
+ /// number of null elements in the array
+ pub fn null_count(&self) -> usize {
+ self.null_count as usize
+ }
+
+ /// If null_count is greater than zero then the validity_bitmap will be Some(Bitmap)
+ pub fn validity_bitmap(&self) -> &Option<Bitmap> {
+ &self.validity_bitmap
+ }
}
macro_rules! array_from_primitive {
@@ -208,17 +224,14 @@ mod tests {
fn test_utf8_offsets() {
let a = Array::from(vec!["this", "is", "a", "test"]);
assert_eq!(4, a.len());
- match a.data() {
- &ArrayData::Utf8(List {
- ref data,
- ref offsets,
- }) => {
- assert_eq!(11, data.len());
- assert_eq!(0, *offsets.get(0));
- assert_eq!(4, *offsets.get(1));
- assert_eq!(6, *offsets.get(2));
- assert_eq!(7, *offsets.get(3));
- assert_eq!(11, *offsets.get(4));
+ match *a.data() {
+ ArrayData::Utf8(ref list) => {
+ assert_eq!(11, list.data().len());
+ assert_eq!(0, *list.offsets().get(0));
+ assert_eq!(4, *list.offsets().get(1));
+ assert_eq!(6, *list.offsets().get(2));
+ assert_eq!(7, *list.offsets().get(3));
+ assert_eq!(11, *list.offsets().get(4));
}
_ => panic!(),
}
@@ -227,8 +240,8 @@ mod tests {
#[test]
fn test_utf8_slices() {
let a = Array::from(vec!["this", "is", "a", "test"]);
- match a.data() {
- &ArrayData::Utf8(ref d) => {
+ match *a.data() {
+ ArrayData::Utf8(ref d) => {
assert_eq!(4, d.len());
assert_eq!("this", str::from_utf8(d.slice(0)).unwrap());
assert_eq!("is", str::from_utf8(d.slice(1)).unwrap());
@@ -255,8 +268,8 @@ mod tests {
fn test_from_i32() {
let a = Array::from(vec![15, 14, 13, 12, 11]);
assert_eq!(5, a.len());
- match a.data() {
- &ArrayData::Int32(ref b) => {
+ match *a.data() {
+ ArrayData::Int32(ref b) => {
assert_eq!(vec![15, 14, 13, 12, 11], b.iter().collect::<Vec<i32>>());
}
_ => panic!(),
diff --git a/rust/src/buffer.rs b/rust/src/buffer.rs
index 85f57f6..5349c40 100644
--- a/rust/src/buffer.rs
+++ b/rust/src/buffer.rs
@@ -31,7 +31,9 @@ extern "C" {
/// Buffer<T> is essentially just a Vec<T> for fixed-width primitive types and the start of the
/// memory region is aligned at a 64-byte boundary
pub struct Buffer<T> {
+ /// Contiguous memory region holding instances of primitive T
data: *const T,
+ /// Number of elements in the buffer
len: i32,
}
@@ -40,6 +42,7 @@ impl<T> Buffer<T> {
Buffer { data, len }
}
+ /// Get the number of elements in the buffer
pub fn len(&self) -> i32 {
self.len
}
@@ -96,6 +99,7 @@ impl<T> Drop for Buffer<T> {
}
}
+/// Iterator over the elements of a buffer
pub struct BufferIterator<T> {
data: *const T,
len: i32,
diff --git a/rust/src/builder.rs b/rust/src/builder.rs
index 421b1a9..e354a2a 100644
--- a/rust/src/builder.rs
+++ b/rust/src/builder.rs
@@ -54,10 +54,12 @@ impl<T> Builder<T> {
}
}
+ /// Get the number of elements in the builder
pub fn len(&self) -> usize {
self.len
}
+ /// Get the capacity of the builder (number of elements)
pub fn capacity(&self) -> usize {
self.capacity
}
diff --git a/rust/src/datatypes.rs b/rust/src/datatypes.rs
index 7b4e3e8..58f5e8e 100644
--- a/rust/src/datatypes.rs
+++ b/rust/src/datatypes.rs
@@ -19,6 +19,7 @@ use super::error::ArrowError;
use serde_json::Value;
use std::fmt;
+/// Arrow data type
#[derive(Debug, Clone, PartialEq)]
pub enum DataType {
Boolean,
@@ -38,6 +39,7 @@ pub enum DataType {
}
impl DataType {
+ /// Parse a data type from a JSON representation
fn from(json: &Value) -> Result<DataType, ArrowError> {
//println!("DataType::from({:?})", json);
match *json {
@@ -106,6 +108,7 @@ impl DataType {
}
}
+ /// Generate a JSON representation of the data type
pub fn to_json(&self) -> Value {
match *self {
DataType::Boolean => json!({"name": "bool"}),
@@ -130,11 +133,12 @@ impl DataType {
}
}
+/// Arrow Field
#[derive(Debug, Clone, PartialEq)]
pub struct Field {
- pub name: String,
- pub data_type: DataType,
- pub nullable: bool,
+ name: String,
+ data_type: DataType,
+ nullable: bool,
}
impl Field {
@@ -146,6 +150,7 @@ impl Field {
}
}
+ /// Parse a field definition from a JSON representation
pub fn from(json: &Value) -> Result<Self, ArrowError> {
//println!("Field::from({:?}", json);
match *json {
@@ -186,6 +191,7 @@ impl Field {
}
}
+ /// Generate a JSON representation of the field
pub fn to_json(&self) -> Value {
json!({
"name": self.name,
@@ -205,6 +211,7 @@ impl fmt::Display for Field {
}
}
+/// Arrow Schema
#[derive(Debug, Clone)]
pub struct Schema {
pub columns: Vec<Field>,
diff --git a/rust/src/list.rs b/rust/src/list.rs
index fad0ed3..abc0370 100644
--- a/rust/src/list.rs
+++ b/rust/src/list.rs
@@ -20,16 +20,37 @@ use std::str;
use super::buffer::Buffer;
use super::list_builder::ListBuilder;
+/// List<T> is a nested type in which each array slot contains a variable-size sequence of values of
+/// the same type T
pub struct List<T> {
- pub data: Buffer<T>,
- pub offsets: Buffer<i32>,
+ /// Contiguous region of memory holding contents of the lists
+ data: Buffer<T>,
+ /// offsets to start of each array slot
+ offsets: Buffer<i32>,
}
impl<T> List<T> {
+ /// Create a List from raw parts
+ pub fn from_raw_parts(data: Buffer<T>, offsets: Buffer<i32>) -> Self {
+ List { data, offsets }
+ }
+
+ /// Get the length of the List (number of array slots)
pub fn len(&self) -> i32 {
self.offsets.len() - 1
}
+ /// Get a reference to the raw data in the list
+ pub fn data(&self) -> &Buffer<T> {
+ &self.data
+ }
+
+ /// Get a reference to the offsets in the list
+ pub fn offsets(&self) -> &Buffer<i32> {
+ &self.offsets
+ }
+
+ /// Get the contents of a single array slot
pub fn slice(&self, index: usize) -> &[T] {
let start = *self.offsets.get(index) as usize;
let end = *self.offsets.get(index + 1) as usize;
@@ -37,6 +58,7 @@ impl<T> List<T> {
}
}
+/// Create a List<u8> from a Vec<String>
impl From<Vec<String>> for List<u8> {
fn from(v: Vec<String>) -> Self {
let mut b: ListBuilder<u8> = ListBuilder::with_capacity(v.len());
@@ -47,7 +69,7 @@ impl From<Vec<String>> for List<u8> {
}
}
-/// This method mostly just used for unit tests
+/// Create a List<u8> from a Vec<&str>
impl From<Vec<&'static str>> for List<u8> {
fn from(v: Vec<&'static str>) -> Self {
List::from(v.iter().map(|s| s.to_string()).collect::<Vec<String>>())
diff --git a/rust/src/list_builder.rs b/rust/src/list_builder.rs
index 0122e68..4c14ef8 100644
--- a/rust/src/list_builder.rs
+++ b/rust/src/list_builder.rs
@@ -18,16 +18,19 @@
use super::builder::*;
use super::list::List;
+/// Builder for List<T>
pub struct ListBuilder<T> {
data: Builder<T>,
offsets: Builder<i32>,
}
impl<T> ListBuilder<T> {
+ /// Create a ListBuilder with a default capacity
pub fn new() -> Self {
ListBuilder::with_capacity(64)
}
+ /// Create a ListBuilder with the specified capacity
pub fn with_capacity(n: usize) -> Self {
let data = Builder::with_capacity(n);
let mut offsets = Builder::with_capacity(n);
@@ -35,16 +38,15 @@ impl<T> ListBuilder<T> {
ListBuilder { data, offsets }
}
+ /// Push one array slot to the builder
pub fn push(&mut self, slice: &[T]) {
self.data.push_slice(slice);
self.offsets.push(self.data.len() as i32);
}
+ /// Create an immutable List<T> from the builder
pub fn finish(&mut self) -> List<T> {
- List {
- data: self.data.finish(),
- offsets: self.offsets.finish(),
- }
+ List::from_raw_parts(self.data.finish(), self.offsets.finish())
}
}
--
To stop receiving notification emails like this one, please contact
uwe@apache.org.