@Axon
static Number? _as(Number? val, Obj? unit)

Set the unit of a number. Unlike to() function, no conversion of the scalar of the number is performed. The target unit can be a unit string or a number in which case the scalar value of the unit parameter is ignored (by convention should be 1).

Examples:

75°F.as(1°C)
75°F.as("°C")

@Axon { admin=true }
static Obj? _echo(Obj? x)

Write the str represenation of x to stdout and return x.

@Axon
static Obj? _equals(Obj? a, Obj? b)

Return if two values are equivalent. Unlike the standard == operator this function will compare the contents of collection values such as lists, dicts, and grids. For non-collection values, the result is the same as the == operator. This function does not work with lazy grids such as hisRead result.

@Axon
static Obj? _toStr(Obj? val)

Convert an obj to its string representation

@Axon
static Obj? _trap(Obj? val, Str name)

Function for the -> operator. If the given value is a dict, then get a value by name, or throw UnknownNameErr if name not mapped. If the value is a Ref, then perform a checked readById, then perform the name lookup.

The trap function maybe be accessed using the -> shortcut operator:

dict->foo  >>>  dict.trap("foo")

See Axon Language.

@Axon
static Obj? abs(Number? val)

Return absolute value of a number, if null return null

@Axon
static Obj? add(Obj? val, Obj? item)

Add item to the end of a list and return a new list.

@Axon
static Obj? addAll(Obj? val, Obj? items)

Add all the items to the end of a list and return a new list.

@Axon
static Grid addCol(Grid grid, Obj? col, Fn fn)

Add a column to a grid by mapping each row to a new cell value. The col parameter may be a simple String name or may be a dictionary which must have a "name" tag (any other tags become column meta-data). The mapping function takes (row) and returns the new cell values for the column.

Examples:

// add new column named areaMeter
readAll(site).addCol("areaMeters") s => s->area.to(1m²)

// add new column named areaMeter with dis meta
readAll(site).addCol({name:"areaMeters", dis:"Area Meters"}) s => s->area.to(1m²)

@Axon
static Obj addColMeta(Obj grid, Str name, Dict meta)

Return a new grid with additional column meta-data. If column not found, then return given grid. Column meta is added using merge conventions. Also see setColMeta and Streams.

@Axon
static Grid addCols(Grid a, Grid b)

Add grid b as a new set of columns to grid a. If b contains duplicate column names, then they are given auto-generated unique names. If b contains fewer rows then a, then the missing cells are filled with null.

Examples:

[{a:0, b:2}, {a:1, b:3}].toGrid.addCols({c:4}.toGrid)
readAll(rtu).addCols(readAll(meter))

@Axon
static Obj addMeta(Obj grid, Dict meta)

Return new grid with additional grid level meta-data tags. Tags are added using merge conventions. Also see setMeta and Streams.

Example:

read(temp).hisRead(today).addMeta({view:"table"})

@Axon
static Grid addRow(Grid grid, Dict newRow)

Add an additional Dict row to the end of a grid.

Example:

readAll(site).addRow({dis:"New Row"})

@Axon
static Grid addRows(Grid grid, Obj newRows)

Add an list of rows to the end of a grid. The newRows may be expressed as list of Dict or a Grid.

Example:

readAll(site).addRows(readAll(equip))

@Axon
static Obj? all(Obj val, Fn fn)

Return if all the items in a list, dict, or grid match the given test function. If the collection is empty, then return true.

If working with a list, the function takes (val) or (val, index) and returns true or false.

If working with a dict, the function takes (val) or (val, name) and returns true or false.

If working with a grid, the function takes (row) or (row, index) and returns true or false.

If working with a string, the function takes (char) or (char, index) and returns true or false.

If working with a stream, then function takes (val) and returns true or false. See Streams.

Examples:

[1, 3, 5].all v => v.isOdd  >>  true
[1, 3, 6].all(isOdd)        >>  false

@Axon
static Obj? any(Obj val, Fn fn)

Return if any the items in a list, dict, or grid match the given test function. If the collection is empty, then return false.

If working with a list, the function takes (val) or (val, index) and returns true or false.

If working with a dict, the function takes (val) or (val, name) and returns true or false.

If working with a grid, the function takes (row) or (row, index) and returns true or false.

If working with a string, the function takes (char) or (char, index) and returns true or false.

If working with a stream, then function takes (val) and returns true or false. See Streams.

Examples:

[1, 3, 5].any v => v.isOdd  >>  true
[2, 4, 6].any(isOdd)        >>  false

@Axon { meta=["foldOn":"Number"] }
static Obj? avg(Obj? val, Obj? acc)

Fold multiple values into their standard average or arithmetic mean. This function is the same as math::mean. Null values are ignored. Return null if no values.

Example:

[7, 2, 3].fold(avg)  >>  4

@Axon
static Obj? call(Obj func, Obj?[]? args := null)

Reflectively call a function with the given arguments. The func may be a Str name or an expression that evaluates to a function. Args is a positional list for each argument. Examples:

call("today")
call("replace", ["hi there", "hi", "hello"])
call("parseDate", ["2021-03-15"])
call("parseDate", ["15-Mar-21", "DD-MMM-YY"])
call(parseDate, ["15-Mar-21", "DD-MMM-YY"])
call(parseDate(_, "DD-MMM-YY"), ["15-Mar-21"])

@Axon
static Str capitalize(Str val)

Return this string with the first character converted to uppercase. The case conversion is for ASCII only. Also see decapitalize() and upper().

Examples:

capitalize("apple")  >>  "Apple"

@Axon
static Number clamp(Number val, Number min, Number max)

Clamp the number val between the min and max. If its less than min then return min, if its greater than max return max, otherwise return val itself. The min and max must have matching units or be unitless. The result is always in the same unit as val.

Examples:

14.clamp(10, 20)     >>   14    // is between 10 and 20
3.clamp(10, 20)      >>   10    // clamps to min 10
73.clamp(10, 20)     >>   20    // clamps to max 20
45°F.clamp(60, 80)   >>   60°F  // min/max can be unitless

@Axon
static Col? col(Grid grid, Str name, Bool checked := true)

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

Example:

// get meta data for given columm
read(temp).hisRead(today).col("ts").meta

@Axon
static Str[] colNames(Grid grid)

Get the column names a list of strings.

Example:

readAll(site).colNames

@Axon
static Obj?[] colToList(Grid grid, Obj col)

Get a column as a list of the cell values ordered by row. Also see rowToList().

Example:

readAll(site).colToList("dis")

@Axon
static Obj collect(Obj? stream, Fn? to := null)

Collect stream into a in-memory list or grid. See Streams.

@Axon
static Col[] cols(Grid grid)

Get the columns from a grid as a list.

Example:

// get name of first column
readAll(site).cols.first.name

@Axon
static Grid colsToLocale(Grid grid)

Localize column display names. For each col which does not have an explicit dislay name, add a dis tag based on the column name. Also see Grid.colsToLocale and Localization.

@Axon
static Grid? compDef(Obj name, Bool checked := true)

Return component definition. The result is a grid where each row corresponds to a cell and its associated meta data. The grid meta is the function level meta data.

Example:

compDef("compName")

@Axon
static Str concat(List list, Str sep := "")

Concatenate a list of items into a string.

Examples:

[1, 2, 3].concat       >>  "123"
[1, 2, 3].concat(",")  >>  "1,2,3"

@Axon
static Def[] conjuncts()

List conjunct definitions in the context namespace as Def[].

@Axon
static Bool contains(Obj val, Obj? x)

Return if val contains x:

• if val is Str, then x is substring.
• if val is List, then x is item to search.
• if val is Range, then is x inside the range inclusively
• if val is DateSpan, then is x a date in the span

@Axon
static Coord coord(Number lat, Number lng)

Construct a Coord from two Numbers in decimal degrees

@Axon
static Number coordDist(Coord c1, Coord c2)

Compute the great-circle distance between two Coords. The result is a distance in meters using the haversine forumula.

@Axon
static Number coordLat(Coord coord)

Latitude of a Coord as a Number

@Axon
static Number coordLng(Coord coord)

Longitude of a Coord as a Number

@Axon { meta=["foldOn":"Obj"] }
static Obj? count(Obj val, Obj? acc)

Fold multiple values into their total count Return zero if no values.

@Axon
static Dict curFunc()

Get the current top-level function's tags.

@Axon
static Obj? date(Obj val, Number? month := null, Number? day := null)

If val is a DateTime: get date portion of the timestamp. If val is a Number: construct a date instance from year, month, day

Examples:

now().date         // same as today()
date(2010, 12, 1)  // same as 2010-12-01

@Axon
static Obj? dateTime(Date d, Time t, Str? tz := null)

Construct a DateTime from a date, time, and timezone name. If timezone is null, use system default.

@Axon
static Obj? day(Obj d)

Get day of month as integer between 1 to 31 from date or datetime.

@Axon
static Number dayOfYear(Obj val)

Given a DateTime or Date, return the day of the year. The result is a number between 1 and 365 (or 1 to 366 if a leap year).

@Axon
static Str debugType(Obj? val)

Return a string of the given value's type. No guarantee is made for the string's format. Applications must not assume any specific format, this function is for human consumption only.

@Axon
static Str decapitalize(Str val)

Return this string with the first character converted to lowercase. The case conversion is for ASCII only. Also see capitalize() and lower().

Examples:

decapitalize("Apple") >> "apple"

@Axon
static Def? def(Obj symbol, Bool checked := true)

Lookup a def by its symbol name (Str or Symbol). If not found return null or raise UnknownDefErr based on checked flag. The result is returned as the definition's normalized dict representation.

@Axon
static Def[] defs()

List all definitions in the context namespace as Def[].

@Axon
static Str dis(Dict? dict, Str? name := null, Str? def := "")

Get display string for dict or the given tag. If name is null, then return display text for the entire dict using Etc.dictToDis. If name is non-null then format the tag value using its appropiate toLocale method. Also see Dict.dis.

@Axon
static Bool dst(DateTime dt)

Return if a DateTime is in daylight saving time. For the given DateTime and its specific timezone, return true if the time is in daylight savings time or false if standard time.

@Axon
static Obj? each(Obj val, Fn fn)

Iterate the items of a collection:

• Grid: iterate the rows as (row, index)
• List: iterate the items as (value, index)
• Dict: iterate the name/value pairs (value, name)
• Str: iterate the characters as numbers (char, index)
• Range: iterate the integer range (integer)
• Stream: iterate items as (val); see Streams

@Axon
static Obj? eachDay(Obj dates, Fn fn)

Iterate the days of a span. The dates argument may be any object converted into a date range by toDateSpan. The given function is called with a Date argument for each iterated day.

Example:

f: day => echo(day)
eachDay(2010-07-01..2010-07-03, f) >> iterate Jul 1st, 2nd, 3rd
eachDay(2010-07, f)                >> iterate each day of July 2010
eachDay(pastWeek, f)               >> iterate last 7 days

@Axon
static Obj? eachMonth(Obj dates, Fn fn)

Iterate the months of a span. The dates argument may be any object converted into a date range by toDateSpan. The given function is called with a DateSpan argument for each interated month.

Examples:

// iterate each month in 2010, and echo data range
eachMonth(2010) d => echo(d)

// call f once for current method
eachMonth(today(), f)

@Axon
static Obj? eachWhile(Obj val, Fn fn)

Iterate the items of a collection until the given function returns non-null. Once non-null is returned, then break the iteration and return the resulting object. Return null if the function returns null for every item.

• Grid: iterate the rows as (row, index)
• List: iterate the items as (val, index)
• Dict: iterate the name/value pairs (val, name)
• Str: iterate the characters as numbers (char, index)
• Range: iterate the integer range (integer)
• Stream: iterate items as (val); see Streams

@Axon
static Obj? end(Obj? val)

End value of a DateSpan, Span, or a range.

@Axon
static Bool endsWith(Str val, Str sub)

Return if Str ends with the specified Str.

Examples:

"hi there".endsWith("there")   >>  true
"hi there".endsWith("hi")      >>  false

@Axon
static Obj? eval(Str expr)

Evaluate an Axon string expression. The evaluation happens in a new scope and does not have access to the current scope of local variables. Also see call() and toAxonCode().

Examples:

eval("2 + 2")
eval("now()")

@Axon
static Fn evalToFunc(Str expr)

Evalate an Axon string expression to a function. Typically the expression is just a function name, but it can be any expression that evaluates to a function. Raise an exception if the expression does not evaluate to a function. Note this call does evalute the given expression in the runtime, so it must be used with caution - never use it with a string from a non-trusted origin.

Examples:

evalToFunc("now").call
evalToFunc("(x, y)=>x+y").call([3, 4])
(evalToFunc("(x, y)=>x+y"))(3, 4)
evalToFunc("""replace(_, "x", "_")""").call(["xyz"])

@Axon
static Obj filter(Expr val, Expr filterExpr)

Apply a filter expression to a collection of dicts. The collection value may be any of the following:

• Grid: returns new grid with filtered rows
• Dict[]: returns list of filtered dicts (nulls are filtered out)
• Col[]: returns list of columns filtered by their meta
• Stream: filters stream of Dicts - see Streams

The filter parameter may one fo the following:

• Axon expression which maps to a filter
• Filter from parseFilter()
• Filter from parseSearch()

Examples:

// apply to a list of dicts
[{v:1}, {v:2}, {v:3}, {v:4}].filter(v >= 3)

// apply to a grid and return new grid with matching rows
readAll(equip).filter(meter)

// apply to a list of columns
read(ahu).toPoints.hisRead(yesterday).cols.filter(kind=="Bool")

// apply to a stream of dicts
readAllStream(equip).filter(siteMeter and elec and meter).collect

// apply search filter
readAll(equip).filter(parseSearch("RTU-1"))

@Axon
static Fn filterToFunc(Expr filterExpr)

Convert a filter expression to a function which maybe used with findAll or find. The returned function accepts one Dict parameter and returns true/false if the Dict is matched by the filter. Also see filter() and parseFilter().

Examples:

// filter for dicts with 'equip' tag
list.findAll(filterToFunc(equip))

// filter rows with an 'area' tag over 10,000
grid.findAll(filterToFunc(area > 10_000))

@Axon
static Obj? find(Obj val, Fn fn)

Find the first matching item in a list or grid by applying the given filter function. If no match is found return null.

If working with a list, the filter should be a function that takes (val) or (val, index). It should return true to match and return the item.

If working with a dict, the filter should be a function that takes (val) or (val, name). It should return true to match and return the item.

If working with a grid, the filter function takes (row) or (row, index) and returns true to match and return the row.

If working with a stream, the filter takes (val) and returns true to match. See Streams.

Examples:

// find first string longer than 3 chars
["ape", "bat", "charlie", "dingo"].find(x => x.size > 3)

// find first odd number
[10, 4, 3, 7].find(isOdd)

@Axon
static Obj? findAll(Obj val, Fn fn)

Find all the items in a list, dict, or grid by applying the given filter function. Also see find.

If working with a list, the filter should be a function that takes (val) or (val, index). It should return true to keep the item.

If working with a dict, the filter should be a function that takes (val) or (val, name). It should return the true to keep the name/value pair.

If working with a grid, the filter function takes (row) or (row, index) and returns true to keep the row. The resulting grid shares the original's grid meta and columns.

If working with a stream, the filter takes (val) and returns true to match. See Streams.

Examples:

// find all the strings longer than 3 chars
["ape", "bat", "charlie", "dingo"].findAll(x => x.size > 3)

// find even numbers
[0, 1, 2, 3, 4].findAll(isEven)

// find all the sites greater than 10,000ft from grid
readAll(site).findAll(s => s->area > 10_000ft²)

@Axon
static Obj? first(Obj? val)

Get the first item from an ordered collection or return null if the collection is empty:

• list: item at index 0
• grid: first frow
• stream: first item; see Streams

@Axon
static Date firstOfMonth(Date date)

Get the first day of given date's month. Also see lastOfMonth().

Example:

2009-10-28.firstOfMonth  >>  2009-10-01

@Axon
static Obj? flatMap(Obj val, Fn fn)

Map each item in a list or grid to zero or more new items as a flattened result.

If mapping a list, the mapping should be a function that takes (val) or (val, index). It should return the a list of zero or more new values. See List.flatMap.

If mapping a grid, the mapping function takes (row) or (row,index) and returns a list of zero or more new Dict rows. See Grid.flatMap.

If mapping a stream, the mapping functions takes (val). See Streams.

Examples:

[1, 2, 3].flatMap(v => [v, v+10])   >>  [1, 11, 2, 12, 3, 13]

@Axon
static Obj flatten(List list)

Flatten a list to a single level. If given a list of grids, then flatten rows to a single grid. Also see List.flatten and Etc.gridFlatten.

Examples:

// flatten a list of numbers
[1, [2, 3], [4, [5, 6]]].flatten  >>  [1, 2, 3, 4, 5, 6]

// flatten a list of grids
["Carytown", "Gaithersburg"].map(n=>readAll(siteRef->dis==n)).flatten

@Axon
static Obj? fold(Obj? val, Fn fn)

Fold a list or stream into a single value using given folding function. The folding function signature must be (val, acc) where val is the items being folded, and acc is an accumulator used to maintain state between iterations. Lifecycle of a fold:

1. Call fn(foldStart, null), return initial accumulator state
2. Call fn(item, acc) for every item, return new accumulator state
3. Call fn(foldEnd, acc) return final result

See Streams for streaming details.

The fold will short-circuit and halt immediately if the folding function returns na() for the accumulator state. The result of the fold is na() in this case. A folding function should document its behavior when a collection contains na().

Built-in folding functions include:

• count()
• sum()
• avg()
• min()
• max()
• mean()
• median()
• rootMeanSquareErr()
• meanBiasErr()
• standardDeviation()

Examples:

[1, 2, 3, 4].fold(max)  // fold list into its max value
[1, 2, 3, 4].fold(avg)  // fold list into its average value
[1, 2, na(), 3].fold(sum) // => na()

Example of writing your own custom fold function that used start/end values and has support for na():

average: (val, acc) => do
  if (val == foldStart()) return {sum:0, count:0}
  if (val == foldEnd()) return acc->sum / acc->count
  if (val == na()) return na()
  return {sum: acc->sum + val, count: acc->count + 1}
end

Also see reduce() which is easier to use if doing your own simple rollup computation.

@Axon
static Obj? foldCol(Grid grid, Str colName, Fn fn)

Fold the values of the given column into a single value. The folding function uses the same semantics as fold.

Example:

readAll(site).foldCol("area", sum)

@Axon
static Grid foldCols(Grid grid, Obj colSelector, Str newColName, Fn fn)

Fold a set of columns in each row into a new folded column and return a new grid. The columns to fold are selected by the colSelector function and removed from the result. The selector may be a list of string names or a function which takes a Col and returns true to select it. The folding function uses same semantics as fold.

Example:

// consider grid 'g' with the following structure:
a    b    c
---  ---  ---
1    10   100
2    20   200

// foldCols, add b and c together to create new bc column
g.foldCols(["b", "c"], "bc", sum)

// yields this grid:
a    bc
---  ---
1    110
2    220

// we could also replace list of col names with a function
colSel: col => col.name == "b" or col.name == "c"
g.foldCols(colSel, "bc", sum)

@Axon
static Obj? foldEnd()

The fold end marker value

@Axon
static Obj? foldStart()

The fold start marker value

@Axon
static Str format(Obj? val, Str? pattern := null)

Format an object using the current locale and specified format pattern. Formatting patterns follow Fantom toLocale conventions:

• Bool.toLocale
• Number.toLocale
• Date.toLocale
• Time.toLocale
• DateTime.toLocale If toLocale method is found, then return val.toStr

Examples:

123.456kW.format                 >>  123kW
123.456kW.format("#.0")          >>  123.5kW
today().format("D-MMM-YYYY")     >>  8-Feb-2023
today().format("DDD MMMM YYYY")  >>  8th February 2023
now().format("D-MMM hh:mm")      >>  08-Feb 14:50
now().format("DD/MM/YY k:mmaa")  >>  08/02/23 2:50pm

@Axon
static DateTime fromJavaMillis(Number millis, Str? tz := null)

Given Number of milliseconds since Unix epoch return a DateTime. The epic is defined as 1-Jan-1970 UTC. If timezone is null, use system default. Also see toJavaMillis.

@Axon
static Dict? func(Obj name, Bool checked := true)

Find a top-level function by name or by reference and return its tags. If not found throw exception or return null based on checked flag.

Example:

func("readAll")
func(readAll)

@Axon
static Grid funcs(Expr filterExpr := Literal.nullVal)

Find all the top-levels functions in the current project which match the given filter. If the filter is omitted then return all the functions declared in the current project. The function tags are returned.

Examples:

funcs()              // all functions
funcs(sparkRule)     // match filter

@Axon
static Obj? get(Obj? val, Obj? key)

Get an item from a collection:

• str(num): get character at index as int (same semantics as Fantom)
• str(range): get string slice (same semantics as Fantom)
• list(num): get item at given index (same semantics as Fantom)
• list(range): get list slice at given index (same semantics as Fantom)
• dict(key): get item with given key or return null
• grid(num): get row at given index
• grid(range): Grid.getRange

The get function maybe be accessed using the [] shortcut operator:

list[3]  >>  list.get(3)

See Axon Language.

@Axon
static Obj? getSafe(Obj? val, Obj? key)

Get an item from a str, list, or grid safely when an index is out of bounds:

• str(num): get a character at index or null if index invalid
• str(range): get safe slice or "" if entire range invalid
• list(num): get item at given index or null is index invalid
• list(range): get list slice with safe index
• grid(num): get row at given index or null if index invalid
• grid(range): Grid.getRange with safe range

@Axon
static Grid gridColKinds(Grid grid)

Given a grid return the types used in each column as a grid with the following:

• name: string name of the column
• kind: all the different value kinds in the column separated by "|"
• count: total number of rows with column with a non-null value Also see readAllTagNames().

Example:

readAll(site).gridColKinds

@Axon
static Dict gridColsToDict(Grid grid, Fn colToKey, Fn colToVal)

Convert grid columns into a dict of name/val pairs. The name/val paris are derived from each column using the given functions. The functions take (col, index)

Example:

// create dict of column name to column dis
read(temp).hisRead(today).gridColsToDict(c=>c.name, c=>c.meta.dis)

@Axon
static Grid gridReplace(Grid grid, Obj? from, Obj? to)

Replace every grid cell with the given from value with the to value. The resulting grid has the same grid and col meta. Replacement comparison is by via equality via == operator, so it will only replace scalar values or null.

Example:

grid.gridReplace(null, 0)   // replace all null cells with zero
grid.gridReplace(na(), 0)   // replace all NA cells with zero

@Axon
static Dict gridRowsToDict(Grid grid, Fn rowToKey, Fn rowToVal)

Convert grid rows into a dict of name/val pairs. The name/value pairs are derived from each row using the given functions. The functions take (row, index)

Example:

// create dict of sites with dis:area pairs
readAll(site).gridRowsToDict(s=>s.dis.toTagName, s=>s->area)

@Axon
static Obj? has(Obj? val, Str name)

If val is a Grid return if it has the given column name. If val is a Dict return if the given name is mapped to a non-null value.

@Axon
static Obj? hour(Obj t)

Get hour of day as integer between 0 to 23 from time or datetime

@Axon
static Number hoursInDay(DateTime dt)

Given a DateTime in a specific timezone, return the number of hours in the day. Dates which transition to DST will be 23 hours and days which transition back to standard time will be 25 hours.

@Axon
static Obj? index(Obj val, Obj x, Number offset := Number.zero)

Return the first match of x in val searching forward, starting at the specified offset index. A negative offset may be used to access from the end of string. Return null if no occurences are found:

• if val is Str, then x is substring.
• if val is List, then x is item to search.

@Axon
static Obj? indexr(Obj val, Obj x, Number offset := Number.negOne)

Return the last match of x in val searching backward, starting at the specified offset index. A negative offset may be used to access from the end of string. Return null if no occurences are found:

• if val is Str, then x is substring.
• if val is List, then x is item to search.

@Axon
static Obj? insert(Obj? val, Number index, Obj? item)

Insert an item into a list at the given index and return a new list.

@Axon
static Obj? insertAll(Obj? val, Number index, Obj? items)

Insert a list of items at the given index and return a new list.

@Axon
static Bool isAlpha(Number num)

Is number an ASCII alpha char: isUpper||isLower

Examples:

isAlpha("A".get(0))  >>  true
isAlpha("a".get(0))  >>  true
isAlpha("8".get(0))  >>  false
isAlpha(" ".get(0))  >>  false
isAlpha("Ã".get(0))  >>  false

@Axon
static Bool isAlphaNum(Number num)

Is number an ASCII alpha-numeric char: isAlpha||isDigit

Examples:

isAlphaNum("A".get(0))  >>  true
isAlphaNum("a".get(0))  >>  true
isAlphaNum("8".get(0))  >>  true
isAlphaNum(" ".get(0))  >>  false
isAlphaNum("Ã".get(0))  >>  false

@Axon
static Bool isBool(Obj? val)

Return if an object is a boolean type

@Axon
static Bool isDate(Obj? val)

Return if an object is a Date type

@Axon
static Bool isDateTime(Obj? val)

Return if an object is a DateTime type

@Axon
static Bool isDict(Obj? val)

Return if an object is a dict type

@Axon
static Bool isDigit(Number num, Number radix := Number.ten)

Is number a digit in the specified radix. A decimal radix of ten returns true for 0-9. A radix of 16 also returns true for a-f and A-F.

Examples:

isDigit("5".get(0))      >>  true
isDigit("A".get(0))      >>  false
isDigit("A".get(0), 16)  >>  true

@Axon
static Bool isDuration(Obj? val)

Return if an object is a number type with a time unit

@Axon
static Obj? isEmpty(Obj? val)

Return if a collection is empty: str, list, dict, or grid

@Axon
static Obj? isEven(Number val)

Return if an integer is an even number.

@Axon
static Bool isFunc(Obj? val)

Return if an object is a function type

@Axon
static Bool isGrid(Obj? val)

Return if an object is a grid type

@Axon
static Bool isHisGrid(Obj? val)

Return if an object is a grid that conforms to the history grid shape

@Axon
static Bool isKeyword(Str val)

Return if given string is an Axon keyword

@Axon
static Bool isLeapYear(Number year)

Return if a year is a leap year. Year must be four digit Number such as 2020.

@Axon
static Bool isList(Obj? val)

Return if an object is a list type

@Axon
static Bool isLower(Number num)

Is number an ASCII lowercase alphabetic char: a-z

Examples:

isUpper("a".get(0))  >>  true
isUpper("A".get(0))  >>  false
isUpper("5".get(0))  >>  false

@Axon
static Bool isMetric(Obj? val := null)

Given an optional value return true if the SI metric system should be used. Return false if the United States customary unit system should be used. The following rules are used:

• if val is a dict with geoCountry return return false if "US"
• if number or rec with unit and unit is known to be a US customary unit return false (right now we only check for °F and Δ°F)
• fallback to locale of hosting server, see Locale

Examples:

isMetric({geoCountry:"US"})  >>  false
isMetric({geoCountry:"FR"})  >>  true
isMetric(75°F)               >>  false
isMetric({unit:"Δ°C"})       >>  true
isMetric()                   >>  fallback to server locale

@Axon
static Bool isNaN(Obj? val)

Return if val is the Number representation of not-a-number

@Axon
static Bool isNonNull(Obj? val)

Return if an object is not null

@Axon
static Bool isNull(Obj? val)

Return if an object is null

@Axon
static Bool isNumber(Obj? val)

Return if an object is a number type

@Axon
static Obj? isOdd(Number val)

Return if an integer is an odd number.

@Axon
static Bool isRef(Obj? val)

Return if an object is a ref type

@Axon
static Bool isSpace(Number num)

Is number is whitespace char: space \t \n \r \f

Examples:

isSpace("x".get(0))   >>  false
isSpace(" ".get(0))   >>  true
isSpace("\n".get(0))  >>  true

@Axon
static Bool isSpan(Obj? val)

Return if an object is a span

@Axon
static Bool isStr(Obj? val)

Return if an object is a str type

@Axon
static Bool isTagName(Str n)

Return if the given string is legal tag name - see Etc.isTagName

@Axon
static Bool isTime(Obj? val)

Return if an object is a Time type

@Axon
static Bool isUpper(Number num)

Is number an ASCII uppercase alphabetic char: A-Z

Examples:

isUpper("A".get(0))  >>  true
isUpper("a".get(0))  >>  false
isUpper("5".get(0))  >>  false

@Axon
static Bool isUri(Obj? val)

Return if an object is a Uri type

@Axon
static Obj? isWeekday(Obj t)

Does the given Date or DateTime fall on Mon, Tue, Wed, Thu, or Fri

@Axon
static Obj? isWeekend(Obj t)

Does the given Date or DateTime fall on Sat or Sun

@Axon
static Grid join(Grid a, Grid b, Str joinColName)

Join two grids by column 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

@Axon
static Grid joinAll(Grid[] grids, Str joinColName)

Join a list of grids into a single grid. See join.

@Axon
static Obj keepCols(Obj grid, Obj[] cols)

Return a new grid with keeps the given columns, but removes all the others. Columns can be Str names or Col instances. Also see Streams.

Example:

readAll(site).keepCols(["id", "area"])

@Axon
static Obj? last(Obj? val)

Get the last item from an ordered collection or return null if the collection is empty:

• list: item at index -1
• grid: item at index -1
• stream: last item; see Streams

@Axon
static DateSpan lastMonth()

DateSpan for month previous to this month 1..28-31

@Axon
static Date lastOfMonth(Date date)

Get the last day of the date's month. Also see firstOfMonth().

Example:

2009-10-28.lastOfMonth  >>  2009-10-31

@Axon
static DateSpan lastQuarter()

DateSpan for 3 month quarter previous to this quarter

@Axon
static DateSpan lastWeek()

DateSpan for week previous to this week sun..sat (uses locale start of week)

@Axon
static DateSpan lastYear()

DateSpan for year previous to this year Jan-1..Dec-31

@Axon
static Def[] libs()

List the lib definitions in the context namespace as Def[].

@Axon
static Obj limit(Obj? stream, Number limit)

Truncate stream after given limit is reached. See Streams.

@Axon
static Obj? localeUse(Expr locale, Expr expr)

Evaluate an expression within a specific locale. This enables formatting and parsing of localized text using a locale other than the default for the current context.

Examples:

// format Date in German
localeUse("de", today().format)

// parse Date in German
localeUse("de", parseDate("01 Mär 2021", "DD MMM YYYY"))

@Axon
static Obj? lower(Obj val)

Convert a char number or str to ASCII lower case. Also see upper() and decapitalize().

Examples:

lower("CAT")      >>  "cat"
lower("Cat")      >>  "cat"
lower(65).toChar  >>  "a"

@Axon
static Obj? map(Obj val, Fn fn)

Map list, dict, or grid by applying the given mapping function.

If mapping a list, the mapping should be a function that takes (val) or (val, index). It should return the new value for that index.

If mapping a dict, the mapping should be a function that takes (val) or (val, name). It should return the new value for that name.

If mapping a grid, the mapping function takes (row) or (row,index) and returns a new dictionary to use for the row. The resulting grid shares the original's grid level meta. Columns left intact share the old meta-data, new columns have no meta-data. If the mapping function returns null, then that row is removed from the resulting grid (not mapped).

If mapping a range, then the mapping function takes (integer), and returns a list for each mapped integer inte the range.

If mapping a stream, the mapping functions takes (val). See Streams.

Examples:

// create list adding ten to each number
[1, 2, 3].map(v => v+10)   >>   [11, 12, 13]

// create new list that turns strings into uppercase
["ape", "bee", "cat"].map(upper)    // ["APE, "BEE", "CAT"]

// create dict adding ten to each value
{a:1, b:2, c:3}.map(v => v+10)   >>   {a:11, b:12, c:13}

// create grid with just dis, area column
readAll(site).map(s => {dis:s->dis, area:s->area})

@Axon
static Marker marker()

Get the marker value singleton Marker.val

@Axon { meta=["foldOn":"Number"] }
static Obj? max(Obj? val, Obj? acc)

Compare two numbers and return the larger one. This function may also be used with fold to return the largest number (or null if no values). Note number units are not checked nor considered for the comparison.

Examples:

max(7, 4)            >>  7
[7, 2, 4].fold(max)  >>  7

@Axon
static Obj? merge(Obj? a, Obj? b)

Merge two Dicts together and return a new Dict. Any tags in b are added to a. If b defines a tag already in a, then it is overwritten by b. If a tag in b is mapped to Remove.val, then that tag is removed from the result.

@Axon
static Dict meta(Obj? val)

Get the meta-data from a grid or col as a dict.

Examples:

read(temp).hisRead(today).meta             // grid meta
read(temp).hisRead(today).col("ts").meta   // column meta

@Axon { meta=["foldOn":"Number"] }
static Obj? min(Obj? val, Obj? acc)

Compare two numbers and return the smaller one. This function may also be used with fold to return the smallest number (or null if no values). Note number units are not checked nor considered for this comparison.

Examples:

min(7, 4)            >>  4
[7, 2, 4].fold(min)  >>  2

@Axon
static Obj? minute(Obj t)

Get minutes of the time as integer between 0 to 59 from time or datetime

@Axon
static Obj? missing(Obj? val, Str name)

If val is a Grid return if it does not have given column name. If val is a Dict, return if the given name is not mapped to a non-null value.

@Axon
static Obj? month(Obj d)

Get month as integer between 1 to 12 from date or datetime

@Axon
static Obj[] moveTo(Obj[] list, Obj? item, Number toIndex)

Find the given item in a list, and move it to the given index. All the other items are shifted accordingly. Negative indexes may used to access an index from the end of the list. If the item is not found then this is a no op. Return new list.

Examples:

[10, 11, 12].moveTo(11, 0)  >>  [11, 10, 12]
[10, 11, 12].moveTo(11, -1) >>  [10, 12, 11]

@Axon
static NA na()

Get NA not-available singleton NA.val

@Axon
static Str name(Obj? val)

If val is a Col, get the column name.

Example:

// get name of first column
readAll(site).cols.first.name

@Axon
static Obj? names(Dict dict)

Get the list of names used by a given dict

@Axon
static Number nan()

Return the Number representation of not-a-number

@Axon
static Number negInf()

Return the Number representation negative infinity

@Axon
static DateTime now()

Return current DateTime according to context's time zone. This function will use a cached version which is only accurate to within 250ms (see DateTime.now for details). Also see nowTicks() and nowUtc().

@Axon
static Number nowTicks()

Return current time as nanosecond ticks since 1 Jan 2000 UTC. Note that the 64-bit floating point representations of nanosecond ticks will lose accuracy below the microsecond. Also see now().

@Axon
static DateTime nowUtc()

Return current DateTime in UTC. This function will use a cached version which is only accurate to within 250ms (see DateTime.nowUtc for details). Also see now() and nowTicks().

@Axon
static Number numDays(Obj? span)

Number of whole days in a span

@Axon
static Number numDaysInMonth(Obj? month := null)

Get the number of days in a given month. The month parameter may be:

• Date: returns number of days in given month (uses month/year, ignores day)
• Number 1-12: returns days in month for current year
• null: returns day in current month

Examples:

numDaysInMonth()            >>>  days in current month
numDaysInMonth(1)           >>>  31day (days in January)
numDaysInMonth(6)           >>>  30day (days in June)
numDaysInMonth(2)           >>>  28day or 29day (days for Feb this year)
numDaysInMonth(2012-02-13)  >>>  29day (days in Feb for leap year)

@Axon
static Obj? occurred(Obj? ts, Obj? range)

Return if a timestamp is contained within a Date range. Range may be any value supported by toDateSpan. Timestamp may be either a Date or a DateTime. Also see contains.

Examples:

ts.occurred(thisWeek)
ts.occurred(pastMonth())
ts.occurred(2010-01-01..2010-01-15)

@Axon
static Str padl(Str val, Number width, Str char := " ")

Pad string to the left. If size is less than width, then add the given char to the left to achieve the specified width.

Examples:

"3".padl(3, "0")    >>  "003"
"123".padl(2, "0")  >>  "123"

@Axon
static Str padr(Str val, Number width, Str char := " ")

Pad string to the right. If size is less than width, then add the given char to the left to acheive the specified with.

Examples:

"xyz".padr(2, ".")  >>  "xyz"
"xyz".padr(5, "-")  >>  "xyz--"

@Axon
static Dict parseAst(Str src)

Parse Axon source code into an abstract syntax tree modeled as a tree of dicts. Each node has a type tag which specified the node type. Common AST shapes:

123    =>  {type:"literal", val:123}
a      =>  {type:"var", name:"a"}
not a  =>  {type:"not", operand:{type:"var", name:"a"}}
a + b  =>  {type:"add", lhs:{type:"var", name:"a"}, rhs:{type:"var", name:"b"}}

NOTE: the keys and structure of the AST is subject to change over time.

@Axon
static Bool? parseBool(Str val, Bool checked := true)

Parse a Str into a Bool, legal formats are "true" or "false. If invalid format and checked is false return null, otherwise throw ParseErr.

Examples:

parseBool("true")
parseBool("bad", false)

@Axon
static Date? parseDate(Str val, Str pattern := "YYYY-MM-DD", Bool checked := true)

Parse a Str into a Date. If the string cannot be parsed into a valid Date and checked is false then return null, otherwise throw ParseErr. See Date.toLocale for pattern.

Examples:

parseDate("7-Feb-23", "D-MMM-YY")
parseDate("07/02/23", "DD/MM/YY")
parseDate("7 february 2023", "D MMMM YYYY")
parseDate("230207", "YYMMDD")

@Axon
static DateTime? parseDateTime(Str val, Str pattern := "YYYY-MM-DD'T'hh:mm:SS.FFFFFFFFFz zzzz", Str tz := TimeZone.cur().name(), Bool checked := true)

Parse a Str into a DateTime. If the string cannot be parsed into a valid DateTime and checked is false then return null, otherwise throw ParseErr. See DateTime.toLocale for pattern:

YY     Two digit year             07
YYYY   Four digit year            2007
M      One/two digit month        6, 11
MM     Two digit month            06, 11
MMM    Three letter abbr month    Jun, Nov
MMMM   Full month                 June, November
D      One/two digit day          5, 28
DD     Two digit day              05, 28
DDD    Day with suffix            1st, 2nd, 3rd, 24th
WWW    Three letter abbr weekday  Tue
WWWW   Full weekday               Tuesday
V      One/two digit week of year 1,52
VV     Two digit week of year     01,52
VVV    Week of year with suffix   1st,52nd
h      One digit 24 hour (0-23)   3, 22
hh     Two digit 24 hour (0-23)   03, 22
k      One digit 12 hour (1-12)   3, 11
kk     Two digit 12 hour (1-12)   03, 11
m      One digit minutes (0-59)   4, 45
mm     Two digit minutes (0-59)   04, 45
s      One digit seconds (0-59)   4, 45
ss     Two digit seconds (0-59)   04, 45
SS     Optional seconds (only if non-zero)
f*     Fractional secs trailing zeros
F*     Fractional secs no trailing zeros
a      Lower case a/p for am/pm   a, p
aa     Lower case am/pm           am, pm
A      Upper case A/P for am/pm   A, P
AA     Upper case AM/PM           AM, PM
z      Time zone offset           Z, +03:00 (ISO 8601, XML Schema)
zzz    Time zone abbr             EST, EDT
zzzz   Time zone name             New_York
'xyz'  Literal characters
''     Single quote literal

Examples:

parseDateTime("2023-02-07 14:30", "YYYY-MM-DD hh:mm")
parseDateTime("2023-02-07 14:30", "YYYY-MM-DD hh:mm", "Paris")
parseDateTime("7/2/23 2:30pm", "D/M/YY k:mma")
parseDateTime("2023-02-07T14:30:00", "YYYY-MM-DD'T'hh:mm:ss")

@Axon
static Obj? parseFilter(Str val, Bool checked := true)

Parse a filter string into a Filter instance. The resulting filter can then be used with read(), readAll(), filter(), or filterToFunc().

Example:

str: "point and kw"
readAll(parseFilter(str))

@Axon
static Number? parseFloat(Str val, Bool checked := true)

Parse a Str into a Float. Representations for infinity and not-a-number are "-INF", "INF", "NaN". If invalid format and checked is false return null, otherwise throw ParseErr. This string value cannot include a unit (see parseNumber).

Examples:

parseFloat("123.456").format("0.000")
parseFloat("NaN")
parseFloat("INF")

@Axon
static Number? parseInt(Str val, Number radix := Number.ten, Bool checked := true)

Parse a Str into a integer number using the specified radix. If invalid format and checked is false return null, otherwise throw ParseErr. This string value cannot include a unit (see parseNumber).

Examples:

parseInt("123")
parseInt("afe8", 16)
parseInt("10010", 2)

@Axon
static Number? parseNumber(Str val, Bool checked := true)

Parse a Str into a number with an option unit. If invalid format and checked is false return null, otherwise throw ParseErr. Also see parseInt and parseFloat to parse basic integers and floating point numbers without a unit.

Examples:

parseNumber("123")
parseNumber("123kW")
parseNumber("123.567").format("#.000")

@Axon
static Ref? parseRef(Str val, Obj? dis := null, Bool checked := true)

Parse a Str into a Ref. If the string is not a valid Ref identifier then raise ParseErr or return null based on checked flag. If the string has a leading "@", then it is stripped off before parsing.

Examples:

parseRef("abc-123")
parseRef("@abc-123")

@Axon
static Filter parseSearch(Str val)

Parse a search string into a Filter instance. The resulting filter can then be used with read(), readAll(), filter(), or filterToFunc().

The search string is one of the following free patterns:

• *<glob>* case insensitive glob with ? and * wildcards (default)
• re:<regex> regular expression
• f:<filter> haystack filter

See Nav for additional details on search syntax.

Examples:

readAll(parseSearch("RTU-1"))
readAll(point).filter(parseSearch("RTU* Fan"))

@Axon
static Symbol? parseSymbol(Str val, Bool checked := true)

Parse a Str into a Symbol. If the string is not a valid Symbol identifier then raise ParseErr or return null based on checked flag. The string must not include a leading "^".

Examples:

parseSymbol("func:now")

@Axon
static Time? parseTime(Str val, Str pattern := "hh:mm:SS", Bool checked := true)

Parse a Str into a Time. If the string cannot be parsed into a valid Time and checked is false then return null, otherwise throw ParseErr. See Time.toLocale for pattern.

Examples:

parseTime("14:30", "h:mm")
parseTime("2:30pm", "k:mma")
parseTime("2:30:00pm", "k:mm:ssa")

@Axon
static Str? parseUnit(Str val, Bool checked := true)

Parse a Str into a standardized unit name. If the val is not a valid unit name from the standard database then return null or raise exception based on checked flag.

Examples:

parseUnit("%")
parseUnit("percent")

@Axon
static Uri? parseUri(Str val, Bool checked := true)

Parse a string into a Uri instance. If the string cannot be parsed into a valid Uri and checked is false then return null, otherwise throw ParseErr. This function converts an URI from standard form. Use uriDecode to convert a string from escaped form. See Uri for a detailed discussion on standard and escaped forms.

Examples:

"foo bar".parseUri     >>  `foo bar`
"foo%20bar".uriDecode  >>  `foo bar`

@Axon
static DateSpan pastMonth()

DateSpan for last 30days today-30days..today

@Axon
static DateSpan pastWeek()

DateSpan for last 7 days as today-7days..today

@Axon
static DateSpan pastYear()

DateSpan for this past today-365days..today

@Axon
static Number posInf()

Return the Number representation positive infinity

@Axon
static Str? reFind(Obj regex, Str s)

Find the first match of regular expression in s or return null if no matches. See AxonUsage.

Examples:

reFind(r"\d+", "x123y")  >>  "123"
reFind(r"\d+", "xyz")    >>  null

@Axon
static Str[] reFindAll(Obj regex, Str s)

Find all matches of the regular expression in s. Returns an empty list of there are no matches.

Examples:

reFindAll(r"-?\d+\.?\d*", "foo, 123, bar, 456.78, -9, baz")
  >> ["123", "456.78", "-9"]
reFindAll(r"\d+", "foo, bar, baz")
  >> [,]

@Axon
static Obj? reGroups(Obj regex, Str s)

Return a list of the substrings captured by matching the given regular operation against s. Return null if no matches. The first item in the list is the entire match, and each additional item is matched to () arguments in the regex pattern. See AxonUsage.

Examples:

re: r"(RTU|AHU)-(\d+)"
reGroups(re, "AHU")    >> null
reGroups(re, "AHU-7")  >> ["AHU-7", "AHU", "7"]

@Axon
static Bool reMatches(Obj regex, Str s)

Return if regular expression matches entire region of s. See AxonUsage.

Examples:

reMatches(r"\d+", "x123y")  >>  false
reMatches(r"\d+", "123")    >>  true

@Axon
static Obj? reduce(Obj val, Obj? init, Fn fn)

Reduce a collection to a single value with the given reducer function. The given function is called with each item in the collection along with a current accumulation value. The accumation value is initialized to init for the first item, and for every subsequent item it is the result of the previous item. Return the final accumulation value. Also see fold which is preferred if doing standard rollup such as sum or average.

If working with a list, the function takes (acc, val, index) and returns accumulation value

If working with a grid, the function takes (acc, row, index) and returns accumulation value

If working with a stream, then function takes (acc, val) and returns accumulation value See Streams.

Examples:

[2, 5, 3].reduce(0, (acc, val)=>acc+val)  >> 10
[2, 5, 3].reduce(1, (acc, val)=>acc*val)  >> 30

@Axon
static Str refDis(Ref ref)

Given a ref return Ref.dis

@Axon
static Ref refGen()

Generate a new unique Ref identifier

@Axon
static Str? refProjName(Ref ref, Bool checked := true)

Given an absolute ref, return its project name. If the ref is not formatted as "p:proj:r:xxx", then raise an exception or return null based on the checked flag:

Examples:

refProjName(@p:demo:r:xxx)   >>  "demo"
refProjName(@r:xxx)          >>  raises exception
refProjName(@r:xxx, false)   >>  null

@Axon
static Str relDis(Obj parent, Obj child)

Get a relative display name. If the child display name starts with the parent, then we can strip that as the common suffix. Parent and child must be either a Dict or a Str.

@Axon
static Obj? remove(Obj? val, Obj? key)

Remove an item from a collection and return a new collection.

• List: key is index to remove at
• Dict: key is tag name

@Axon
static Obj removeCol(Obj grid, Obj col)

Return a new grid with the given column removed. If the column doesn't exist, then return given grid. Also see Streams.

@Axon
static Obj removeCols(Obj grid, Obj[] cols)

Return a new grid with all the given columns removed. Columns can be Str names or Col instances. Also see Streams.

@Axon
static Remove removeMarker()

Get the remove value singleton Remove.val

@Axon
static Grid renameCol(Grid grid, Str oldName, Str newName)

Return a new grid with the given column renamed.

Example:

readAll(site).renameCol("dis", "title")

@Axon
static Grid renameCols(Grid grid, Dict mapping)

Return a new grid with multiple columns renamed. Mapping must be a dict of old to new names. Old column names not found are ignored.

Example:

readAll(site).renameCols({dis:"title", geoAddr:"subtitle"})

@Axon
static Obj reorderCols(Obj grid, Str[] colNames)

Return a new grid with the columns reordered. The given list of names represents the new order and must contain the same current column names. Any columns not specified are removed. Also see colNames, moveTo, and Streams.

Example:

// move name to first col, and foo to last col
cols: grid.colNames.moveTo("name", 0).moveTo("foo", -1)
return grid.reorderCols(cols)

@Axon
static Str replace(Str val, Str from, Str to)

String replace of all occurrences of from with to. All three parameters must be strings.

Examples:

"hello".replace("hell", "t")  >>  "to"
"aababa".replace("ab", "-")   >>  "a--a"

@Axon
static Obj?[] rowToList(Row row)

Get a grid row as a list of cells. Sparse cells are included as null. Also see colToList().

Example:

readAll(equip).first.rowToList

@Axon
static Obj? second(Obj t)

Get seconds of the time as integer between 0 to 59 from time or datetime

@Axon
static Obj? set(Obj? val, Obj? key, Obj? item)

Set a collection item and return a new collection.

• List: set item by index key
• Dict: set item by key name

@Axon
static Obj setColMeta(Obj grid, Str name, Dict meta)

Return a new grid with column meta-data replaced by given meta dict. If column not found, then return given grid. Also see addColMeta and Streams.

@Axon
static Obj setMeta(Obj grid, Dict meta)

Return new grid with grid level meta-data replaced by given meta Dict. Also see addMeta and Streams.

Example:

read(temp).hisRead(today).setMeta({view:"table"})

@Axon
static Number size(Obj? val)

Return number of items in str, list, or grid

@Axon
static Obj skip(Obj? stream, Number count)

Skip the given number of items in a stream. See Streams.

@Axon
static Obj? sort(Obj val, Obj? sorter := null)

Sort a list or grid.

If sorting a list, the sorter should be a function that takes two list items and returns -1, 0, or 1 (typicaly done with the <=> operator. If no sorter is passed, then the list is sorted by its natural ordering.

If sorting a grid, the sorter can be a column name or a function. If a function, it should take two rows and return -1, 0, or 1.

Examples:

// sort string list
["bear", "cat", "apple"].sort

// sort string list by string size
["bear", "cat", "apple"].sort((a,b) => a.size <=> b.size)

// sort sites by area
readAll(site).sort((a, b) => a->area <=> b->area)

@Axon
static Obj? sortDis(Grid val)

Sort a grid by row display name - see Grid.sortDis

Examples:

// read all sites and sort by display name
readAll(site).sortDis

@Axon
static Obj? sortr(Obj val, Obj? sorter := null)

Reverse sort a list or grid. This function works just like sort except sorts in reverse.

@Axon
static Obj? split(Str val, Str? sep := null, Dict? opts := null)

Split a string by the given separator and trim whitespace. If sep is null then split by any whitespace char; otherwise it must be exactly one char long. See Str.split for detailed behavior.

Options:

• noTrim: disable auto-trim of whitespace from start and end of tokens

Examples:

"a b c".split                   >>  ["a", "b", "c"]
"a,b,c".split(",")              >>  ["a", "b", "c"]
"a, b, c".split(",")            >>  ["a", "b", "c"]
"a, b, c".split(",", {noTrim})  >>  ["a", " b", " c"]

@Axon { meta=["foldOn":"Number"] }
static Obj? spread(Obj? val, Obj? acc)

Fold multiple values to compute the difference between the max and min value. Return null if no values.

Example:

[7, 2, 3].fold(spread)  >>  5

@Axon
static Obj? start(Obj? val)

Start value of a DateSpan, Span or a range.

@Axon
static Number startOfWeek()

Return current locale's start of weekday. Weekday is returned as integer from 0 (Sunday) to 6 (Saturday).

@Axon
static Bool startsWith(Str val, Str sub)

Return if Str starts with the specified Str.

Examples:

"hi there".startsWith("hi")   >>  true
"hi there".startsWith("foo")  >>  false

@Axon
static Obj stream(Obj? val)

Create new stream from given collection:

• Grid: stream the rows
• List: stream the items
• Range: stream inclusive range of integers See Streams.

@Axon
static Obj streamCol(Grid grid, Obj col)

Create a new stream for the cell values of the given column. See Streams.

@Axon { meta=["foldOn":"Number"] }
static Obj? sum(Obj? val, Obj? acc)

Fold multiple values into their numeric sum. Return null if no values.

@Axon
static Grid swizzleRefs(Grid grid)

Given a grid of records, assign new ids and swizzle all internal ref tags. Each row of the grid must have an id tag. A new id is generated for each row, and any Ref tags which used one of the old ids is replaced with the new id. This function is handy for copying graphs of recs such as site/equip/point trees.

@Axon
static Def[] tags()

List tag definitions in the context namespace as Def[].

@Axon
static Def[] terms()

List term definitions (tags and conjuncts) in the context namespace as Def[].

@Axon
static DateSpan thisMonth()

DateSpan for this month as 1st..28-31

@Axon
static DateSpan thisQuarter()

DateSpan for this 3 month quarter

@Axon
static DateSpan thisWeek()

DateSpan for this week as sun..sat (uses locale start of week)

@Axon
static DateSpan thisYear()

DateSpan for this year Jan-1..Dec-31

@Axon
static Obj? time(Obj val, Number? minutes := null, Number secs := Number.zero)

If val is a DateTime: get time portion of the timestamp. If val is a Number: construct a time instance from hour, minutes, secs (truncated to nearest second).

Examples:

now().time      // current time
time(20, 45)    // same as 20:45

@Axon
static Obj? times(Number times, Fn fn)

Call the specified function the given number of times passing the counter.

@Axon
static Number? to(Number? val, Obj? unit)

Convert a number to the given unit. If the units are not of the same dimension then an exception is raised. The target unit can be a string or a Number. If target unit is a Number, then the scalar value is ignored, but by convention should be 1. Also see as() function to set a unit without conversion.

Examples:

10kWh.to(1BTU)
10kWh.to("BTU")
75°F.to(1°C)
to(75°F, 1°C)

@Axon
static Obj? toAxonCode(Obj? val)

Convert a scalar, list, or dict value to its Axon code representation. Examples:

toAxonCode(123)        =>   "123"
toAxonCode([1, 2, 3])  =>   "[1, 2, 3]"
toAxonCode({x:123})    =>   "{x:123}"

@Axon
static Str toChar(Number num)

Convert a unicode char number into a single char string

Examples:

toChar(65)   >>  "A"

@Axon
static DateSpan toDateSpan(Obj? x)

Convert the following objects into a DateSpan:

• Func: function which evaluates to date range
• DateSpan: return itself
• Date: one day range
• Span: return Span.toDateSpan
• Str: evaluates to DateSpan.fromStr
• Date..Date: starting and ending date (inclusive)
• Date..Number: starting date and num of days (day unit required)
• DateTime..DateTime: use starting/ending dates; if end is midnight, then use previous date
• Number: convert as year
• null: use projMeta dateSpanDefault or default to today (deprecated)

Examples:

toDateSpan(2010-07-01..2010-07-03)  >>  01-Jul-2010..03-Jul-2010
toDateSpan(2010-07-01..60day)       >>  01-Jul-2010..29-Aug-2010
toDateSpan(2010-07)                 >>  01-Jul-2010..31-Jul-2010
toDateSpan(2010)                    >>  01-Jan-2010..31-Dec-2010
toDateSpan(pastWeek) // on 9 Aug    >>  02-Aug-2010..09-Aug-2010

@Axon
static Grid toGrid(Obj? val, Dict? meta := null)

Given an arbitrary object, translate it to a Grid via Etc.toGrid:

• if grid just return it
• if row in grid of size, return row.grid
• if scalar return 1x1 grid
• if dict return grid where dict is only
• if list of dict return grid where each dict is row
• if list of non-dicts, return one col grid with rows for each item

Example:

// create simple grid with dis,age cols and 3 rows:
[{dis:"Bob", age:30},
 {dis:"Ann", age:40},
 {dis:"Dan", age:50}].toGrid

@Axon
static Obj? toHex(Number val)

Convert a number to a hexadecimal string.

@Axon
static Number toJavaMillis(DateTime dt)

Given a DateTime return Number of milliseconds since Unix epoch. The epic is defined as 1-Jan-1970 UTC. Also see fromJavaMillis.

@Axon
static Obj?[] toList(Obj? val)

If val is a list return it, otherwise return [val].

@Axon
static Str toLocale(Str key)

Get the localized string for the given tag name or qualified name. If the key is formatted as "pod::name" then route to Env.locale, otherwise to Etc.tagToLocale.

@Axon
static Obj? toRadix(Number val, Number radix, Number? width := null)

Convert a number to its string representation in the given radix (base). If width is non-null, then leading zeroes are prepended to ensure the specified width.

Example:

6.toRadix(2) => "110"
255.toRadix(16, 4) => "00ff"

@Axon
static Span toSpan(Obj? x, Str? tz := null)

Convert the following objects into a Span:

• Span: return itself
• Span+tz: update timezone using same dates only if aligned to midnight
• Str: return Span.fromStr using current timezone
• Str+tz: return Span.fromStr using given timezone
• DateTime..DateTime: range of two DateTimes
• Date..DateTime: start day for date until the end timestamp
• DateTime..Date: start timestamp to end of day for end date
• DateTime: span of a single timestamp
• DateSpan: anything accepted by toDateSpan in current timezone
• DateSpan+tz: anything accepted by toDateSpan using given timezone

@Axon
static Str toTagName(Str n)

Given arbitrary string, convert to a safe tag name - see Etc.toTagName

@Axon
static Obj? toTimeZone(Obj val, Str tz)

Convert a DateTime or Span to another timezone:

now().toTimeZone("Chicago")
now().toTimeZone("UTC")

@Axon
static Date today()

Return today's Date according to context's time zone

@Axon
static Grid transpose(Grid grid)

Perform a matrix transpose on the grid. The cells of the first column because the display names for the new columns. Columns 1..n become the new rows.

Example:

readAll(site).transpose

@Axon
static Str trim(Str val)

Trim whitespace from the beginning and end of the string. For the purposes of this function, whitespace is defined as any character equal to or less than the 0x20 space character (including , \r, \n, and \t).

Examples:

" abc ".trim   >>  "abc"
"abc".trim     >>  "abc"

@Axon
static Str trimEnd(Str val)

Trim whitespace only from the end of the string. See trim for definition of whitespace.

Examples:

" abc ".trimEnd  >>  " abc"
"abc".trimEnd    >>  "abc"

@Axon
static Str trimStart(Str val)

Trim whitespace only from the beginning of the string. See trim for definition of whitespace.

Examples:

" abc ".trimStart  >>  "abc "
"abc".trimStart    >>  "abc"

@Axon
static Obj? tz(DateTime? dt := null)

Get timezone as city name string in tzinfo database from datetime. If the datetime is null then return the environment default timezone.

@Axon
static Obj? unique(Obj val, Obj? key := null)

Return the unique items in a collection. If val is a List then return List.unique. If val is a Grid then return Grid.unique where key must be a column name or list of column names.

Examples:

[1, 1, 2, 2].unique                 >> [1, 2]
grid.unique("geoState")             >> unique states
grid.unique(["geoCity", geoState"]) >> city,state combos

@Axon
static Str? unit(Number? val)

Given a number return its unit string or null. If the val is null, then return null.

@Axon
static Bool unitsEq(Number? a, Number? b)

Return if the two numbers have the same unit. If either of the numbers if null return false.

@Axon
static Obj? upper(Obj val)

Convert a char number or str to ASCII upper case. Also see lower() and capitalize().

Examples:

upper("cat")      >> "CAT"
upper("Cat")      >> "CAT"
upper(97).toChar  >> "A"

@Axon
static Str? uriBasename(Uri val)

Get the basename (last name in path without extension) of a Uri as a string.

@Axon
static Uri uriDecode(Str val, Bool checked := true)

Parse an ASCII percent encoded string into a Uri according to RFC 3986. All %HH escape sequences are translated into octects, and then the octect sequence is UTF-8 decoded into a Str. The + character in the query section is unescaped into a space. If checked if true then throw ParseErr if the string is a malformed URI or if not encoded correctly, otherwise return null. Use parseUri to parse from standard form. See Uri for a detailed discussion on standard and encoded forms.

Examples:

"foo bar".parseUri     >>  `foo bar`
"foo%20bar".uriDecode  >>  `foo bar`

@Axon
static Str uriEncode(Uri val)

Return the percent encoded string for this Uri according to RFC 3986. Each section of the Uri is UTF-8 encoded into octects and then percent encoded according to its valid character set. Spaces in the query section are encoded as +.

Examples:

`foo bar`.uriEncode  >>  "foo%20bar"

@Axon
static Str? uriExt(Uri val)

Get the URI extension of a Uri as a string or null.

@Axon
static Str? uriFrag(Uri val)

Return if the fragment identifier portion of the a URI after hash symbol

@Axon
static Str? uriHost(Uri val)

Get the host Uri as a string or null

@Axon
static Bool uriIsDir(Uri val)

Return if the URI path ends in a slash.

@Axon
static Str? uriName(Uri val)

Get the name Str of a Uri (last item in path).

@Axon
static Obj? uriPath(Uri val)

Get the path segments of a Uri as a list of Strs.

@Axon
static Str? uriPathStr(Uri val)

Get the path a Uri as a string.

@Axon
static Uri uriPlusSlash(Uri val)

Adding trailing slash to the URI. See Uri.plusSlash

@Axon
static Number? uriPort(Uri val)

Get the port of a Uri as a Number or null

@Axon
static Str? uriQueryStr(Uri val)

Return if the query portion of the a URI after question mark

@Axon
static Str? uriScheme(Uri val)

Get the scheme of a Uri as a string or null

@Axon
static Obj? vals(Dict dict)

Get the list of values used by a given dict

@Axon
static Number weekOfYear(Obj val, Number? startOfWeek := null)

Given a DateTime or Date, return the week number of the year. The result is a number between 1 and 53 using the given start of week weekday as number 0-6 (defaults start of week for current locale).

@Axon
static Number weekday(Obj t)

Get weekday as integer from 0 to 6 of Date or DateTime. Zero indicates Sunday and 6 indicates Saturday

@Axon
static Obj xstr(Str type, Str val)

Construct decoded XStr instance

@Axon
static Obj? year(Obj d)

Get year as integer such as 2010 from date or datetime

@Axon
static Date yesterday()

Return yesterday's Date according to context's time zone