# Values

A value is data produced by evaluating an expression. This section describes the kinds of values in the M language. Each kind of value is associated with a literal syntax, a set of values that are of that kind, a set of operators defined over that set of values, and an intrinsic type ascribed to newly constructed values.

Kind | Literal |
---|---|

Null |
`null` |

Logical |
`true` `false` |

Number |
`0` `1` `-1` `1.5` `2.3e-5` |

Time |
`#time(09,15,00)` |

Date |
`#date(2013,02,26)` |

DateTime |
`#datetime(2013,02,26, 09,15,00)` |

DateTimeZone |
`#datetimezone(2013,02,26, 09,15,00, 09,00)` |

Duration |
`#duration(0,1,30,0)` |

Text |
`"hello"` |

Binary |
`#binary("AQID")` |

List |
`{1, 2, 3}` |

Record |
`[ A = 1, B = 2 ]` |

Table |
`#table({"X","Y"},{{0,1},{1,0}})` |

Function |
`(x) => x + 1` |

Type |
`type { number }` `type table [ A = any, B = text ]` |

The following sections cover each value kind in detail. Types and type ascription are defined formally in Types. Function values are defined in Functions. The following sections list the operators defined for each value kind and give examples. The full definition of operator semantics follows in Operators.

## Null

A *null value* is used to represent the absence of a value, or a value of indeterminate or unknown state. A null value is written using the literal `null`

. The following operators are defined for null values:

Operator | Result |
---|---|

`x > y` |
Greater than |

`x >= y` |
Greater than or equal |

`x < y` |
Less than |

`x <= y` |
Less than or equal |

`x = y` |
Equal |

`x <> y` |
Not equal |

`x ?? y` |
Coalesce |

The native type of the `null`

value is the intrinsic type `null`

.

## Logical

A *logical value* is used for Boolean operations has the value true or false. A logical value is written using the literals `true`

and `false`

. The following operators are defined for logical values:

Operator | Result |
---|---|

`x > y` |
Greater than |

`x >= y` |
Greater than or equal |

`x < y` |
Less than |

`x <= y` |
Less than or equal |

`x = y` |
Equal |

`x <> y` |
Not equal |

`x or y` |
Conditional logical OR |

`x ?? y` |
Coalesce |

`x and y` |
Conditional logical AND |

`not x` |
Logical NOT |

The native type of both logical values (`true`

and `false`

) is the intrinsic type `logical`

.

## Number

A *number value* is used for numeric and arithmetic operations. The following are examples of number literals:

```
3.14 // Fractional number
-1.5 // Fractional number
1.0e3 // Fractional number with exponent
123 // Whole number
1e3 // Whole number with exponent
0xff // Whole number in hex (255)
```

A number is represented with at least the precision of a *Double* (but may retain more precision). The *Double* representation is congruent with the IEEE 64-bit double precision standard for binary floating point arithmetic defined in [IEEE 754-2008]. (The *Double* representation have an approximate dynamic range from 5.0 x 10^{324} to 1.7 x 10^{308} with a precision of 15-16 digits.)

The following special values are also considered to be *number* values:

Positive zero and negative zero. In most situations, positive zero and negative zero behave identically as the simple value zero, but certain operations distinguish between the two.

Positive infinity (

`#infinity`

) and negative infinity (`-#infinity`

). Infinities are produced by such operations as dividing a non-zero number by zero. For example,`1.0 / 0.0`

yields positive infinity, and`-1.0 / 0.0`

yields negative infinity.The

*Not-a-Number*value (`#nan`

), often abbreviated NaN. NaNs are produced by invalid floating-point operations, such as dividing zero by zero.

Binary mathematical operations are performed using a *Precision*. The precision determines the domain to which the operands are rounded and the domain in which the operation is performed. In the absence of an explicitly specified precision, such operations are performed using *Double Precision*.

If the result of a mathematical operation is too small for the destination format, the result of the operation becomes positive zero or negative zero.

If the result of a mathematical operation is too large for the destination format, the result of the operation becomes positive infinity or negative infinity.

If a mathematical operation is invalid, the result of the operation becomes NaN.

If one or both operands of a floating-point operation is NaN, the result of the operation becomes NaN.

The following operators are defined for number values:

Operator | Result |
---|---|

`x > y` |
Greater than |

`x >= y` |
Greater than or equal |

`x < y` |
Less than |

`x <= y` |
Less than or equal |

`x = y` |
Equal |

`x <> y` |
Not equal |

`x + y` |
Sum |

`x - y` |
Difference |

`x * y` |
Product |

`x / y` |
Quotient |

`x ?? y` |
Coalesce |

`+x` |
Unary plus |

`-x` |
Negation |

The native type of number values is the intrinsic type `number`

.

## Time

A *time value* stores an opaque representation of time of day. A time is encoded as the number of *ticks since midnight*, which counts the number of 100-nanosecond ticks that have elapsed on a 24-hour clock. The maximum number of *ticks since midnight* corresponds to 23:59:59.9999999 hours.

Time values may be constructed using the #time instrinsic.

```
#time(hour, minute, second)
```

The following must hold or an error with reason code `Expression.Error`

is raised:

0 ≤ hour ≤ 24

0 ≤ minute ≤ 59

0 ≤ second ≤ 59

In addition, if hour = 24, then minute and second must be zero.

The following operators are defined for time values:

Operator | Result |
---|---|

`x = y` |
Equal |

`x <> y` |
Not equal |

`x >= y` |
Greater than or equal |

`x > y` |
Greater than |

`x < y` |
Less than |

`x <= y` |
Less than or equal |

`x ?? y` |
Coalesce |

The following operators permit one or both of their operands to be a date:

Operator | Left Operand | Right Operand | Meaning |
---|---|---|---|

`x + y` |
`time` |
`duration` |
Date offset by duration |

`x + y` |
`duration` |
`time` |
Date offset by duration |

`x - y` |
`time` |
`duration` |
Date offset by negated duration |

`x - y` |
`time` |
`time` |
Duration between dates |

`x & y` |
`date` |
`time` |
Merged datetime |

The native type of time values is the intrinsic type `time`

.

## Date

A *date value* stores an opaque representation of a specific day. A date is encoded as a number of *days since epoch*, starting from January 1, 0001 Common Era on the Gregorian calendar. The maximum number of days since epoch is 3652058, corresponding to December 31, 9999.

Date values may be constructed using the `#date`

intrinsic.

```
#date(year, month, day)
```

The following must hold or an error with reason code `Expression.Error`

is raised:

1 ≤ year ≤ 9999

1 ≤ month ≤ 12

1 ≤ day ≤ 31

In addition, the day must be valid for the chosen month and year.

The following operators are defined for date values:

Operator | Result |
---|---|

`x = y` |
Equal |

`x <> y` |
Not equal |

`x >= y` |
Greater than or equal |

`x > y` |
Greater than |

`x < y` |
Less than |

`x <= y` |
Less than or equal |

`x ?? y` |
Coalesce |

The following operators permit one or both of their operands to be a date:

Operator | Left Operand | Right Operand | Meaning |
---|---|---|---|

`x + y` |
`date` |
`duration` |
Date offset by duration |

`x + y` |
`duration` |
`date` |
Date offset by duration |

`x - y` |
`date` |
`duration` |
Date offset by negated duration |

`x - y` |
`date` |
`date` |
Duration between dates |

`x & y` |
`date` |
`time` |
Merged datetime |

The native type of date values is the intrinsic type `date`

.

## DateTime

A *datetime value* contains both a date and time.

DateTime values may be constructed using the `#datetime`

intrinsic.

```
#datetime(year, month, day, hour, minute, second)
```

The following must hold or an error with reason code Expression.Error is raised:
1 ≤ year ≤ 9999

1 ≤ month ≤ 12

1 ≤ day ≤ 31

0 ≤ hour ≤ 23

0 ≤ minute ≤ 59

0 ≤ second ≤ 59

In addition, the day must be valid for the chosen month and year.

The following operators are defined for datetime values:

Operator | Result |
---|---|

`x = y` |
Equal |

`x <> y` |
Not equal |

`x >= y` |
Greater than or equal |

`x > y` |
Greater than |

`x < y` |
Less than |

`x <= y` |
Less than or equal |

`x ?? y` |
Coalesce |

The following operators permit one or both of their operands to be a datetime:

Operator | Left Operand | Right Operand | Meaning |
---|---|---|---|

`x + y` |
`datetime` |
`duration` |
Datetime offset by duration |

`x + y` |
`duration` |
`datetime` |
Datetime offset by duration |

`x - y` |
`datetime` |
`duration` |
Datetime offset by negated duration |

`x - y` |
`datetime` |
`datetime` |
Duration between datetimes |

The native type of datetime values is the intrinsic type `datetime`

.

## DateTimeZone

A *datetimezone* value contains a datetime and a timezone. A *timezone* is encoded as a number of *minutes offset from UTC*, which counts the number of minutes the time portion of the *datetime* should be offset from Universal Coordinated Time (UTC). The minimum number of *minutes offset from UTC* is -840, representing a UTC offset of -14:00, or fourteen hours earlier than UTC. The maximum number of *minutes offset from UTC* is 840, corresponding to a UTC offset of 14:00.

DateTimeZone values may be constructed using the `#datetimezone`

intrinsic.

```
#datetimezone(
year, month, day,
hour, minute, second,
offset-hours, offset-minutes)
```

The following must hold or an error with reason code `Expression.Error`

is raised:

1 ≤ year ≤ 9999

1 ≤ month ≤ 12

1 ≤ day ≤ 31

0 ≤ hour ≤ 23

0 ≤ minute ≤ 59

0 ≤ second ≤ 59

-14 ≤ offset-hours ≤ 14

-59 ≤ offset-minutes ≤ 59

In addition, the day must be valid for the chosen month and year and, if offset-hours = 14, then offset-minutes <= 0 and, if offset-hours = -14, then offset-minutes >= 0.

The following operators are defined for datetimezone values:

Operator | Result |
---|---|

`x = y` |
Equal |

`x <> y` |
Not equal |

`x >= y` |
Greater than or equal |

`x > y` |
Greater than |

`x < y` |
Less than |

`x <= y` |
Less than or equal |

`x ?? y` |
Coalesce |

The following operators permit one or both of their operands to be a datetimezone:

Operator | Left Operand | Right Operand | Meaning |
---|---|---|---|

`x + y` |
`datetimezone` |
`duration` |
Datetimezone offset by duration |

`x + y` |
`duration` |
`datetimezone` |
Datetimezone offset by duration |

`x - y` |
`datetimezone` |
`duration` |
Datetimezone offset by negated duration |

`x - y` |
`datetimezone` |
`datetimezone` |
Duration between datetimezones |

The native type of datetimezone values is the intrinsic type `datetimezone`

.

## Duration

A *duration value* stores an opaque representation of the distance between two points on a timeline measured 100-nanosecond ticks. The magnitude of a *duration* can be either positive or negative, with positive values denoting progress forwards in time and negative values denoting progress backwards in time. The minimum value that can be stored in a *duration* is -9,223,372,036,854,775,808 ticks, or 10,675,199 days 2 hours 48 minutes 05.4775808 seconds backwards in time. The maximum value that can be stored in a *duration* is 9,223,372,036,854,775,807 ticks, or 10,675,199 days 2 hours 48 minutes 05.4775807 seconds forwards in time.

Duration values may be constructed using the `#duration`

intrinsic function:

```
#duration(0, 0, 0, 5.5) // 5.5 seconds
#duration(0, 0, 0, -5.5) // -5.5 seconds
#duration(0, 0, 5, 30) // 5.5 minutes
#duration(0, 0, 5, -30) // 4.5 minutes
#duration(0, 24, 0, 0) // 1 day
#duration(1, 0, 0, 0) // 1 day
```

The following operators are defined on duration values:

Operator | Result |
---|---|

`x = y` |
Equal |

`x <> y` |
Not equal |

`x >= y` |
Greater than or equal |

`x > y` |
Greater than |

`x < y` |
Less than |

`x <= y` |
Less than or equal |

`x ?? y` |
Coalesce |

Additionally, the following operators allow one or both of their operands to be a duration value:

Operator | Left Operand | Right Operand | Meaning |
---|---|---|---|

`x + y` |
`datetime` |
`duration` |
Datetime offset by duration |

`x + y` |
`duration` |
`datetime` |
Datetime offset by duration |

`x + y` |
`duration` |
`duration` |
Sum of durations |

`x - y` |
`datetime` |
`duration` |
Datetime offset by negated duration |

`x - y` |
`datetime` |
`datetime` |
Duration between datetimes |

`x - y` |
`duration` |
`duration` |
Difference of durations |

`x * y` |
`duration` |
`number` |
N times a duration |

`x * y` |
`number` |
`duration` |
N times a duration |

`x / y` |
`duration` |
`number` |
Fraction of a duration |

The native type of duration values is the intrinsic type `duration`

.

## Text

A *text* value represents a sequence of Unicode characters. Text values have a literal form conformant to the following grammar:

_text-literal:

`"`

text-literal-characters_{opt} `"`

*text-literal-characters:
text-literal-character text-literal-characters _{opt}
text-literal-character:
single-text-character
character-escape-sequence
double-quote-escape-sequence
single-text-character:*

Any character except

`"`

(`U+0022`

) or `#`

(`U+0023`

) followed by `(`

(`U+0028`

)*double-quote-escape-sequence:*

`""`

(`U+0022`

, `U+0022`

)The following is an example of a *text* value:

```
"ABC" // the text value ABC
```

The following operators are defined on *text* values:

Operator | Result |
---|---|

`x = y` |
Equal |

`x <> y` |
Not equal |

`x >= y` |
Greater than or equal |

`x > y` |
Greater than |

`x < y` |
Less than |

`x <= y` |
Less than or equal |

`x & y` |
Concatenation |

`x ?? y` |
Coalesce |

The native type of text values is the intrinsic type `text`

.

## Binary

A *binary value* represents a sequence of bytes. There is no literal format. Several standard library functions are provided to construct binary values. For example, `#binary`

can be used to construct a binary value from a list of bytes:

```
#binary( {0x00, 0x01, 0x02, 0x03} )
```

The following operators are defined on *binary* values:

Operator | Result |
---|---|

`x = y` |
Equal |

`x <> y` |
Not equal |

`x >= y` |
Greater than or equal |

`x > y` |
Greater than |

`x < y` |
Less than |

`x <= y` |
Less than or equal |

`x ?? y` |
Coalesce |

The native type of binary values is the intrinsic type *binary*.

## List

A *list value* is a value which produces a sequence of values when enumerated. A value produced by a list can contain any kind of value, including a list. Lists can be constructed using the initialization syntax, as follows:

*list-expression:*

{ *item-list _{opt}* }

*item-list:*

item

item

item

item

`,`

*item-list*

item:

expression

expression

item:

expression

expression

`..`

*expression*

The following is an example of a *list-expression* that defines a list with three text values: `"A"`

, `"B"`

, and `"C"`

.

```
{"A", "B", "C"}
```

The value `"A"`

is the first item in the list, and the value `"C"`

is the last item in the list.

- The items of a list are not evaluated until they are accessed.
- While list values constructed using the list syntax will produce items in the order they appear in
*item-list*, in general, lists returned from library functions may produce a different set or a different number of values each time they are enumerated.

To include a sequence of whole number in a list, the `a..b`

form can be used:

```
{ 1, 5..9, 11 } // { 1, 5, 6, 7, 8, 9, 11 }
```

The number of items in a list, known as the *list count*, can be determined using the `List.Count`

function.

```
List.Count({true, false}) // 2
List.Count({}) // 0
```

A list may effectively have an infinite number of items; `List.Count`

for such lists is undefined and may either raise an error or not terminate.

If a list contains no items, it is called an *empty list*. An empty list is written as:

```
{} // empty list
```

The following operators are defined for lists:

Operator | Result |
---|---|

`x = y` |
Equal |

`x <> y` |
Not equal |

`x & y` |
Concatenate |

`x ?? y` |
Coalesce |

For example:

```
{1, 2} & {3, 4, 5} // {1, 2, 3, 4, 5}
{1, 2} = {1, 2} // true
{2, 1} <> {1, 2} // true
```

The native type of list values is the intrinsic type `list`

, which specifies an item type of `any`

.

## Record

A *record value* is an ordered sequence of fields. A *field* consists of a *field name*, which is a text value that uniquely identifies the field within the record, and a *field value*. The field value can be any kind of value, including record. Records can be constructed using initialization syntax, as follows:

*record-expression:*

`[`

*field-list _{opt}*

`]`

*field-list:*

field

field

field

field

`,`

*field-list*

field:

field-name

field:

field-name

`=`

*expression*

field-name:

generalized-identifier

quoted-identifier

field-name:

generalized-identifier

quoted-identifier

The following example constructs a record with a field named `x`

with value `1`

, and a field named `y`

with value `2`

.

```
[ x = 1, y = 2 ]
```

The following example constructs a record with `a`

field named a with a nested record value. The nested record has a field named `b`

with value `2`

.

```
[ a = [ b = 2 ] ]
```

The following holds when evaluating a record expression:

The expression assigned to each field name is used to determine the value of the associated field.

If the expression assigned to a field name produces a value when evaluated, then that becomes the value of the field of the resulting record.

If the expression assigned to a field name raises an error when evaluated, then the fact that an error was raised is recorded with the field along with the error value that was raised. Subsequent access to that field will cause an error to be re-raised with the recorded error value.

The expression is evaluated in an environment like the parent environment only with variables merged in that correspond to the value of every field of the record, except the one being initialized.

A value in a record is not evaluated until the corresponding field is accessed.

A value in a record is evaluated at most once.

The result of the expression is a record value with an empty metadata record.

The order of the fields within the record is defined by the order that they appear in the

*record-initializer-expression*.Every field name that is specified must be unique within the record, or it is an error. Names are compared using an ordinal comparison.

```
[ x = 1, x = 2 ] // error: field names must be unique
[ X = 1, x = 2 ] // OK
```

A record with no fields is called an *empty record*, and is written as follows:

```
[] // empty record
```

Although the order of the fields of a record is not significant when accessing a field or comparing two records, it is significant in other contexts such as when the fields of a record are enumerated.

The same two records produce different results when the fields are obtained:

```
Record.FieldNames([ x = 1, y = 2 ]) // [ "x", "y" ]
Record.FieldNames([ y = 1, x = 2 ]) // [ "y", "x" ]
```

The number of fields in a record can be determined using the `Record.FieldCount`

function. For example:

```
Record.FieldCount([ x = 1, y = 2 }) // 2
Record.FieldCount([]) // 0
```

In addition to using the record initialization syntax `[ ]`

, records can be constructed from a list of values, and a list of field names or a record type. For example:

```
Record.FromList({1, 2}, {"a", "b"})
```

The above is equivalent to:

```
[ a = 1, b = 2 ]
```

The following operators are defined for record values:

Operator | Result |
---|---|

`x = y` |
Equal |

`x <> y` |
Not equal |

`x & y` |
Merge |

`x ?? y` |
Coalesce |

The following examples illustrate the above operators. Note that record merge uses the fields from the right operand to override fields from the left operand, should there be an overlap in field names.

```
[ a = 1, b = 2 ] & [ c = 3 ] // [ a = 1, b = 2, c = 3 ]
[ a = 1, b = 2 ] & [ a = 3 ] // [ a = 3, b = 2 ]
[ a = 1, b = 2 ] = [ b = 2, a = 1 ] // true
[ a = 1, b = 2, c = 3 ] <> [ a = 1, b = 2 ] // true
```

The native type of record values is the intrinsic type `record`

, which specifies an open empty list of fields.

## Table

A *table value* is an ordered sequence of rows. A *row* is an ordered sequence of value. The table's type determines the length of all rows in the table, the names of the table's columns, the types of the table's columns, and the structure of the table's keys (if any).

There is no literal syntax for tables. Several standard library functions are provided to construct binary values. For example, `#table`

can be used to construct a table from a list of row lists and a list of header names:

```
#table({"x", "x^2"}, {{1,1}, {2,4}, {3,9}})
```

The above example constructs a table with two columns, both of which are of `type any`

.

`#table`

can also be used to specify a full table type:

```
#table(
type table [Digit = number, Name = text],
{{1,"one"}, {2,"two"}, {3,"three"}}
)
```

Here the new table value has a table type that specifies column names and column types.

The following operators are defined for table values:

Operator | Result |
---|---|

`x = y` |
Equal |

`x <> y` |
Not equal |

`x & y` |
Concatenation |

`x ?? y` |
Coalesce |

Table concatenation aligns like-named columns and fills in `null`

for columns appearing in only one of the operand tables. The following example illustrates table concatenation:

```
#table({"A","B"}, {{1,2}})
& #table({"B","C"}, {{3,4}})
```

A | B | C |
---|---|---|

`1` |
`2` |
`null` |

`null` |
`3` |
`4` |

The native type of table values is a custom table type (derived from the intrinsic type `table`

) that lists the column names, specifies all column types to be any, and has no keys. (Go to Table types for details on table types.)

## Function

A *function value* is a value that maps a set of arguments to a single value. The details of *function* values are described in Functions.

## Type

A *type value* is a value that classifies other values. The details of *type* values are described in Types.