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 <andygrov...@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 <andygrov...@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
u...@apache.org.

Reply via email to