\chapter{Gretl data types}
\label{chap:datatypes}

\section{Introduction}

Gretl offers the following data types:
%
\begin{center}
\begin{tabular}{lp{.8\textwidth}}
  \texttt{scalar} & holds a single numerical value\\
  \texttt{series} & holds $n$ numerical values, where $n$
                    is the number of observations in the current dataset \\
  \texttt{matrix} & holds a rectangular array of numerical
                    values, of any (two) dimensions\\
  \texttt{list} & holds the ID numbers of a set of series \\
  \texttt{string} & holds an array of characters\\
  \texttt{bundle} & holds zero or more objects of 
                    various types \\
  \texttt{array} & holds zero or more objects of 
                   a given type
\end{tabular}
\end{center}

The ``numerical values'' mentioned above are all double-precision
floating point numbers.

In this chapter we give a run-down of the basic characteristics of
each of these types and also explain their ``life cycle'' (creation,
modification and destruction). The list and matrix types, whose uses
are relatively complex, are discussed at greater length in
chapters~\ref{chap:lists-strings} and \ref{chap:matrices}
respectively.

\section{Series}
\label{sec:Series}

We begin with the \texttt{series} type, which is the oldest and in a
sense the most basic type in gretl. When you open a data file in the
gretl GUI, what you see in the main window are the ID numbers, names
(and descriptions, if available) of the series read from the file. All
the series existing at any point in a gretl session are of the same
length, although some may have missing values. The variables that can
be added via the items under the \textsf{Add} menu in the main window
(logs, squares and so on) are also series.

For a gretl session to contain any series, a common series length must
be established. This is usually achieved by opening a data file, or
importing a series from a database, in which case the length is set by
the first import. But one can also use the \texttt{nulldata} command,
which takes as it single argument the desired length, a positive
integer.

Each series has these basic attributes: an ID number, a name, and of
course $n$ numerical values. A series may also have a description
(which is shown in the main window and is also accessible via the
\texttt{labels} command), a ``display name'' for use in graphs, a
record of the compaction method used in reducing the variable's
frequency (for time-series data only) and flags marking the variable
as discrete and/or as a numeric encoding of a qualitative
characteristic. These attributes can be edited in the GUI by choosing
\textsf{Edit Attributes} (either under the \textsf{Variable} menu or
via right-click), or by means of the \texttt{setinfo} command.

In the context of most commands you are able to reference series by
name or by ID number as you wish. The main exception is the definition
or modification of variables via a formula; here you must use names
since ID numbers would get confused with numerical constants.

Note that series ID numbers are always consecutive, and the ID number
for a given series will change if you delete a lower-numbered series.
In some contexts, where gretl is liable to get confused by such
changes, deletion of low-numbered series is disallowed.

\subsection{Discrete series}

It is possible to mark variables of the series type as
\textit{discrete}. The meaning and uses of this facility are explained
in chapter~\ref{chap:discrete}.

\subsection{String-valued series}

It is generally expected that series in gretl will be ``properly
numeric'' (on a ratio or at least an ordinal scale), or the sort of
numerical indicator variables (0/1 ``dummies'') that are traditional
in econometrics. However, ``string-valued'' series are also
supported---see chapter~\ref{chap:strval-series} for details.

\section{Scalars}
\label{sec:Scalars}

The scalar type is relatively simple: just a convenient named holder
for a single numerical value. Scalars have none of the additional
attributes pertaining to series, do not have ID numbers, and must be
referenced by name. A common use of scalar variables is to record
information made available by gretl commands for further processing,
as in \texttt{scalar s2 = \$sigma\^{}2} to record the square of the
standard error of the regression following an estimation command such
as \texttt{ols}.

You can define and work with scalars in gretl without having any
dataset in place.

In the gretl GUI, scalar variables can be inspected and their values
edited via the ``Icon view'' (see the \texttt{View} menu in the main
window).

\section{Matrices}
\label{sec:Matrices}

Matrices in gretl work much as in other mathematical software (e.g.\
\textsf{MATLAB}, \textsf{Octave}). Like scalars they have no ID
numbers and must be referenced by name, and they can be used without
any dataset in place. Matrix indexing is 1-based: the top-left element
of matrix \texttt{A} is \texttt{A[1,1]}.  Matrices are discussed at
length in chapter~\ref{chap:matrices}; advanced users of gretl will
want to study this chapter in detail.

Matrices have two optional attribute beyond their numerical content:
they may have column and/or row names attached; these are displayed
when the matrix is printed. See the \texttt{cnameset} and
\texttt{rnameset} functions for details.

In the gretl GUI, matrices can be inspected, analysed and edited via
the \texttt{Icon view} item under the \texttt{View} menu in the main
window: each currently defined matrix is represented by an icon.

\section{Lists}
\label{sec:Lists}

As with matrices, lists merit an explication of their own (see
chapter~\ref{chap:lists-strings}).  Briefly, named lists can (and
should!)  be used to make command scripts less verbose and
repetitious, and more easily modifiable. Since lists are in fact lists
of series ID numbers they can be used only when a dataset is in place.

In the gretl GUI, named lists can be inspected and edited under the
\textsf{Data} menu in the main window, via the item \textsf{Define or
  edit list}.

\section{Strings}
\label{sec:Strings}

String variables may be used for labeling, or for constructing
commands. They are discussed in chapter~\ref{chap:lists-strings}. They
must be referenced by name; they can be defined in the absence of a
dataset.

Such variables can be created and modified via the command-line in
the gretl console or via script; there is no means of editing them
via the gretl GUI.

\section{Bundles}
\label{sec:Bundles}

A \texttt{bundle} is a container or wrapper for various sorts of
objects---primarily scalars, matrices, strings, arrays and
bundles. (Yes, a bundle can contain other bundles). Secondarily,
series and lists can be placed in bundles but this is subject to
important qualifications noted below.

A bundle takes the form of a hash table or associative array: each
item placed in the bundle is associated with a key which can used to
retrieve it subsequently. We begin by explaining the mechanics of
bundles then offer some thoughts on what they are good for.

There are several ways of creating a bundle. Here are the first two:
\begin{itemize}
\item Just ``declare'' it, as in
\begin{code}
bundle foo
\end{code}
\item or define an empty bundle using the \texttt{defbundle} function
without any arguments:
\begin{code}
bundle foo = defbundle()
\end{code}
\end{itemize}
These formulations are basically equivalent, in that they both
create an empty bundle. The difference is that the second variant may
be reused---if a bundle named \texttt{foo} already exists the effect
is to empty it---while the first may only be used once in a given
gretl session; it is an error to attempt to declare a variable that
already exists.

To create a bundle and add contents in one go, you can use the
\texttt{defbundle} function with some arguments. For example:
\begin{code}
bundle foo = defbundle("x", 13, "mat", I(3), "str", "some string")
\end{code}
The arguments must be given in pairs---a key followed by the object to
be associated with the key---with all terms comma-separated. However,
you may prefer to use one or other of the alternative idioms
introduced in gretl 2021a. The first of these looks like this:
\begin{code}
bundle foo = _(x = 13, mat = I(3), str = "some string")
\end{code}
It's more streamlined than \texttt{defbundle} but not quite so
flexible. You don't have to quote the keys, but that also means that
you can't give the name of a key as a string variable; it's always
taken as a string literal. Yet more streamlined but also less flexible
is this variant:
\begin{code}
bundle foo = _(x, mat, str)
\end{code}
which works if and only if there are existing objects \texttt{x},
\texttt{mat} and \texttt{str} in scope and you want to add them to the
bundle under keys equal to their own names.

For more on the \texttt{defbundle} function, see the \GCR\ or the
\textsf{Function Reference} under \textsf{Help} in the GUI program.

To add an object to a bundle you assign to a compound left-hand value:
the name of the bundle followed by the key. Two forms of syntax are
acceptable in this context. The recommended syntax (for most uses) is
\textsl{bundlename}.\textsl{key}; that is, the name of the bundle
followed by a dot, then the key. Both the bundle name and the key must
be valid gretl identifiers.\footnote{As a reminder: 31 characters
  maximum, starting with a letter and composed of just letters,
  numbers or underscore.} For example, the statement
%
\begin{code}
foo.matrix1 = m
\end{code}
%
adds an object called \texttt{m} (presumably a matrix) to bundle
\texttt{foo} under the key \texttt{matrix1}. If you wish to make it
explicit that \texttt{m} is supposed to be a matrix you can use the
form
%
\begin{code}
matrix foo.matrix1 = m
\end{code}

Alternatively, a bundle key may be given as a string enclosed in
square brackets, as in
%
\begin{code}
foo["matrix1"] = m
\end{code}
%
This syntax offers greater flexibility in that the key string does not
have to be a valid identifier (for example it can include spaces). In
addition, when using the square bracket syntax it is possible to use a
string variable to define or access the key in question. For example:
%
\begin{code}
string s = "matrix 1"
foo[s] = m # matrix is added under key "matrix 1"
\end{code}

To get an item out of a bundle, again use the name of the bundle
followed by the key, as in

\begin{code}
matrix bm = foo.matrix1
# or using the alternative notation
matrix bm = foo["matrix1"]
# or using a string variable
matrix bm = foo[s]
\end{code}

Note that the key identifying an object within a given bundle is
necessarily unique. If you reuse an existing key in a new assignment,
the effect is to replace the object which was previously stored under
the given key. In this context it is not required that the type of the
replacement object is the same as that of the original.

Also note that when you add an object to a bundle, what in fact
happens is that the bundle acquires a \textit{copy} of the object. The
external object retains its own identity and is unaffected if the
bundled object is replaced by another. Consider the following script
fragment:

\begin{code}
bundle foo
matrix m = I(3)
foo.mykey = m
scalar x = 20
foo.mykey = x
\end{code}

After the above commands are completed bundle \texttt{foo} does not
contain a matrix under \texttt{mykey}, but the original matrix
\texttt{m} is still in good health.

To delete an object from a bundle use the \texttt{delete} command,
with the bundle/key combination, as in

\begin{code}
delete foo.mykey
\end{code}

This destroys the object associated with \texttt{mykey} and removes
the key from the hash table.

To determine whether a bundle contains an object associated with a
given key, use the \texttt{inbundle()} function. This takes two
arguments: the name of the bundle and the key string. The value
returned by this function is an integer which codes for the type of
the object (0 for no match, 1 for scalar, 2 for series, 3 for matrix,
4 for string, 5 for bundle and 6 for array). The function
\texttt{typestr()} may be used to get the string corresponding to this
code. For example:

\begin{code}
scalar type = inbundle(foo, x)
if type == 0
  print "x: no such object"
else
  printf "x is of type %s\n", typestr(type)
endif
\end{code}

Besides adding, accessing, replacing and deleting individual items,
the other operations that are supported for bundles are union,
printing and deletion. As regards union, if bundles \texttt{b1} and
\texttt{b2} are defined you can say

\begin{code}
bundle b3 = b1 + b2
\end{code}

to create a new bundle that is the union of the two others. The
algorithm is: create a new bundle that is a copy of \texttt{b1}, then
add any items from \texttt{b2} whose keys are not already present in
the new bundle. (This means that bundle union is not commutative if
the bundles have one or more key strings in common.)

If \texttt{b} is a bundle and you say \texttt{print b}, you get a
listing of the bundle's keys along with the types of the corresponding
objects, as in

\begin{code}
? print b
bundle b:
 x (scalar)
 mat (matrix)
 inside (bundle)
\end{code}

Note that in the example above the bundle \texttt{b} nests a bundle
named \texttt{inside}. If you want to see what's inside nested bundles
(with a single command) you can append the \option{tree} option to the
print command.

\subsection{Series and lists as bundle members}

It is possible to add both series and lists to a bundle, as in
\begin{code}
open data4-10
list X = const CATHOL INCOME
bundle b
b.y = ENROLL
b.X = X
eval b.y
eval b.X
\end{code}

However, it is important to bear in mind the following limitations.
\begin{itemize}
\item A series, as such, is inherently a member of a dataset, and a
  bundle can ``survive'' the replacement or destruction of the dataset
  from which a series was added. It may then be impossible (or, even
  if possible, meaningless) to extract a bundled series \textit{as a
    series}. However it's always possible to retrieve the values of
  the series in the form of a matrix (column vector).
\item In gretl commands that call for series arguments you cannot give
  a bundled series without first extracting it. In the little example
  above the series \texttt{ENROLL} was added to bundle \texttt{b}
  under the key \texttt{y}, but \texttt{b.y} is not itself a series
  (member of a dataset), it's just an anonymous array of values. It
  therefore cannot be given as, say, the dependent variable in a call
  to gretl's \texttt{ols} command.
\item A gretl list is just an array of ID numbers of series in a given
  dataset, a ``macro'' if you like. So as with series, there's no
  guarantee that a bundled list can be extracted \textit{as a list}
  (though it can always be extracted as a row vector).
\end{itemize}

The points made above are illustrated in Listing~\ref{ex:bundle-limits}.  In
``Case 1'' we open a little dataset with just 14 cross-sectional
observations and put a series into a bundle. We then open a
time-series dataset with 64 observations, while preserving the bundle,
and extract the bundled series. This instance is \textit{legal}, since
the stored series does not overflow the length of the new dataset (it
gets written into the first 14 observations), but it's probably not
meaningful. It's up to the user to decide if such operations make
sense.

In ``Case 2'' a similar sequence of statements leads to an error
(trapped by \texttt{catch}) because this time the stored series will
not fit into the new dataset. We can nonetheless grab the data as a
vector.

In ``Case 3'' we put a list of three series into a bundle. This does
not put any actual data values into the bundle, just the ID numbers of
the specified series, which happen to be 4, 5 and 6. We then switch to
a dataset that contains just 4 series, so the list cannot be extracted
as such (IDs 5 and 6 are out of bounds). Once again, however, we can
retrieve the ID numbers in matrix form if we want.

In some cases putting a gretl list as such into a bundle may be
appropriate, but in others you are better off adding the
\textit{content} of the list, in matrix form, as in
\begin{code}
open data4-10
list X = const CATHOL INCOME
bundle b
matrix b.X = {X}
\end{code}
In this case we're adding a matrix with three columns and as many rows
as there are in the dataset; we have the actual data, not just a
reference to the data that might ``go bad''. See
chapter~\ref{chap:matrices} for more on this.

\begin{script}[htbp]
  \scriptinfo{bundle-limits}{Series and lists in bundles}
\begin{scode}
# Case 1: store and retrieve series, OK?
open data4-1
bundle b
series b.x = sqft
open data9-7 --preserve
series x = b.x
print x --byobs

# Case 2: store and retrieve series: gives an error,
# but the data can be retrieved in matrix form
open data9-7
bundle b
series b.x = QNC
open data4-1 --preserve
catch series x = b.x # wrong, won't fit!
if $error
  matrix mx = b.x
  print mx
else
  print x
endif

# Case 3: store and retrieve list: gives an error,
# but the ID numbers in the list can be retrieved
# as a row vector
open data9-7
list L = PRIME UNEMP STOCK
bundle b
list b.L = L
open data4-1 --preserve
catch list L = b.L
if $error
  matrix mL = b.L
  print mL # prints "4 5 6"
endif
\end{scode}
\end{script}

\subsection{What are bundles good for?}

Bundles are unlikely to be of interest in the context of standalone
gretl scripts, but they can be very useful in the context of complex
function packages where a good deal of information has to be passed
around between the component functions \citep[see][]{GFPG}. Instead of
using a lengthy list of individual arguments, function $A$ can bundle
up the required data and pass it to functions $B$ and $C$, where
relevant information can be extracted via a mnemonic key.

In this context bundles should be passed in ``pointer'' form
(see chapter~\ref{chap:functions}) as illustrated in the following
trivial example, where a bundle is created at one level then filled
out by a separate function.

\begin{code}
# modification of bundle (pointer) by user function

function void fill_out_bundle (bundle *b)
  b.mat =  I(3)
  b.str = "foo"
  b.x = 32
end function

bundle my_bundle 
fill_out_bundle(&my_bundle)
\end{code}

The bundle type can also be used to advantage as the \textit{return
  value} from a packaged function, in cases where a package writer
wants to give the user the option of accessing various results. In the
gretl GUI, function packages that return a bundle are treated
specially: the output window that displays the printed results
acquires a menu showing the bundled items (their names and types),
from which the user can save items of interest. For example, a
function package that estimates a model might return a bundle 
containing a vector of parameter estimates, a residual series and a
covariance matrix for the parameter estimates, among other
possibilities.

When offering a bundle as the return value from a function it's
important to keep in mind the limitation noted above, concerning the
inclusion of lists in bundles. Once again: a list is just an array of
series ID numbers. Consider the following would-be function code.

\begin{code}
function bundle bunlist (const series y)
  series y2 = y^2
  series y3 = y^3
  bundle ret
  # don't do this!
  list ret.L = y2 y3
  return ret
end function
\end{code}

If the intent is to give the caller a list containing two new series
this will \textit{not} work. Suppose that when this function is
called, the caller has in place a dataset with two series (besides the
built-in \texttt{const}), with ID numbers 1 and 2. Then the series
\texttt{y2} and \texttt{y3} will be given IDs 3 and 4, which will be
duly recorded in \texttt{ret.L}. But these series are local to the
function; at caller level there will be no series answering to IDs 3
and 4, and the ``list'' therefore turns into the useless vector
$\{3, 4\}$. If you want to return multiple series your options are (a)
return a list \textit{directly}---in which case gretl adds the
specified series to the caller's dataset---or (b) turn the list into a
a matrix, as in
\begin{code}
list L = y2 y3
matrix Y = {L}
\end{code}
This matrix can be returned in its own right, or can be packed into a
bundle if the function is to return something else besides; either way
the caller can reconstitute a list using the \texttt{mat2list}
function.

You might be wondering, if the direct return of a list works as
mentioned above, why doesn't a bundled list work in the same way?
That's basically because of the ``encapsulation'' policy: functions
should not have any unexpected side effects. If a caller assigns the
return value of a function that advertises a list return, it should be
clear that the caller's dataset may be modified---it's all ``above
board''. If a function that advertises a bundle return value has the
side effect of modifying the caller's dataset, because the bundle
happens to contain a list, that would seem to break encapsulation.

For completeness, it's worth noting that there are cases where a
function \textit{can} successfully return a list in a bundle, without
breaking encapsulation: the requirement is just that the series IDs in
the list are defined at caller
level. Listing~\ref{ex:discrete-check} gives an example. A list
argument \texttt{L} is examined and the return value is a bundle
containing a list and a vector. The bundled list includes the IDs of
just those series in \texttt{L} that are discrete, and the vector
gives the number of distinct values for each of these series.

\begin{script}
    \scriptinfo{discrete-check}{Returning a list in a bundle}
\begin{scode}
set verbose off

function bundle discrete_check (const list L)
   list dlist
   matrix nvals = {}
   bundle b
   loop i=1..nelem(L)
      b = getinfo(L[i])
      if b.discrete
         dlist += L[i]
         nvals ~= nelem(values(L[i]))
      endif
   endloop
   return _(dlist, nvals)
end function

open mroz87.gdt --quiet
list L = dataset
bundle b = discrete_check(L)
list print b.dlist
\end{scode}
\end{script}

\subsection{Adding annotations}

As a refinement to support the use of bundles as a function return
type, the \texttt{setnote} function can be used to add a brief
explanatory note to a bundled item---such notes will then be shown in
the GUI menu.  This function takes three arguments: the name of a
bundle, a key string, and the note. For example

\begin{code}
setnote(b, "vcv", "covariance matrix")
\end{code}

After this, the object under the key \texttt{vcv} in bundle \texttt{b}
will be shown as ``covariance matrix'' in a GUI menu.

\section{Arrays}
\label{sec:arrays}

The gretl array type is intended for scripting use. Arrays have no GUI
representation and they're unlikely to acquire one.\footnote{However,
  it's possible to save arrays ``invisibly'' in the context of a GUI
  session, by virtue of the fact that they can be packed into bundles
  (see below), and bundles can be saved as part of a ``session''.}

A gretl array is, as you might expect, a container which can hold zero
or more objects of a certain type, indexed by consecutive integers
starting at 1. It is one-dimensional. This type is implemented by a
quite ``generic'' back-end. The types of object that can be put into
arrays are strings, matrices, lists, bundles and arrays.\footnote{It
  was not possible to nest arrays prior to version 2019d of gretl.}

Of gretl's ``primary'' types, then, neither scalars nor series are
supported by the array mechanism. There would be little point in
supporting arrays of scalars as such since the matrix type already
plays that role, and more flexibly. As for series, they have a special
status as elements of a dataset (which is in a sense an ``array of
series'' already) and in addition we have the list type which already
functions as a sort of array for subsets of the series in a dataset.

\subsection{Creating an array}

An array can be brought into existence in any of three ways: bare
declaration or using one of the functions \texttt{array()} or
\texttt{defarray()}. In each case one of the specific type-words
\texttt{strings}, \texttt{matrices}, \texttt{lists}, \texttt{bundles}
or \texttt{arrays} must be used. Here are some examples:

\begin{code}
# declare an empty array of strings
strings S
# make an empty array of matrices
matrices M = array(0)
# make an array with space for four bundles
bundles B = array(4)
# make an array with three specified strings
strings P = defarray("foo", "bar", "baz")
\end{code}

The ``bare declaration'' form and the function form with
\texttt{array(0)} have
the same effect of creating an empty array, but the second can be used
in contexts where bare declaration is not allowed (and it can also be
used to destroy the content of an existing array and reduce it to size
zero). The \texttt{array()} function expects a non-negative integer
argument and can be used to create an array of pre-given size; in this
case the elements are initialized appropriately as empty strings, empty
matrices, empty lists, empty bundles or empty arrays. The
\texttt{defarray()} function takes a variable number of arguments (one
or more), each of which may be the name of a variable of the
appropriate type or an expression which evaluates to an object of the
appropriate type.

\subsection{Setting and getting elements}

There are two ways to set the value of an array element: you can set a
particular element using the array index, or you can append an element
using the \texttt{+=} operator:
\begin{code}
# first case
strings S = array(3)
S[2] = "string the second"
# alternative
matrices M = array(0)
M += mnormal(T,k)
\end{code}

In the first method the index must (of course) be within bounds; that
is, greater than zero and no greater than the current length of the
array. When the second method is used it automatically extends the
length of the array by 1.

To get hold of an element, the array index must be used:
\begin{code}
# for S an array of strings
string s = S[5]
# for M an array of matrices
printf "\n%#12.5g\n", M[1]
\end{code}

\subsection{Removing elements}

There's a counterpart to the \texttt{+=} operator mentioned above:
\texttt{-=} can be used to remove one or more elements specified by
\textit{content} from an array of strings. Note that \texttt{-=} works
on all matching elements, so after the following statements
\begin{code}
strings S = defarray("a", "a", "b", "a")
S -= "a"
\end{code}
\texttt{S} becomes a one-element array holding only the original third
element.

More generally, a negative index can be used to remove a specified
element from an array of any type, as in
\begin{code}
strings S = defarray("a", "a", "b", "a")
S = S[-1]
\end{code}
where only the first element is removed. See
chapter~\ref{chap:matrices} for more on the semantics of negative
indices.

\subsection{Operations on whole arrays}

Three operators are applicable to whole arrays, but only one to
arrays of arbitrary type (the other two being restricted to arrays of
strings). The generally available operation is appending. You can do,
for example
\begin{code}
# for M1 and M2 both arrays of matrices
matrices BigM = M1 + M2
# or if you wish to augment M1
M1 += M2
\end{code}
In each case the result is an array of matrices whose length is the sum
of the lengths of \texttt{M1} and \texttt{M2}---and similarly for the
other supported types.

The operators specific to strings are union, via \verb+||+, and
intersection, via \verb+&&+. Given the following code, for \texttt{S1}
and \texttt{S2} both arrays of strings,
\begin{code}
strings Su = S1 || S2
strings Si = S1 && S2
\end{code}
the array \texttt{Su} will contain all the strings in \texttt{S1} plus
any in \texttt{S2} that are not in \texttt{S1}, while \texttt{Si} will
contain all and only the strings that appear in both \texttt{S1} and
\texttt{S2}.

\subsection{Arrays as function arguments}
\label{subsec:array-args}

One can write hansl functions that take as arguments any of the array
types, and it is possible to pass arrays as function arguments in
``pointerized'' form. In addition hansl functions may return any of
the array types. Here is a trivial example for strings:
\begin{code}
function void printstrings (strings *S)
  loop i=1..nelem(S)
    printf "element %d: '%s'\n", i, S[i]
  endloop
end function

function strings mkstrs (int n)
  strings S = array(n)
  loop i=1..n
    S[i] = sprintf("member %d", i)
  endloop
  return S
end function

strings Foo = mkstrs(5)
print Foo
printstrings(&Foo)
\end{code}

A couple of points are worth noting here. First, the \texttt{nelem()}
function works to give the number of elements in any of the
``container'' types (lists, arrays, bundles, matrices). Second, if you
do ``\texttt{print Foo}'' for \texttt{Foo} an array, you'll see
something like:
\begin{code}
? print Foo
Array of strings, length 5
\end{code}

\subsection{Nesting arrays}

While gretl's \texttt{array} structure is in itself one-dimensional
you can add extra dimensions by nesting. For example, the code below
creates an array holding $n$ arrays of $m$ bundles.
\begin{code}
arrays BB = array(n)
loop i=1..n
    bundles BB[i] = array(m)
endloop
\end{code}
The syntax for setting or accessing any of the $n \times m$ bundles
(or their members) is then on the following pattern:
\begin{code}
BB[i][j].m = I(3)
eval BB[i][j]
eval BB[i][j].m # or eval BB[i][j]["m"]
\end{code}
where the respective array subscripts are each put into square
brackets.

The elements of an array of arrays must (obviously) all be arrays, but
it's not required that they have a common content-type. For example,
the following code creates an array holding an array of matrices plus
an array of strings.
\begin{code}
arrays AA = array(2)
matrices AA[1] = array(3)
strings AA[2] = array(3)
\end{code}

\subsection{Arrays and bundles}

As mentioned, the \texttt{bundle} type is supported by the array
mechanism. In addition, arrays (of whatever type) can be put into
bundles:
\begin{code}
matrices M = array(8)
# set values of M[i] here...
bundle b
b.M = M
\end{code}

The mutual ``packability'' of bundles and arrays means that it's
possible to go quite far down the rabbit-hole\dots\ users are advised
not to get carried away.

\section{The life cycle of gretl objects}

\subsection{Creation}

The most basic way to create a new variable of any type is by
\textit{declaration}, where one states the type followed by the name
of the variable to create, as in

\begin{code}
scalar x
series y
matrix A
\end{code}

and so forth. In that case the object in question is given a default
initialization, as follows: a new scalar has value \texttt{NA}
(missing); a new series is filled with \texttt{NA}s; a new matrix is
empty (zero rows and columns); a new string is empty; a new list has no
members, new bundles and new arrays are empty.

Declaration can be supplemented by a definite initialization, as in

\begin{code}
scalar x = pi
series y = log(x)
matrix A = zeros(10,4)
\end{code}

The type of a new variable can be left implicit, as in
\begin{code}
x = y/100
z = 3.5
\end{code}
Here the type of \texttt{x} will be determined automatically depending
on the context.  If \texttt{y} is a scalar, a series or a matrix
\texttt{x} will inherit \texttt{y}'s type (otherwise an error will be
generated, since division is applicable to these types only). The new
variable \texttt{z} will ``naturally'' be of scalar type.

In general, however, we recommend that you state the type of a new
variable explicitly. This makes the intent clearer to a reader of the
script and also guards against errors that might otherwise be
difficult to understand (i.e.\ a certain variable turns out to be of
the wrong type for some subsequent calculation, but you don't notice
at first because you didn't say what type you wanted). Exceptions to
this rule might reasonably be granted for clear and simple cases where
there's little possibility of confusion.

\subsection{Modification}

Typically, the values of variables of all types are modified
by assignment, using the \texttt{=} operator with the name of the
variable on the left and a suitable value or formula on the right:

\begin{code}
z = normal()
x = 100 * log(y) - log(y(-1))
M = qform(a, X)
\end{code}

By a ``suitable'' value we mean one that is conformable for the type
in question. A gretl variable acquires its type when it is first
created and this cannot be changed via assignment; for example, if you
have a matrix \texttt{A} and later want a string \texttt{A}, you will
have to delete the matrix first.

\tip{One point to watch out for in gretl scripting is type
  conflicts having to do with the names of series brought in from a
  data file. For example, in setting up a command loop (see
  chapter~\ref{chap:looping}) it is very common to call the loop index
  \texttt{i}. Now a loop index is a scalar (typically incremented each
  time round the loop). If you open a data file that happens to
  contain a series named \texttt{i} you will get a type error (``Types
  not conformable for operation'') when you try to use \texttt{i} as a
  loop index.}

Although the type of an existing variable cannot be changed on the
fly, gretl nonetheless tries to be as ``understanding'' as
possible. For example if \texttt{x} is an existing series and you say

\begin{code}
x = 100
\end{code} 

gretl will give the series a constant value of 100 rather than
complaining that you are trying to assign a scalar to a series. This
issue is particularly relevant for the matrix type---see
chapter~\ref{chap:matrices} for details.

Besides using the regular assignment operator you also have the option
of using an ``inflected'' equals sign, as in the C programming
language. This is shorthand for the case where the new value of the
variable is a function of the old value. For example,

\begin{code}
x += 100 # in longhand: x = x + 100
x *= 100 # in longhand: x = x * 100
\end{code} 

For scalar variables you can use a more condensed shorthand for simple
increment or decrement by 1, namely trailing \texttt{++} or \verb|--|
respectively:

\begin{code}
x = 100
x--     # x now equals 99
x++     # x now equals 100
\end{code}

In the case of objects holding more than one value---series, matrices
and bundles---you can modify particular values within the object using
an expression within square brackets to identify the elements to
access. We have discussed this above for the bundle type and
chapter~\ref{chap:matrices} goes into details for matrices. As for
series, there are two ways to specify particular values for
modification: you can use a simple 1-based index, or if the dataset is
a time series or panel (or if it has marker strings that identify the
observations) you can use an appropriate observation string. Such
strings are displayed by gretl when you print data with the
\verb|--byobs| flag. Examples:

\begin{code}
x[13]      = 100  # simple index: the 13th observation
x[1995:4]  = 100  # date: quarterly time series
x[2003:08] = 100  # date: monthly time series
x["AZ"]    = 100  # the observation with marker string "AZ"
x[3:15]    = 100  # panel: the 15th observation for the 3rd unit
\end{code}

Note that with quarterly or monthly time series there is no ambiguity
between a simple index number and a date, since dates always contain a
colon. With annual time-series data, however, such ambiguity exists
and it is resolved by the rule that a number in brackets is always
read as a simple index: \texttt{x[1905]} means the nineteen-hundred
and fifth observation, \textit{not} the observation for the year 1905.
You can specify a year by quotation, as in \verb|x["1905"]|.

\subsection{Destruction}

Objects of the types discussed above, \textit{with the important
  exception of named lists}, are all destroyed using the
\texttt{delete} command: \texttt{delete} \textsl{objectname}.

Lists are an exception for this reason: in the context of gretl
commands, a named list expands to the ID numbers of the member series,
so if you say

\begin{code}
delete L
\end{code} 

for \texttt{L} a list, the effect is to delete all the series in
\texttt{L}; the list itself is not destroyed, but ends up empty.  To
delete the list itself (without deleting the member series) you must
invert the command and use the \texttt{list} keyword:

\begin{code}
list L delete
\end{code}

Note that the \texttt{delete} command cannot be used within a
\texttt{loop} construct (see chapter~\ref{chap:looping}).
