►Rebellion
▼4 Collections
►4.5 Vector Builders
On this page:
vector-builder?
make-vector-builder
vector-builder-add
vector-builder-add-all
build-vector
build-mutable-vector
4.5.1 Legacy APIs
unused-vector-builder/  c
8.12
  top  contents    up   

4.5 Vector Builders🔗ℹ

 (require rebellion/collection/vector/builder)
  package: rebellion

A vector builder is a mutable object for creating vectors. Values can be added to a builder incrementally with vector-builder-add, and vectors can be built from a builder with build-vector. Builders can be reused — a single builder can build many vectors, and elements can be added to the builder after its already built vectors. Each built vector contains at least as many elements as every vector built before it.

Vector builders try to efficiently minimize allocation when adding more elements to a builder. Constructing a vector of size N using a builder consumes an amount of space linear in N.

procedure

(vector-builder? v) → boolean?

  v : any/c
A predicate for vector builders.

procedure

(make-vector-builder [initial-contents 
  #:expected-size expected-size]) 
 → vector-builder?
  initial-contents : (sequence/c any/c) = empty-list
  expected-size : (or/c natural? #f) = #f
Constructs a new vector builder containing initial-contents. If expected-size is given, the builder uses it as a hint of how many elements it will eventually contain and adjusts its reserved space accordingly. The expected-size paramater need only be an estimate; an incorrect guess will never cause the builder to produce different results. However, an accurate guess will allow the builder to minimize wasted space.

procedure

(vector-builder-add builder v ...) → vector-builder?

  builder : vector-builder?
  v : any/c
Adds each v to builder and returns builder. This mutates the builder! The builder is returned as a convenience to the caller when used with operations like for/fold.

Examples:
(define builder (make-vector-builder))

 

> (vector-builder-add builder 1 2 3)

#<vector-builder>

> (vector-builder-add builder 4 5 6)

#<vector-builder>

> (build-vector builder)

'#(1 2 3 4 5 6)

procedure

(vector-builder-add-all builder elements) → vector-builder?

  builder : vector-builder?
  elements : (sequence/c any/c)
Adds elements to builder and returns builder. This mutates the builder! The builder is returned as a convenience to the caller when used with operations like for/fold.

Examples:
(define builder (make-vector-builder))

 

> (vector-builder-add-all builder (in-range 0 5))

#<vector-builder>

> (vector-builder-add-all builder (in-range 5 10))

#<vector-builder>

> (build-vector builder)

'#(0 1 2 3 4 5 6 7 8 9)

procedure

(build-vector builder) → immutable-vector?

  builder : vector-builder?
Builds an immutable vector from builder. Does not mutate builder in any way, and builder can still be used to build additional vectors afterwards.

Examples:
(define builder (make-vector-builder))

 

> (build-vector (vector-builder-add builder 1 2 3))

'#(1 2 3)

> (build-vector (vector-builder-add builder 4 5 6))

'#(1 2 3 4 5 6)

procedure

(build-mutable-vector builder)

 → (and/c vector? (not/c immutable?))
  builder : vector-builder?
Builds a mutable vector from builder. Does not mutate builder in any way, and builder can still be used to build additional vectors afterwards.

Examples:
(define builder (make-vector-builder))

 

> (build-mutable-vector (vector-builder-add builder 1 2 3))

'#(1 2 3)

> (build-mutable-vector (vector-builder-add builder 4 5 6))

'#(1 2 3 4 5 6)

4.5.1 Legacy APIs🔗ℹ

value

unused-vector-builder/c : predicate/c

Deprecated. Alias for vector-builder?, use that instead.

  top  contents    up