WithCapacity v0.1.0

Package: Text

Signature

func WithCapacity(
    capacity: uint
) -> StringBuilder;

Parameters

Returns

An empty StringBuilder holding a block of capacity bytes. It is empty — Length is 0 — but Capacity is what was asked for, and appends that stay within it do not reallocate.

A capacity of 0 allocates nothing, which is New.

This is worth reaching for when the final size is known: String::Repeat sizes its builder this way, which is what makes it one allocation rather than one per round.

Example

import Text::StringBuilder;

func Main() -> int {
    var builder = StringBuilder::WithCapacity(64);
    builder.Length();   // 0
    builder.Capacity(); // 64

    builder.Append("Rux");
    builder.Capacity(); // 64 still -- the append fit

    builder.Free();
    return 0;
}

See also

• StringBuilder — the builder type
• New — an empty builder that allocates nothing
• Reserve — reserve more room on a builder that already exists
• Shrink — hand back the capacity that went unused