Update arrow module docs #1840
Merged
Update arrow module docs #1840
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
tustvold
commented
Jun 10, 2022
| @@ -15,114 +15,215 @@ | |||
| // specific language governing permissions and limitations | |||
| // under the License. | |||
|
|
|||
| //! A native Rust implementation of [Apache Arrow](https://arrow.apache.org), a cross-language | |||
| //! A complete, safe, native Rust implementation of [Apache Arrow](https://arrow.apache.org), a cross-language | |||
There was a problem hiding this comment.
Nothing like a good bit of marketeering 😆
| //! [the Arrow data layout specification](https://arrow.apache.org/docs/format/Columnar.html). | ||
| //! For example, the type `Int16Array` represents an Apache | ||
| //! Arrow array of 16-bit integers. | ||
| //! # Downcasting an Array |
There was a problem hiding this comment.
I feel it is important to highlight this from the outset, as it can be unclear for a new user given an Array how to actually do something with it 😆
| //! # use arrow::array::ListArray; | ||
| //! # use arrow::datatypes::Int32Type; | ||
| //! # | ||
| //! Int32Array::from(vec![1, 2]); |
There was a problem hiding this comment.
These new APIs are 👌
| //! let array = Arc::new(Int32Array::from_iter([1, 2, 3])) as ArrayRef; | ||
| //! | ||
| //! // Slice with offset 1 and length 2 | ||
| //! let sliced = array.slice(1, 2); |
There was a problem hiding this comment.
It is perhaps a little bit unfortunate that this returns ArrayRef even when called on a concrete type, but then again I'm not sure of many use-cases for slicing concretely type arrays 😆
alamb
approved these changes
Jun 10, 2022
| //! # use arrow::array::ListArray; | ||
| //! # use arrow::datatypes::Int32Type; | ||
| //! # | ||
| //! Int32Array::from(vec![1, 2]); |
| //! | ||
| //! ## Field, Schema and RecordBatch | ||
| //! It is often the case that code wishes to handle any type of array, without necessarily knowing |
There was a problem hiding this comment.
thank you for this -- it is a good contribution
| //! # Safety and Security | ||
| //! | ||
| //! Like many crates, this crate makes use of unsafe where prudent. However, it endeavours to be | ||
| //! sound. Specifically, **it should not be possible to trigger undefined behaviour using safe APIs.** |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The module level documentation for arrow whilst accurate I felt could be improved. In particular: