WithCapacity

Creates an empty builder with room reserved up front.

Module: Text

Signature

func WithCapacity(capacity: uint) -> StringBuilder;

Parameters

Name	Type	Description
capacity	uint	How many bytes to reserve.

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;

var builder = StringBuilder::WithCapacity(64);
builder.Length();   // 0
builder.Capacity(); // 64

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

builder.Free();

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