Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add better documentation, examples and builer-style API to ByteView #6479

Merged
merged 8 commits into from
Oct 1, 2024

Conversation

alamb
Copy link
Contributor

@alamb alamb commented Sep 28, 2024

Which issue does this PR close?

Closes #6478

Rationale for this change

Rationale for this change

While working with StringViewArray's downstream in DataFusion, I found it was not always clear that ByteView exists for creating/destructuring with the u128s so I wanted to write some additional documentation
I also found it quite awkward to write the examples (specifically setting the prefix) so I added some BuilderStyle APIs as well

This is what creating ByteViews looks like without the builder APIs :vomit:

let view = ByteView {
   length: 12,
   // convert 4 byte &str to u32
   prefix: u32::from_le_bytes(prefix.as_bytes().try_into().unwrap()),
   buffer_index: 3,
   offset: 42,
};

What changes are included in this PR?

  1. Add pointer to GenericByteViewArray from docs
  2. Add examples of using ByteView
  3. Add builder style APIs to ByteView

Are there any user-facing changes?

There are several new functions on ByteView

@github-actions github-actions bot added the arrow Changes to the arrow crate label Sep 28, 2024
buffer_index: 3,
offset: 1,
};
let view = ByteView::new(13, &v.as_bytes()[0..4])
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is an example of the kind of improvement the new API allows (aka not having to know to do try_into/unwrap for byte slices

@alamb
Copy link
Contributor Author

alamb commented Sep 28, 2024

FYI @XiangpengHao

Copy link
Contributor

@tustvold tustvold left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like it

@alamb
Copy link
Contributor Author

alamb commented Sep 30, 2024

Thank you for the review @tustvold

};
let v: Vec<u8> = vec![
// invalid UTF8
0xf0, 0x80, 0x80, 0x80, // more bytes to make it larger than 12
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was actually an invalid ByteView (the length is less than 12 but the prefix is only 4), so I updated the test

@alamb alamb merged commit 1e9e5a2 into apache:master Oct 1, 2024
26 checks passed
@alamb
Copy link
Contributor Author

alamb commented Oct 1, 2024

Thanks again @tustvold and @XiangpengHao

@alamb alamb deleted the alamb/view_docs branch October 1, 2024 20:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
arrow Changes to the arrow crate
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Make it easier to find / work with ByteView
3 participants