= List of Data Types

The server support a wide range of data types, both in `unlang` and in
the dictionaries.  This page outlines the names and functionality of
those data types.

== Basic Data Types

There are a number of "basic" data types.  These data types are
fixed-size, and encapsulate simple concepts such as "integer" or "IP
address".

Basic data types can be used in `unlang`, as they contain simple
values which can be compared, or assigned to one attribute.  In most
cases, it is not necessary to know the name of the data type.  It is
possible to write values in the format you expect, The server will do
"the right thing" when interpreting the values.

.Basic Data Types
[options="header"]
[cols="15%,85%"]
|=====
| Data Type     | Description
| bool		| boolean
| date		| calendar date
| ethernet	| Ethernet address
| float32	| 32-bit floating point number
| float64	| 64-bit floating point number
| ifid		| interface ID
| int8		| 8-bit signed integer
| int16		| 16-bit signed integer
| int32		| 32-bit signed integer
| int64		| 64-bit signed integer
| ipaddr        | IPv4 address
| ipv6addr      | IPv6 address
| ipv4prefix    | IPv4 network with address and prefix length
| ipv6prefix    | IPv6 network with address and prefix length
| octets        | raw binary, printed as hex strings
| xref:type/string/index.adoc[string]        | printable strings
| time_delta	| difference between two calendar dates
| uint8		| 8-bit unsigned integer
| uint16	| 16-bit unsigned integer
| uint32	| 32-bit unsigned integer
| uint64	| 64-bit unsigned integer
|=====

=== Structural Data Types

The following data types are "structural", in that they form
parent-child relationships between attributes.  These data types can
only be used in the dictionaries.  They cannot be used in `unlang`
statements.

.Structural Data Types
[options="header"]
[cols="15%,85%"]
|=====
| Data Type     | Description
| group		| generic grouping
| struct	| structure which contains fixed-width fields
| tlv		| type-length-value which contains other attributes
| vendor	| Encapsulation of a vendor within data type `vsa`
| vsa		| Encapsulation of vendor-specific attributes
|=====

Each structural data type serves a different purpose.  Each structural
data type can contain child attributes.  The different structural
types have different behaviors about what kind of children they can
contain, and how the data type is sent in a packet over the network.

struct:: A `struct` contains fixed-sized data types, in a pre-defined order.
+
The `struct` can only contain a fixed and pre-defined list of child
attributes.  These attributes are the fields, or members, of the structure.
+
The `struct` always encodes all of its children.  If a child is
missing, then the relevant field is filled with zeros.

group: A `group` contains an arbitrary collection of children, in any order.
+
A `group` is really a reference to some other attribute elsewhere in
the same protocol dictionary, or to a different protocol dictionary.
The `group` allows for dictionaries to contain cross-references.
+
The `group` can contain any child attributes, so long as they are
within the same protocol namespace.  See the
dictionary/attribute.adoc[ATTRIBUTE] documentation for more
information.
+
The `group` only encodes the child attributes which have been created
and stored within the `group`.  The order of children does not matter.

tlv:: A `tlv` defines a hierarchy of children, which can only be contained in the `tlv`.
+
The `tlv` can only contain child attributes which have been defined as
children of the `tlv.`
+
The `tlv` only encodes the child attributes which have been created
and stored within the `tlv`.  The order of children does not matter.

vendor:: A `vendor` is a group which has a limited subset of children:
attributes which have been defined by that vendor.
+
The `vendor` can only contain child attributes which have been defined by the vendor.
+
The `vendor` only encodes the child attributes which have been created
and stored within the `vendor`.  The order of children does not
matter.  In practice, the `vendor` attributes are usually encoded with
a 32-bit vendor ID, which identies the vendor.
+
A `vendor` data type can only be a child of a `vsa` data type.

vsa:: A `vsa` is a group which has a limited subset of children: `vendor`s.
+
The `vsa` can only contain child attributes which are `vendor`s
+
The `vsa` only encodes the vendor attributes which have been created
and stored within the `vsa`.  The order of children does not
matter.
+
A `vsa` data type can only be a contain children of the `vendor` data type.


// Copyright (C) 2021 Network RADIUS SAS.  Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS
