Lists

Lists — handling of lists of integers

Functions

#define LISTSEP
int * gretl_list_new ()
int * gretl_list_resize ()
int * gretl_list_append_term ()
int * gretl_list_sort ()
int gretl_list_cmp ()
int * gretl_null_list ()
int * gretl_consecutive_list_new ()
int ** gretl_list_array_new ()
void gretl_list_array_free ()
int * gretl_list_copy ()
int * gretl_list_copy_from_pos ()
int * gretl_list_from_string ()
int * gretl_list_from_vector ()
char * gretl_list_to_string ()
char * gretl_list_to_lags_string ()
char * gretl_list_get_names ()
char ** gretl_list_get_names_array ()
int in_gretl_list ()
int gretl_list_delete_at_pos ()
int gretl_list_purge_const ()
int gretl_list_min_max ()
int * gretl_list_add ()
int * gretl_list_union ()
int * gretl_list_intersection ()
int * gretl_list_product ()
int * gretl_list_omit ()
int * gretl_list_omit_last ()
int * gretl_list_drop ()
int gretl_list_diff ()
int * gretl_list_diff_new ()
int * gretl_list_build ()
int gretl_list_add_list ()
int gretl_list_insert_list ()
int gretl_list_insert_list_minus ()
int reglist_check_for_const ()
int gretl_list_const_pos ()
int list_members_replaced ()
int gretl_list_separator_position ()
int gretl_list_has_separator ()
int gretl_list_is_consecutive ()
int gretl_list_split_on_separator ()
int * gretl_lists_join_with_separator ()
int gretl_list_duplicates ()
int gretl_lists_share_members ()
int gretl_list_n_distinct_members ()
int * full_var_list ()
const char * saved_list_get_name ()
int * get_list_by_name ()
int gretl_is_list ()
int append_to_list_by_name ()
int subtract_from_list_by_name ()
int replace_list_by_name ()
int remember_list ()
void gretl_list_print ()
int * list_from_matrix ()
int * varname_match_list ()
int * ellipsis_list ()
int varname_match_any ()

Object Hierarchy


Includes

#include <libgretl.h>

Description

Lists of integers are used in many contexts in libgretl, e.g. for holding the ID numbers of variables in a regression specification. A gretl "list" is simply an array of ints following a definite convention: the value at position 0 gives the number of elements that follow. The total number of ints in the list foo is therefore foo[0] + 1, and reading the substantive members of foo involves looping from position 1 to position foo[0].

Functions

LISTSEP

#define LISTSEP (-100)

Symbolic name for the separator used in gretl lists; this corresponds to a semicolon in the string representation of a list.


gretl_list_new ()

int *
gretl_list_new (int nterms);

Creates a newly allocated list with space for nterms elements, besides the leading element, which in a gretl list always holds a count of the number of elements that follow. This leading element is initialized appropriately. For example, if nterms = 4, space for 5 integers is allocated and the first element of the array is set to 4. The other elements of the list are initialized to 0.

Parameters

nterms

the maximum number of elements to be stored in the list.

 

Returns

the newly allocated list, or NULL on failure.


gretl_list_resize ()

int *
gretl_list_resize (int **oldlist,
                   int nterms);

Resizes the content of oldlist to hold nterms , and adjusts the first element to reflect the new size. If the new list is longer than the old, the extra elements are initialized to zero.

Parameters

oldlist

pointer to list to be resized.

 

nterms

the new maximum number of elements for the list.

 

Returns

the resized list, or NULL on failure.


gretl_list_append_term ()

int *
gretl_list_append_term (int **plist,
                        int v);

Resizes (or allocates from scratch) the content of plist , so that it can hold one extra element, and sets the last element to v .

Parameters

plist

pointer to list to be augmented.

 

v

the term to be added.

 

Returns

the augmented list, or NULL on failure.


gretl_list_sort ()

int *
gretl_list_sort (int *list);

Sorts the elements from position 1 to the end of list in ascending order.

Parameters

list

list to be sorted.

 

Returns

the sorted list.


gretl_list_cmp ()

int
gretl_list_cmp (const int *list1,
                const int *list2);

Parameters

list1

gretl list.

 

list2

gretl list.

 

Returns

0 if list1 and list2 have identical content, otherwise 1.


gretl_null_list ()

int *
gretl_null_list (void);

Creates a newly allocated "list" with only one member, which is set to zero.

Returns

the newly allocated list, or NULL on failure.


gretl_consecutive_list_new ()

int *
gretl_consecutive_list_new (int lmin,
                            int lmax);

Creates a newly allocated list whose elements run from lmin to lmax consecutively.

Parameters

lmin

starting value for consecutive list elements.

 

lmax

ending value.

 

Returns

the newly allocated list, or NULL on failure.


gretl_list_array_new ()

int **
gretl_list_array_new (int nlists,
                      int nterms);

Creates an array of newly allocated lists, each of which as described in connection with gretl_list_new().

Parameters

nlists

the number of lists to create.

 

nterms

the maximum number of elements to be stored in each list.

 

Returns

the newly allocated lists, or NULL on failure.


gretl_list_array_free ()

void
gretl_list_array_free (int **lists,
                       int nlists);

Frees all the lists in lists and also the top-level pointer.

Parameters

lists

array of gretl lists.

 

nlists

the number of lists in lists .

 

gretl_list_copy ()

int *
gretl_list_copy (const int *src);

Parameters

src

an array of integers, the first element of which holds a count of the number of elements following.

 

Returns

an allocated copy src (or NULL if src is NULL).


gretl_list_copy_from_pos ()

int *
gretl_list_copy_from_pos (const int *src,
                          int pos);

Parameters

src

an array of integers, the first element of which holds a count of the number of elements following.

 

Returns

an allocated copy src from position pos onward (or NULL on failure).


gretl_list_from_string ()

int *
gretl_list_from_string (const char *str,
                        int *err);

Reads a string containing a list of integers, separated by spaces and/or commas and possibly wrapped in parentheses, and constructs an array of these integers. The first element is the number of integers that follow. This function supports an abbreviation for consecutive (increasing) integers in the list, using the notation, e.g., "1-4" as shorthand for "1 2 3 4".

Parameters

str

string representation of list of integers.

 

err

location to receive error code.

 

Returns

the allocated array, or NULL on failure.


gretl_list_from_vector ()

int *
gretl_list_from_vector (const gretl_vector *v,
                        int *err);

Parameters

v

source vector.

 

Returns

a newly allocated gretl list containing the values in v , or NULL on failure. Note that it is an error if v is NULL, or is not a vector.


gretl_list_to_string ()

char *
gretl_list_to_string (const int *list);

Prints the given list of integers into a newly allocated string, separated by single spaces and with one leading space.

Parameters

list

array of integers.

 

Returns

The string representation of the list on success, or NULL on failure.


gretl_list_to_lags_string ()

char *
gretl_list_to_lags_string (const int *list,
                           int *err);

Prints the given list of integers into a newly allocated string, enclosed by braces and separated by commas. Will fail if list contains any numbers greater than 998.

Parameters

list

array of integers.

 

err

location to receive error code.

 

Returns

The string representation of the list on success, or NULL on failure.


gretl_list_get_names ()

char *
gretl_list_get_names (const int *list,
                      const DATASET *dset,
                      int *err);

Prints the names of the members of list of integers into a newly allocated string, separated by commas.

Parameters

list

array of integers.

 

dset

dataset information.

 

err

location to receive error code.

 

Returns

The string representation of the list on success, or NULL on failure.


gretl_list_get_names_array ()

char **
gretl_list_get_names_array (const int *list,
                            const DATASET *dset,
                            int *err);

Parameters

list

array of integers.

 

dset

dataset information.

 

err

location to receive error code.

 

Returns

An array of strings holding the names of the members of list , or NULL on failure.


in_gretl_list ()

int
in_gretl_list (const int *list,
               int k);

Checks whether k is present among the members of list , in position 1 or higher.

Parameters

list

an array of integers, the first element of which holds a count of the number of elements following.

 

k

integer to test.

 

Returns

the position of k in list , or 0 if k is not present.


gretl_list_delete_at_pos ()

int
gretl_list_delete_at_pos (int *list,
                          int pos);

Deletes the element at position pos from list and moves any remaining elements forward. Decrements the value of the first, counter, element of list .

Parameters

list

an array of integers, the first element of which holds a count of the number of elements following.

 

pos

position at which to delete list element.

 

Returns

0 on success, 1 on error.


gretl_list_purge_const ()

int
gretl_list_purge_const (int *list,
                        const DATASET *dset);

Checks list from position 1 onward for the presence of a variable whose valid values in sample all equal 1.0. If such a variable is found, it is deleted from list (that is, any following elements are moved forward by one and list[0] is decremented by 1).

Parameters

list

list of variable ID numbers.

 

dset

dataset struct.

 

Returns

1 if a constant was found and deleted, else 0.


gretl_list_min_max ()

int
gretl_list_min_max (const int *list,
                    int *lmin,
                    int *lmax);

Reads list from position 1 onward and writes to lmin and lmax the minimum and maximum values among the elements of the list. Reading stops at the end of the list or when a list separator is encountered.

Parameters

list

gretl list.

 

lmin

location to receive minimum value.

 

lmax

location to receive maximum value.

 

Returns

0 on successful completion, error code if the list is NULL or empty.


gretl_list_add ()

int *
gretl_list_add (const int *orig,
                const int *add,
                int *err);

Creates a list containing the union of elements of orig and the elements of add . If one or more elements of add were already present in orig , the error code is E_ADDDUP.

Parameters

orig

an array of integers, the first element of which holds a count of the number of elements following.

 

add

list of variables to be added.

 

err

location to receive error code.

 

Returns

new list on success, NULL on error.


gretl_list_union ()

int *
gretl_list_union (const int *l1,
                  const int *l2,
                  int *err);

Creates a list holding the union of l1 and l2 .

Parameters

l1

list of integers.

 

l2

list of integers.

 

err

location to receive error code.

 

Returns

new list on success, NULL on error.


gretl_list_intersection ()

int *
gretl_list_intersection (const int *l1,
                         const int *l2,
                         int *err);

Creates a list holding the intersection of l1 and l2 .

Parameters

l1

list of integers.

 

l2

list of integers.

 

err

location to receive error code.

 

Returns

new list on success, NULL on error.


gretl_list_product ()

int *
gretl_list_product (const int *X,
                    const int *Y,
                    DATASET *dset,
                    int *err);

Creates a list holding the Cartesian product of X and Y .

Parameters

X

list of integers (representing discrete variables).

 

Y

list of integers.

 

dset

pointer to dataset.

 

err

location to receive error code.

 

Returns

new list on success, NULL on error.


gretl_list_omit ()

int *
gretl_list_omit (const int *orig,
                 const int *omit,
                 int minpos,
                 int *err);

Creates a list containing the elements of orig that are not present in omit . It is an error if the omit list contains members that are not present in orig , and also if the omit list contains duplicated elements.

Parameters

orig

an array of integers, the first element of which holds a count of the number of elements following.

 

omit

list of variables to drop.

 

minpos

minimum position to check. This should be 2 for a regular regression list, to skip the dependent var in position 1; but in other contexts it may be 1 to start from the first element of orig .

 

err

pointer to receive error code.

 

Returns

new list on success, NULL on error.


gretl_list_omit_last ()

int *
gretl_list_omit_last (const int *orig,
                      int *err);

Creates a list containing all but the last element of orig , which must not contain LISTSEP and must contain at least two members.

Parameters

orig

an array of integers, the first element of which holds a count of the number of elements following.

 

err

location to receive error code.

 

Returns

new list on success, NULL on error.


gretl_list_drop ()

int *
gretl_list_drop (const int *orig,
                 const int *drop,
                 int *err);

Creates a list containing the elements of orig that are not present in drop . Unlike gretl_list_omit(), processing always starts from position 1 in orig , and it is not an error if some members of drop are not present in orig , or if some members of drop are duplicated.

Parameters

orig

an array of integers, the first element of which holds a count of the number of elements following.

 

drop

list of variables to drop.

 

err

pointer to receive error code.

 

Returns

new list on success, NULL on error.


gretl_list_diff ()

int
gretl_list_diff (int *targ,
                 const int *biglist,
                 const int *sublist);

Fills out targ with the elements of biglist , from position 2 onwards, that are not present in sublist . It is assumed that the variable ID number in position 1 (dependent variable) is the same in both lists. It is an error if, from position 2 on, sublist is not a proper subset of biglist . See also gretl_list_diff_new.

Parameters

targ

target list (must be pre-allocated).

 

biglist

inclusive list.

 

sublist

subset of biglist.

 

Returns

0 on success, 1 on error.


gretl_list_diff_new ()

int *
gretl_list_diff_new (const int *biglist,
                     const int *sublist,
                     int minpos);

Parameters

biglist

inclusive list.

 

sublist

subset of biglist.

 

minpos

position in lists at which to start.

 

Returns

a newly allocated list including the elements of biglist , from position minpos onwards, that are not present in sublist , again from minpos onwards, or NULL on failure. Note that comparison stops whenever a list separator is found; i.e. only the pre-separator portions of the lists are compared.


gretl_list_build ()

int *
gretl_list_build (const char *s,
                  const DATASET *dset,
                  int *err);

Builds a list based on the specification in s , which may include the ID numbers of variables, the names of variables, and/or the names of previously defined lists (all separated by spaces).

Parameters

s

string list specification.

 

dset

dataset information.

 

err

location to receive error code

 

Returns

the constructed list, or NULL on failure.


gretl_list_add_list ()

int
gretl_list_add_list (int **targ,
                     const int *src);

Adds src onto the end of targ . The length of targ becomes the sum of the lengths of the two original lists.

Parameters

targ

location of list to which src should be added.

 

src

list to be added to targ .

 

Returns

0 on success, non-zero on failure.


gretl_list_insert_list ()

int
gretl_list_insert_list (int **targ,
                        const int *src,
                        int pos);

Inserts src into targ at pos . The length of targ becomes the sum of the lengths of the two original lists.

Parameters

targ

location of list into which src should be inserted.

 

src

list to be inserted.

 

pos

zero-based position at which src should be inserted.

 

Returns

0 on success, non-zero on failure.


gretl_list_insert_list_minus ()

int
gretl_list_insert_list_minus (int **targ,
                              const int *src,
                              int pos);

Inserts src into targ at pos . The length of targ becomes the sum of the lengths of the two original lists minus one. This can be useful if we were expecting to insert a single variable but found we had to insert a list instead. Insertion of src overwrites any entries in targ beyond pos (the expectation is that this function will be called in the process of assembling targ , in left-to-right mode).

Parameters

targ

location of list into which src should be inserted.

 

src

list to be inserted.

 

pos

zero-based position at which src should be inserted.

 

Returns

0 on success, non-zero on failure.


reglist_check_for_const ()

int
reglist_check_for_const (int *list,
                         const DATASET *dset);

Checks list for an intercept term (a variable all of whose valid values in sample are 1). If such a variable is present, it is moved to position 2 in the list.

Parameters

list

regression list suitable for use with a gretl model (should not contain LISTSEP).

 

dset

dataset struct.

 

Returns

1 if the list contains an intercept, else 0.


gretl_list_const_pos ()

int
gretl_list_const_pos (const int *list,
                      int minpos,
                      const DATASET *dset);

Checks list for the presence, in position minpos or higher, of a variable whose valid values in sample all equal 1. This usually amounts to checking whether a list of regressors includes an intercept term.

Parameters

list

an array of integer variable ID numbers, the first element of which holds a count of the number of elements following.

 

minpos

position in list at which to start the search (>= 1).

 

dset

dataset struct.

 

Returns

The list position of the const, or 0 if none is found.


list_members_replaced ()

int
list_members_replaced (const int *list,
                       const DATASET *dset,
                       int ref_id);

Checks whether any variable in list has been redefined via gretl's genr command since a previous model (identified by ref_id ) was estimated.

Parameters

list

an array of integer variable ID numbers, the first element of which holds a count of the number of elements following.

 

dset

dataset information.

 

ref_id

ID number of reference MODEL.

 

Returns

1 if any variables have been replaced, 0 otherwise.


gretl_list_separator_position ()

int
gretl_list_separator_position (const int *list);

Parameters

list

an array of integer variable ID numbers, the first element of which holds a count of the number of elements following.

 

Returns

if list contains the separator for compound lists, LISTSEP, the position in list at which this is found, else 0. The search begins at position 1.


gretl_list_has_separator ()

int
gretl_list_has_separator (const int *list);

Parameters

list

an array of integer variable ID numbers, the first element of which holds a count of the number of elements following.

 

Returns

1 if list contains the separator for compound lists, LISTSEP, else 0. The search begins at position 1.


gretl_list_is_consecutive ()

int
gretl_list_is_consecutive (const int *list);

Parameters

list

list to check.

 

Returns

1 if the elements of list , from position 1 onward, are consecutive integer values, else 0.


gretl_list_split_on_separator ()

int
gretl_list_split_on_separator (const int *list,
                               int **plist1,
                               int **plist2);

If list contains the list separator, LISTSEP, creates two sub-lists, one containing the elements of list preceding the separator and one containing the elements following the separator. The sub-lists are newly allocated, and assigned as the content of plist1 and plist2 respectively. Note, however, that one or other of the sublists can be discarded by passing NULL as the second or third argument.

Parameters

list

source list.

 

plist1

pointer to accept first sub-list, or NULL.

 

plist2

pointer to accept second sub-list, or NULL.

 

Returns

0 on success, E_ALLOC is memory allocation fails, or E_DATA if list does not contain a separator.


gretl_lists_join_with_separator ()

int *
gretl_lists_join_with_separator (const int *list1,
                                 const int *list2);

Concatenates the content of list2 onto list1 , after first appending the list separator. It is acceptable that list1 be NULL, in which case the returned list is just list2 with the separator prepended. But it is not acceptable that list2 be null; in that this function returns NULL.

Parameters

list1

first sub-list.

 

list2

second sub-list.

 

Returns

alllcated list on success or NULL on failure.


gretl_list_duplicates ()

int
gretl_list_duplicates (const int *list,
                       GretlCmdIndex ci);

Checks whether or not a gretl list contains duplicated elements. Exactly what counts as duplication depends on the context of the command in which list will be used, which is given by ci .

Parameters

list

an array of integer variable ID numbers, the first element of which holds a count of the number of elements following.

 

ci

index of gretl command (for context).

 

Returns

the ID number of the first duplicated variable found, or -1 in case of no duplication.


gretl_lists_share_members ()

int
gretl_lists_share_members (const int *list1,
                           const int *list2);

Returns

the number of elements that are in common between list1 and list2 .


gretl_list_n_distinct_members ()

int
gretl_list_n_distinct_members (const int *list);

Parameters

list

list to test.

 

Returns

the count of distinct elements in list from position 1 onward, not counting LISTSEP if present.


full_var_list ()

int *
full_var_list (const DATASET *dset,
               int *nvars);

Creates a newly allocated list including all series in the dataset that are not hidden variables, and are accessible at the current level of function execution. The return value is NULL in case either (a) allocation of memory failed, or (b) the resulting list would be empty. The caller can distinguish between these possibilities by examining the value returned in nvars , which will be zero if and only if the resulting list would be empty. If this is not of interest to the caller, nvars may be given as NULL.

Parameters

dset

dataset information.

 

nvars

location for return of number of elements in full list.

 

Returns

the allocated list, or NULL.


saved_list_get_name ()

const char *
saved_list_get_name (const int *list);

Parameters

list

list whose name should be retrieved.

 

Returns

the name of the specified saved list, or NULL if there is no match.


get_list_by_name ()

int *
get_list_by_name (const char *name);

Looks up name in the stack of saved variables, at the current level of function execution, and retrieves the associated list.

Parameters

name

the name of the list to be found.

 

Returns

the list, or NULL if the lookup fails.


gretl_is_list ()

int
gretl_is_list (const char *name);

Parameters

name

the name to test.

 

Returns

1 if name is the name of a saved list, 0 otherwise.


append_to_list_by_name ()

int
append_to_list_by_name (const char *targ,
                        const int *add);

If targ is the name of a saved list, append the list add to it.

Parameters

targ

the name of the target list.

 

add

list to add.

 

Returns

0 on success, non-zero code on failure.


subtract_from_list_by_name ()

int
subtract_from_list_by_name (const char *targ,
                            const int *sub);

If targ is the name of a saved list, remove from targ any elements of sub that it contains.

Parameters

targ

the name of the target list.

 

sub

sub-list to remove.

 

Returns

0 on success, non-zero code on failure.


replace_list_by_name ()

int
replace_list_by_name (const char *targ,
                      const int *src);

If targ is the name of a saved list, replace the list of that name with src .

Parameters

targ

the name of the target list.

 

src

replacement list

 

Returns

0 on success, non-zero code on failure.


remember_list ()

int
remember_list (const int *list,
               const char *name,
               PRN *prn);

Adds a copy of list to the stack of saved lists and associates it with name , unless there is already a list with the given name in which case the original list is replaced. A status message is printed to prn .

Parameters

list

array of integers, the first element being a count of the following elements.

 

name

name to be given to the list.

 

prn

printing struct.

 

Returns

0 on success, non-zero code on error.


gretl_list_print ()

void
gretl_list_print (const char *lname,
                  const DATASET *dset,
                  PRN *prn);

Prints to prn the given list of variables, by name.

Parameters

lname

name of list.

 

dset

dataset information.

 

prn

gretl printing struct.

 

list_from_matrix ()

int *
list_from_matrix (const gretl_matrix *m,
                  const DATASET *dset,
                  int *err);

Tries to interpret the matrix m as a list of ID numbers of series. This can work only if m is a vector, and all its elements have integer values k satisfying 0 <= k < v, where v is the number of series in dset . In the special case where m is a null matrix, an empty list is returned.

Parameters

m

matrix (must be a vector).

 

dset

pointer to dataset.

 

err

location to receive error code.

 

Returns

a gretl list, or NULL on failure.


varname_match_list ()

int *
varname_match_list (const DATASET *dset,
                    const char *pattern,
                    int *err);

Parameters

dset

pointer to dataset information.

 

pattern

pattern to be matched.

 

err

location to receive error code.

 

Returns

a list of ID numbers of variables whose names match pattern , or NULL if there are no matches.


ellipsis_list ()

int *
ellipsis_list (const DATASET *dset,
               int v1,
               int v2,
               int *err);

Parameters

dset

pointer to dataset information.

 

v1

index of first variable.

 

v2

index of last variable.

 

err

location to receive error code.

 

Returns

a list of ID numbers of variables running from v1 to v2 .


varname_match_any ()

int
varname_match_any (const DATASET *dset,
                   const char *pattern);

Parameters

dset

pointer to dataset information.

 

pattern

pattern to be matched.

 

Returns

1 if at least one variable in the dataset has a name that matches pattern , otherwise 0.

Types and Values