CString structv0.1.0
pub struct CString {
pub data: *var char8;
pub length: uint;
pub allocator: Allocator;
}
Move-only: it explicitly prohibits copying, owns its block, and gives it back when it dies. The terminator is
part of the block and not part of the text, so Length answers without it.
Fields
| Name | Type | Description |
|---|---|---|
data | *var char8 | The bytes, ending with the one zero byte the text does not contain. Null only for a CString that was consumed by a move; every constructor allocates, since even empty C text is one byte long. |
length | uint | How many bytes of text come before the terminator. |
allocator | Allocator | Where the block came from, and where it goes back to. |
Associated functions
FromText
pub func FromText(
allocator: Allocator,
text: char8[..]
) -> CString ! TextError
A terminated copy of text, or why the text cannot cross the boundary.
Refuses a zero byte for the reason FromView does: text that ends early on the C side of the boundary is
how a checked name and a used name part company.
| Name | Type | Description |
|---|---|---|
allocator | Allocator | where the storage comes from |
text | char8[..] | the text to act on |
Returns: the terminated copy, or a failure when the text holds an interior zero byte
FromView
pub func FromView(
allocator: Allocator,
view: StringView
) -> CString ! TextError
A terminated copy of view, or why the text cannot cross the boundary.
Fails with InvalidUtf8 when the text contains a zero byte — refused rather than truncated,
because text that ends early on the C side of the boundary is the classic way a checked name and a used name
part company. Reports OutOfMemory when the copy cannot be made.
Runs in time proportional to the length — one pass to check, one to copy — and allocates once.
| Name | Type | Description |
|---|---|---|
allocator | Allocator | where the storage comes from |
view | StringView | the borrowed text to act on |
Returns: the terminated copy, or a failure when the text holds an interior zero byte
FromRaw
pub func FromRaw(
allocator: Allocator,
raw: *char8,
limit: uint
) -> CString ! TextError
A copy of the C text at raw, read to its terminator, or why it is not text.
raw is borrowed for the call and its bytes are copied, so the C side keeps whatever it handed over.
limit bounds the search for the terminator: C promises one exists, and this is what the promise costs when
it is broken — reports InvalidUtf8 after limit bytes rather than reading memory forever. Bytes that are
not UTF-8 are refused the same way, since nothing about C promises text.
| Name | Type | Description |
|---|---|---|
allocator | Allocator | where the storage comes from |
raw | *char8 | the null-terminated bytes to copy |
limit | uint | the most bytes to read before giving up on finding a terminator |
Returns: the copy, or a failure when no terminator was found within limit
Methods
Length
pub func Length(self: &CString) -> uint
How many bytes of text come before the terminator.
Returns: how many bytes precede the terminator
Raw
pub func Raw(self: &CString) -> *char8
The pointer C expects: the text, then one zero byte.
Borrowed. Valid until this CString is released or dies, and no longer — C code that keeps it past that is
keeping a pointer into a freed block.
Returns: the address to hand to a C interface, which stays valid while this does
View
pub func View(self: &CString) -> StringView
The text without its terminator, as a view.
The view borrows this CString and must not outlive it.
Returns: the bytes as text, without the terminator
Clear
pub func Clear(self: &var CString)
Gives the block back and leaves a CString that owns nothing.
Safe to call twice, since what it leaves behind owns nothing.
Destructor
func ~CString(self: &var CString)
Gives the block back.