[arrow-rs] branch master updated: Docstrings for Timestamp*Array. (#988)

[al...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

alamb 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 6817c80  Docstrings for Timestamp*Array. (#988)
6817c80 is described below

commit 6817c80eccbf2d220f5da8797438bd359e4bdf97
Author: Navin <na...@novemberkilo.com>
AuthorDate: Sun Dec 5 02:21:47 2021 +1100

    Docstrings for Timestamp*Array. (#988)
    
    * Docstrings for TimestampSecondArray.
    
    * fixup! Docstrings for TimestampSecondArray.
---
 arrow/src/array/mod.rs | 50 +++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 49 insertions(+), 1 deletion(-)

diff --git a/arrow/src/array/mod.rs b/arrow/src/array/mod.rs
index 4d9eaa7..26db3e6 100644
--- a/arrow/src/array/mod.rs
+++ b/arrow/src/array/mod.rs
@@ -324,10 +324,58 @@ pub type UInt32DictionaryArray = DictionaryArray<UInt32Type>;
 /// assert_eq!(array.values(), &values);
 /// ```
 pub type UInt64DictionaryArray = DictionaryArray<UInt64Type>;
-
+///
+/// A primitive array where each element is of type `TimestampSecondType.`
+/// See also [`Timestamp.`](crate::datatypes::Timestamp)
+///
+/// # Example: UTC timestamps post epoch
+/// ```
+/// # use arrow::array::TimestampSecondArray;
+/// use chrono::FixedOffset;
+/// // Corresponds to single element array with entry 1970-05-09T14:25:11+0:00
+/// let arr = TimestampSecondArray::from_vec(vec![11111111], None);
+/// // OR
+/// let arr = TimestampSecondArray::from_opt_vec(vec![Some(11111111)], None);
+/// let utc_offset = FixedOffset::east(0);
+///
+/// assert_eq!(arr.value_as_datetime_with_tz(0, utc_offset).map(|v| v.to_string()).unwrap(), "1970-05-09 14:25:11")
+/// ```
+///
+/// # Example: UTC timestamps pre epoch
+/// ```
+/// # use arrow::array::TimestampSecondArray;
+/// use chrono::FixedOffset;
+/// // Corresponds to single element array with entry 1969-08-25T09:34:49+0:00
+/// let arr = TimestampSecondArray::from_vec(vec![-11111111], None);
+/// // OR
+/// let arr = TimestampSecondArray::from_opt_vec(vec![Some(-11111111)], None);
+/// let utc_offset = FixedOffset::east(0);
+///
+/// assert_eq!(arr.value_as_datetime_with_tz(0, utc_offset).map(|v| v.to_string()).unwrap(), "1969-08-25 09:34:49")
+/// ```
+///
+/// # Example: With timezone specified
+/// ```
+/// # use arrow::array::TimestampSecondArray;
+/// use chrono::FixedOffset;
+/// // Corresponds to single element array with entry 1970-05-10T00:25:11+10:00
+/// let arr = TimestampSecondArray::from_vec(vec![11111111], Some("+10:00".to_string()));
+/// // OR
+/// let arr = TimestampSecondArray::from_opt_vec(vec![Some(11111111)], Some("+10:00".to_string()));
+/// let sydney_offset = FixedOffset::east(10 * 60 * 60);
+///
+/// assert_eq!(arr.value_as_datetime_with_tz(0, sydney_offset).map(|v| v.to_string()).unwrap(), "1970-05-10 00:25:11")
+/// ```
+///
 pub type TimestampSecondArray = PrimitiveArray<TimestampSecondType>;
+/// A primitive array where each element is of type `TimestampMillisecondType.`
+/// See examples for [`TimestampSecondArray.`](crate::array::TimestampSecondArray)
 pub type TimestampMillisecondArray = PrimitiveArray<TimestampMillisecondType>;
+/// A primitive array where each element is of type `TimestampMicrosecondType.`
+/// See examples for [`TimestampSecondArray.`](crate::array::TimestampSecondArray)
 pub type TimestampMicrosecondArray = PrimitiveArray<TimestampMicrosecondType>;
+/// A primitive array where each element is of type `TimestampNanosecondType.`
+/// See examples for [`TimestampSecondArray.`](crate::array::TimestampSecondArray)
 pub type TimestampNanosecondArray = PrimitiveArray<TimestampNanosecondType>;
 pub type Date32Array = PrimitiveArray<Date32Type>;
 pub type Date64Array = PrimitiveArray<Date64Type>;