SkySpark by SkyFoundry

mixin haystack::Grid

haystack::Grid

@Js

Two dimensional tabular data structure composed of Cols and Rows. Grids may be created by factory methods on Etc. See docSkyspark

addCol

Grid addCol(Str name, Obj? meta, |Row,Int->Obj?| f)

Return a new grid with an additional column. The cells of the column are created by calling the mapping function for each row. The meta may be any value accepted by Etc.makeDict

addColMeta

Grid addColMeta(Obj col, Obj? meta)

Return a new grid with additional column meta-data. The col parameter may be either a Col or column name. The meta may be any value accepted by Etc.makeDict

addMeta

Grid addMeta(Obj? meta)

Return a new grid with additional grid level meta-data. The meta may be any value accepted by Etc.makeDict

all

Bool all(|Row,Int->Bool| f)

Return true if the function returns true for all of the rows in the grid. If the grid is empty, return false.

any

Bool any(|Row,Int->Bool| f)

Return true if the function returns true for any of the rows in the grid. If the grid is empty, return false.

col

abstract Col? col(Str name, Bool checked := true)

Get a column by its name. If not resolved then return null or throw UnknownNameErr based on checked flag.

colDisNames

Str[] colDisNames()

Convenience for cols mapped to Col.dis. The resulting list is safe for mutating.

colNames

Str[] colNames()

Convenience for cols mapped to Col.name. The resulting list is safe for mutating.

colToList

Obj?[] colToList(Obj col)

Get a column as a list of the cell values ordered by row.

cols

abstract Col[] cols()

Columns

colsToLocale

Grid colsToLocale()

Return a new Grid wich each col name mapped to its localized tag name if the col does not already have a display string. See Etc.tagToLocale and Localization.

commit

Grid commit(Grid diffs)

Return a new Grid which is the result of applying the given diffs to this grid. The diffs must have the same number of rows as this grid. Any cells in the diffs with a Remove.val are removed from this grid, otherwise they are updated/added.

each

abstract Void each(|Row,Int| f)

Iterate the rows

eachWhile

abstract Obj? eachWhile(|Row,Int->Obj?| f)

Iterate every row until the function returns non-null. If function returns non-null, then break the iteration and return the resulting object. Return null if the function returns null for every item

find

Row? find(|Row,Int->Bool| f)

Find one matching row or return null if no matches. Also see findIndex and findAll.

findAll

Grid findAll(|Row,Int->Bool| f)

Return a new grid which finds matching the rows in this grid. The has the same meta and column definitions. Also see find.

findIndex

Int? findIndex(|Row,Int->Bool| f)

Find one matching row index or return null if no matches. Also see find.

first

abstract Row? first()

Get the first row or return null if grid is empty.

get

@Operator
abstract Row get(Int index)

Get a row by its index number. Throw UnsupportedErr is the grid doesn't support indexed based row access.

getRange

@Operator
Grid getRange(Range r)

Return a new grid which is a slice of the rows in this grid. Negative indexes may be used to access from the end of the grid. The has the same meta and column definitions.

getSafe

abstract Row? getSafe(Int index)

Get a row by its index number or if index is out of bounds then return null. Throw UnsupportedErr is the grid doesn't support indexed based row access.

has

Bool has(Str name)

Return if this grid contains the given column name.

isEmpty

Bool isEmpty()

Convenience for size equal to zero.

isErr

Bool isErr()

Return if this is an error grid - meta has "err" tag.

join

Grid join(Grid that, Obj joinCol)

Join two grids by column name. The joinCol parameter may be a Col or col name. Current implementation requires:

  • grids cannot have conflicting col names (other than join col)
  • each row in both grids must have a unique value for join col
  • grid level meta is merged
  • join column meta is merged
keepCols

Grid keepCols(Obj[] toKeep)

Return a new grid with all the columns removed except the given columns. The toKeep columns can be Col instances or column names. Columns not found are silently ignored.

last

virtual Row? last()

Get the last row or return null if grid is empty. Throw UnsupportedErr is the grid doesn't support indexed based row access.

map

Grid map(|Row,Int->Obj?| f)

Return a new grid which maps the rows to new Dict. The grid meta and existing column meta are maintained. New columns have empty meta. If the mapping function returns null, then the row is removed.

meta

abstract Dict meta()

Meta-data for entire grid

missing

Bool missing(Str name)

Return if this grid does not contains the given column name.

removeCol

Grid removeCol(Obj col)

Return a new grid with the given column removed. The col parameter may be either a Col or column name. If column doesn't exist return this grid.

removeCols

Grid removeCols(Obj[] toRemove)

Return a new grid with all the given columns removed. The toRemove columns can be Col instances or column names. Columns not found are silently ignored.

renameCol

Grid renameCol(Obj oldCol, Str newName)

Return a new grid with the given column renamed. The oldCol parameter may be a Col or col name.

reorderCols

Grid reorderCols(Obj[] cols)

Return a new grid with the columns reordered. The given list of names represents the new order and must contain the same current Col instances or column names.

size

abstract Int size()

Get the number of rows in the grid. Throw UnsupportedErr if the grid doesn't support a size.

sort

Grid sort(|Row,Row->Int| f)

Return a new Grid which is a copy of this grid with the rows sorted by the given comparator function.

sortCol

Grid sortCol(Obj col)

Convenience for sort which sorts the given column by value. The col parameter can be a Col or a str name.

sortDis

Grid sortDis()

Sort using Etc.compareDis and Dict.dis.

sortr

Grid sortr(|Row,Row->Int| f)

Return a new Grid which is a copy of this grid with the rows reverse sorted by the given comparator function.

unique

Grid unique(Obj[] keyCols)

Return a new grid with only rows that define a unique key by the given key columns. If multiple rows have the same key cells, then the first row is returned and subsequent rows are removed. The keyCols can be Col instances or column names.