1 Tables

8.12

1 Tables🔗ℹ

package: scone

Tables are the core data type in scone, they represent simple tabular data in a similar manner to CSV files. There are two table types, row-oriented and column-oriented, although the former has more support at this time than the latter. Tables are intended to be as light-weight as possible with very simple schema-like definitions and to use a mix of lists and vectors for the main data.

1.1 Table Types🔗ℹ

struct
(struct table (def rows)
    #:transparent)
  def : tabledef?
  rows : (listof row/c)

Construct a row-oriented table from the given Table Definition and list of rows. Each row must have the same number of columns as the definition and each value must conform to the corresponding Column Definition.

Layout

,-------------------------------------------------------------------,

|-----------------+-----------+------------+------------+-----------|

'-------------------------------------------------------------------'

struct
(struct columnar-table (def columns)
    #:transparent)
  def : tabledef?
  columns : (vectorof list?)

Construct a column-oriented table from the given Table Definition and vector of column data. The vector of column data must have the same number of values as the definition has columns and each value is a list where every value must conform to the corresponding Column Definition.

Layout

,----------------------------------------------------------,

|--------+-----------+------------+------------+-----------|

| |-----------+------------+------------+-----------|

'----------------------------------------------------------'

procedure
(table-name table) → table-name/c
table : table-type/c

Return the name of this table, from it’s tabledef.

procedure
(table-columns table) → (listof columndef?)
table : table-type/c

Return the list of columns in this table, from it’s tabledef.

procedure
(table-column-count table) → exact-nonnegative-integer?
table : table-type/c

Return the number of columns in this table, from it’s tabledef.

procedure
(table-has-column? table name) → boolean?
table : table-type/c
name : column-name/c

Return #t if this table has a column named name, else #f.

procedure
(table-column-def table name)
→ (or/c (cons/c exact-nonnegative-integer? columndef?) #f)
table : table-type/c
name : column-name/c

Find the columndef for the column named name. If found return the columndef and the index of the column in the tabledef. If not found return #f.

procedure
(table-column-index table name)
→ (or/c exact-nonnegative-integer? #f)
table : table-type/c
name : column-name/c

Find the columndef for the column named name. If found return the index of the column in the tabledef. If not found return #f.

procedure
(table-row-count table) → exact-nonnegative-integer?
table : table-type/c

Returns the number of rows in this table.

1.1.1 Rows and Values🔗ℹ

procedure
(row-validate tabledef row) → row/c
tabledef : tabledef?
row : row/c

Validate the values in the row with the column definitions for the given table.

1.2 Table Definition🔗ℹ

A table definition structure, tabledef, acts as the schema for a table or columnar-table.

struct
(struct tabledef (name columns)
    #:transparent)
  name : column-name/c
  columns : (listof columndef?)

The table definition contains the table’s name and a vector of columndef values.

constructor
(make-tabledef columns [name]) → tabledef?
columns : (listof columndef-from/c)
name : table-name/c = (next-table-name)

Construct a new tabledef, if no name is supplied one will be generated using next-table-name.

constructor
(make-tabledef-from row) → tabledef?
row : row/c

Given a row from a table, infer a table definition from the values in the row.

procedure
(tabledef-column-count def) → exact-nonnegative-integer?
def : tabledef?

Return the number of columns in this table definition.

procedure
(tabledef-has-column? def name) → boolean?
def : tabledef?
name : column-name/c

Return #t if this table definition has a column named name, else #f.

procedure
(tabledef-column-def def name)
→ (or/c (cons/c exact-nonnegative-integer? columndef?) #f)
def : tabledef?
name : column-name/c

Find the columndef for the column named name. If found return the columndef and the index of the column in the table definition. If not found return #f.

procedure
(tabledef-column-index def name)
→ (or/c exact-nonnegative-integer? #f)
def : tabledef?
name : column-name/c

Find the columndef for the column named name. If found return the index of the column in the table definition. If not found return #f.

procedure
(next-table-name) → (table-name/c)

Return a newly created table name using the value of the parameter default-table-name with a suffix of the form "\"_❬nn❭\"".

1.3 Column Definition🔗ℹ

A column definition structure, columndef, acts as the schema for a single column within a table’s tabledef.

struct
(struct columndef (name data-type is-list)
    #:transparent)
  name : column-name/c
  data-type : data-type/c
  is-list : boolean?

...

constructor
(make-columndef name [data-type is-list?]) → columndef?
  name : column-name/c
  data-type : data-type/c = (default-column-data-type)
  is-list? : boolean/c = #f

...

constructor
(make-columndef-from value index) → columndef?
value : value/c
index : exact-nonnegative-integer?

...

1.4 Table Contracts🔗ℹ

contract
(columndef-from/c value) → boolean?
value : any/c

Returns #t if the provided data value conforms to the following contract.

(or/c
   column-name/c
   (list/c column-name/c)
   (list/c column-name/c data-type/c)
   (list/c column-name/c data-type/c boolean?))

contract
(column-name/c value) → boolean?
value : any/c

Returns #t if the provided value is a valid column name.

contract
(data-type/c value) → boolean?
value : any/c

Returns #t if the provided value is a valid column data type. Valid values are currently:

'boolean, accepts the standard boolean values #t and #f
'number, accepts any numeric value
'string, accepts any string value
'symbol, accepts any symbol value

contract
(row/c value) → boolean?
value : any/c

Returns #t if the provided value is a vector where each value is a value/c.

contract
(table-name/c value) → boolean?
value : any/c

Returns #t if the provided value is a valid table name.

contract
(table-type/c value) → boolean?
value : any/c

Returns #t if the provided value is a valid type of table – currently either table or columnar-table.

contract
(value/c value) → boolean?
value : any/c

Returns #t if the provided data value corresponds to the types in data-type/c, and may be individual values or homogeneous lists.

1.5 Table Defaults🔗ℹ

parameter
(default-column-data-type) → data-type/c
(default-column-data-type data-type) → void?
data-type : data-type/c
= 'string

...

parameter
(default-column-prefix) → column-name/c
(default-column-prefix column-prefix) → void?
column-prefix : column-name/c
= 'column

...

parameter
(default-table-name) → table-name/c
(default-table-name table-name) → void?
table-name : table-name/c
= 'unnamed

...

1	Tables
2	Table I/ O
3	Table Queries
4	License

1.1	Table Types
1.2	Table Definition
1.3	Column Definition
1.4	Table Contracts
1.5	Table Defaults