►Rebellion
▼4 Collections
On this page:
vector-builder?
unused-vector-builder/  c
make-vector-builder
vector-builder-add
vector-builder-add-all
build-vector
build-mutable-vector
7.7
  top  ← prev  up  next → 

4.5 Vector Builders

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

A vector builder is a single-use object for building a vector. First create a builder with make-vector-builder, then repeatedly add elements to it with vector-builder-add or vector-builder-add-all, and finally construct a vector using either build-vector or build-mutable-vector.

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

Vector builders are linear objects. Each operation on a vector builder destructively uses the builder and returns an updated, unused builder. Used builders cannot be reused; attempting to do so may raise a contract error, but this is not guaranteed.

Examples:
> (define builder (make-vector-builder))
> (define builder2 (vector-builder-add builder 1 2 3))
> (vector-builder-add builder 1 2 3)

vector-builder-add: contract violation;

 this builder has already been used

  builder: #<vector-builder>

  in: the 1st argument of

      (->

       unused-vector-builder/c

       any/c

       ...

       unused-vector-builder/c)

  contract from:

      <pkgs>/rebellion/private/vector-builder.rkt

  blaming: top-level

   (assuming the contract is correct)

  at: <pkgs>/rebellion/private/vector-builder.rkt:12.3

procedure

(vector-builder? v) → boolean?

  v : any/c
A predicate for vector builders.

value

unused-vector-builder/c : flat-contract?

A flat contract for vector builders that are unused. Passing a vector builder as an input to functions like vector-builder-add and build-vector uses the builder, and the unused-vector-builder/c contract can detect when a builder has already been used. Detection is not guaranteed, because those functions may or may not choose to mutate the original builder and reuse it instead of allocating a new builder.

procedure

(make-vector-builder [initial-contents 
  #:expected-size expected-size]) 
 → unused-vector-builder/c
  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 allocations and wasted space.

procedure

(vector-builder-add builder v ...) → unused-vector-builder/c

  builder : unused-vector-builder/c
  v : any/c
Adds each v to builder and returns an updated vector builder. The original builder is consumed in the process and must not be reused.

Examples:
> (define builder (make-vector-builder))
> (vector-builder-add builder 1 2 3)

#<vector-builder>

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

vector-builder-add: contract violation;

 this builder has already been used

  builder: #<vector-builder>

  in: the 1st argument of

      (->

       unused-vector-builder/c

       any/c

       ...

       unused-vector-builder/c)

  contract from:

      <pkgs>/rebellion/private/vector-builder.rkt

  blaming: top-level

   (assuming the contract is correct)

  at: <pkgs>/rebellion/private/vector-builder.rkt:12.3

procedure

(vector-builder-add-all builder seq) → unused-vector-builder/c

  builder : unused-vector-builder/c
  seq : (sequence/c any/c)
Adds each element of seq to builder and returns an updated vector builder. The original builder is consumed in the process and must not be reused.

Examples:
> (define builder (make-vector-builder))
> (vector-builder-add-all builder (in-range 0 20))

#<vector-builder>

> (vector-builder-add-all builder (in-range 20 40))

vector-builder-add-all: contract violation;

 this builder has already been used

  builder: #<vector-builder>

  in: the 1st argument of

      (->

       unused-vector-builder/c

       (sequence/c any/c)

       unused-vector-builder/c)

  contract from:

      <pkgs>/rebellion/private/vector-builder.rkt

  blaming: top-level

   (assuming the contract is correct)

  at: <pkgs>/rebellion/private/vector-builder.rkt:14.3

procedure

(build-vector builder) → immutable-vector?

  builder : unused-vector-builder/c
Builds an immutable vector from builder, consuming the builder in the process.

Examples:
> (define builder
    (vector-builder-add-all (make-vector-builder) (in-range 0 10)))
> (build-vector builder)

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

> (build-vector builder)

build-vector: contract violation;

 this builder has already been used

  builder: #<vector-builder>

  in: the 1st argument of

      (->

       unused-vector-builder/c

       immutable-vector?)

  contract from:

      <pkgs>/rebellion/private/vector-builder.rkt

  blaming: top-level

   (assuming the contract is correct)

  at: <pkgs>/rebellion/private/vector-builder.rkt:16.3

procedure

(build-mutable-vector builder)

 → (and/c vector? (not/c immutable?))
  builder : unused-vector-builder/c
Builds a mutable vector from builder, consuming the builder in the process.

Examples:
> (define builder
    (vector-builder-add-all (make-vector-builder) (in-range 0 10)))
> (build-mutable-vector builder)

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

> (build-mutable-vector builder)

build-mutable-vector: contract violation;

 this builder has already been used

  builder: #<vector-builder>

  in: the 1st argument of

      (->

       unused-vector-builder/c

       (and/c vector? (not/c immutable?)))

  contract from:

      <pkgs>/rebellion/private/vector-builder.rkt

  blaming: top-level

   (assuming the contract is correct)

  at: <pkgs>/rebellion/private/vector-builder.rkt:17.3

  top  ← prev  up  next →