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.

Sign up for GitHub

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

Document that useAsCStringLen does not append NUL #612

Merged
merged 2 commits into from
Sep 15, 2023
Merged

Document that useAsCStringLen does not append NUL #612

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9e6c00c
Document that useAsCStringLen does not append NUL
Bodigrim Sep 15, 2023
2f52feb
Update Data/ByteString.hs
Bodigrim Sep 15, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions Data/ByteString.hs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1797,9 +1797,13 @@ useAsCString (BS fp l) action =
pokeByteOff buf l (0::Word8)
action (castPtr buf)

-- | /O(n) construction/ Use a @ByteString@ with a function requiring a @CStringLen@.
-- As for @useAsCString@ this function makes a copy of the original @ByteString@.
-- | /O(n) construction/ Use a @ByteString@ with a function requiring a 'CStringLen'.
-- As for 'useAsCString' this function makes a copy of the original @ByteString@.
-- It must not be stored or used after the subcomputation finishes.
--
-- Beware that this function does not add a terminating @\NUL@ byte at the end of 'CStringLen'.
Copy link
Member

Choose a reason for hiding this comment

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

It looks like the implementation actually does currently append a null byte, but I agree that doing so is not part of this function's contract.

Suggested change
-- Beware that this function does not add a terminating @\NUL@ byte at the end of 'CStringLen'.
-- Beware that this function is not required to add a terminating @\NUL@ byte at the end of the 'CStringLen' it provides.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Right, it's ShortByteString version who does not add it, but ByteString one currently does.

-- If you need to construct a pointer to a null-terminated sequence, use 'useAsCString'
-- (and measure length independently if desired).
useAsCStringLen :: ByteString -> (CStringLen -> IO a) -> IO a
useAsCStringLen p@(BS _ l) f = useAsCString p $ \cstr -> f (cstr,l)

Expand Down
8 changes: 6 additions & 2 deletions Data/ByteString/Short/Internal.hs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1766,10 +1766,14 @@ useAsCString sbs action =
action buf
where l = length sbs

-- | /O(n) construction./ Use a @ShortByteString@ with a function requiring a @CStringLen@.
-- As for @useAsCString@ this function makes a copy of the original @ShortByteString@.
-- | /O(n) construction./ Use a @ShortByteString@ with a function requiring a 'CStringLen'.
-- As for 'useAsCString' this function makes a copy of the original @ShortByteString@.
-- It must not be stored or used after the subcomputation finishes.
--
-- Beware that this function does not add a terminating @\NUL@ byte at the end of 'CStringLen'.
-- If you need to construct a pointer to a null-terminated sequence, use 'useAsCString'
-- (and measure length independently if desired).
--
-- @since 0.10.10.0
useAsCStringLen :: ShortByteString -> (CStringLen -> IO a) -> IO a
useAsCStringLen sbs action =
Expand Down
Loading