Lists

Lists — handling of lists of integers

Synopsis

#include <libgretl.h>

#define             LISTSEP
int *               gretl_list_new                      (int nterms);
int *               gretl_list_resize                   (int **oldlist,
                                                         int nterms);
int *               gretl_list_append_term              (int **plist,
                                                         int v);
int *               gretl_list_sort                     (int *list);
int                 gretl_list_cmp                      (const int *list1,
                                                         const int *list2);
int *               gretl_null_list                     (void);
int *               gretl_consecutive_list_new          (int lmin,
                                                         int lmax);
int **              gretl_list_array_new                (int nlists,
                                                         int nterms);
void                gretl_list_array_free               (int **lists,
                                                         int nlists);
int *               gretl_list_copy                     (const int *src);
int *               gretl_list_copy_from_pos            (const int *src,
                                                         int pos);
int *               gretl_list_from_string              (const char *str,
                                                         int *err);
int *               gretl_list_from_vector              (const gretl_vector *v,
                                                         int *err);
char *              gretl_list_to_string                (const int *list);
char *              gretl_list_to_lags_string           (const int *list,
                                                         int *err);
char *              gretl_list_get_names                (const int *list,
                                                         const DATAINFO *pdinfo,
                                                         int *err);
int                 in_gretl_list                       (const int *list,
                                                         int k);
int                 gretl_list_delete_at_pos            (int *list,
                                                         int pos);
int                 gretl_list_purge_const              (int *list,
                                                         const double **Z,
                                                         const DATAINFO *pdinfo);
int                 gretl_list_min_max                  (const int *list,
                                                         int *lmin,
                                                         int *lmax);
int *               gretl_list_add                      (const int *orig,
                                                         const int *add,
                                                         int *err);
int *               gretl_list_union                    (const int *l1,
                                                         const int *l2,
                                                         int *err);
int *               gretl_list_intersection             (const int *l1,
                                                         const int *l2,
                                                         int *err);
int *               gretl_list_omit                     (const int *orig,
                                                         const int *omit,
                                                         int minpos,
                                                         int *err);
int *               gretl_list_omit_last                (const int *orig,
                                                         int *err);
int *               gretl_list_drop                     (const int *orig,
                                                         const int *drop,
                                                         int *err);
int                 gretl_list_diff                     (int *targ,
                                                         const int *biglist,
                                                         const int *sublist);
int *               gretl_list_diff_new                 (const int *biglist,
                                                         const int *sublist,
                                                         int minpos);
int *               gretl_list_build                    (const char *s,
                                                         const DATAINFO *pdinfo,
                                                         int *err);
int                 gretl_list_add_list                 (int **targ,
                                                         const int *src);
int                 gretl_list_insert_list              (int **targ,
                                                         const int *src,
                                                         int pos);
int                 gretl_list_insert_list_minus        (int **targ,
                                                         const int *src,
                                                         int pos);
int                 reglist_check_for_const             (int *list,
                                                         const double **Z,
                                                         const DATAINFO *pdinfo);
int                 gretl_list_const_pos                (const int *list,
                                                         int minpos,
                                                         const double **Z,
                                                         const DATAINFO *pdinfo);
int                 list_members_replaced               (const int *list,
                                                         const DATAINFO *pdinfo,
                                                         int ref_id);
int                 gretl_list_separator_position       (const int *list);
int                 gretl_list_has_separator            (const int *list);
int                 gretl_list_is_consecutive           (const int *list);
int                 gretl_list_split_on_separator       (const int *list,
                                                         int **plist1,
                                                         int **plist2);
int *               gretl_lists_join_with_separator     (const int *list1,
                                                         const int *list2);
int                 gretl_list_duplicates               (const int *list,
                                                         GretlCmdIndex ci);
int                 gretl_lists_share_members           (const int *list1,
                                                         const int *list2);
int                 gretl_list_n_distinct_members       (const int *list);
int *               full_var_list                       (const DATAINFO *pdinfo,
                                                         int *nvars);
int                 n_saved_lists                       (void);
int                 max_varno_in_saved_lists            (void);
const char *        get_list_name_by_index              (int idx);
int *               get_list_by_name                    (const char *name);
int                 append_to_list_by_name              (const char *targ,
                                                         const int *add);
int                 subtract_from_list_by_name          (const char *targ,
                                                         const int *sub);
int                 replace_list_by_name                (const char *targ,
                                                         const int *src);
int                 remember_list                       (const int *list,
                                                         const char *name,
                                                         PRN *prn);
int                 copy_named_list_as                  (const char *orig,
                                                         const char *newname);
int                 named_list_lower_level              (const char *name);
int                 rename_saved_list                   (const char *orig,
                                                         const char *newname);
int                 create_named_null_list              (const char *name);
int                 create_named_singleton_list         (int varnum,
                                                         const char *name);
int                 delete_list_by_name                 (const char *name);
int                 destroy_saved_lists_at_level        (int level);
int                 gretl_lists_revise                  (const int *dlist,
                                                         int dmin);
void                gretl_lists_cleanup                 (void);
int                 load_user_lists_file                (const char *fname);
int                 gretl_serialize_lists               (const char *fname);
void                gretl_list_print                    (const char *lname,
                                                         const DATAINFO *pdinfo,
                                                         PRN *prn);
int *               varname_match_list                  (const DATAINFO *pdinfo,
                                                         const char *pattern,
                                                         int *err);
int *               ellipsis_list                       (const DATAINFO *pdinfo,
                                                         int v1,
                                                         int v2,
                                                         int *err);
int                 varname_match_any                   (const DATAINFO *pdinfo,
                                                         const char *pattern);

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].

Details

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.

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.

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.

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.

list :

list to be sorted.

Returns :

the sorted list.

gretl_list_cmp ()

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

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.

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().

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.

lists :

array of gretl lists.

nlists :

the number of lists in lists.

gretl_list_copy ()

int *               gretl_list_copy                     (const int *src);

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);

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".

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);

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. This function is designed to handle positive integers in a range that is sensible for ID numbers of variables, typically with three digits or less, and will fail if the list contains any numbers greater than 9998.

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, separated by commas. Will fail if the list contains any numbers greater than 998.

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 DATAINFO *pdinfo,
                                                         int *err);

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

list :

array of integers.

pdinfo :

dataset information.

err :

location to receive error code.

Returns :

The string representation of the list on success, 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.

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.

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 double **Z,
                                                         const DATAINFO *pdinfo);

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).

list :

list of variable ID numbers.

Z :

data array.

pdinfo :

dataset information.

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.

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.

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.

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.

l1 :

list of integers.

l2 :

list of integers.

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.

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.

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.

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.

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);

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 DATAINFO *pdinfo,
                                                         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).

s :

string list specification.

pdinfo :

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.

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.

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).

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 double **Z,
                                                         const DATAINFO *pdinfo);

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.

list :

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

Z :

data array.

pdinfo :

dataset information.

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 double **Z,
                                                         const DATAINFO *pdinfo);

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.

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).

Z :

data array.

pdinfo :

dataset information.

Returns :

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

list_members_replaced ()

int                 list_members_replaced               (const int *list,
                                                         const DATAINFO *pdinfo,
                                                         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.

list :

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

pdinfo :

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);

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);

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);

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.

list :

source list.

plist1 :

pointer to accept first sub-list.

plist2 :

pointer to accept second sub-list.

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.

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.

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 :

1 if there are any elements in common between list1 and list2, otherwise 0.

gretl_list_n_distinct_members ()

int                 gretl_list_n_distinct_members       (const int *list);

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 DATAINFO *pdinfo,
                                                         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.

pdinfo :

dataset information.

nvars :

location for return of number of elements in full list.

Returns :

the allocated list, or NULL.

n_saved_lists ()

int                 n_saved_lists                       (void);

Returns :

the number of saved (named) lists currently defined.

max_varno_in_saved_lists ()

int                 max_varno_in_saved_lists            (void);

Returns :

the highest ID number of a variable referenced in a saved (named) list.

get_list_name_by_index ()

const char *        get_list_name_by_index              (int idx);

idx :

0-based index into array of saved lists.

Returns :

the name of the specified saved list, or NULL if idx is out of bounds.

get_list_by_name ()

int *               get_list_by_name                    (const char *name);

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

name :

the name of the list to be found.

Returns :

the list, or NULL if the lookup fails.

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.

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.

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.

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.

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.

copy_named_list_as ()

int                 copy_named_list_as                  (const char *orig,
                                                         const char *newname);

If a saved list is found by the name orig, a copy of this list is added to the stack of saved lists under the name newname. This is intended for use when a list is given as the argument to a user-defined function: it is copied under the name assigned by the function's parameter list.

orig :

the name of the original list.

newname :

the name to be given to the copy.

Returns :

0 on success, non-zero on error.

named_list_lower_level ()

int                 named_list_lower_level              (const char *name);

If a saved list is found by the name name, at the current level of function execution, lower its level by 1. This is intended for use when a list is returned by a user-defined function: it is shifted to the level of the caller.

name :

the name of the list.

Returns :

0 on success, non-zero on error.

rename_saved_list ()

int                 rename_saved_list                   (const char *orig,
                                                         const char *newname);

Renames a saved list from orig to new. If there is already a list called newname, it is destroyed.

orig :

the original name of the list.

newname :

the new name to be given.

Returns :

0 on success, non-zero on error.

create_named_null_list ()

int                 create_named_null_list              (const char *name);

Creates an empty list under the given name and adds it to the stack of saved lists at the next level of function execution. This is intended for use when a null list is given as an argument to a user-defined function.

name :

the name to be given to the list.

Returns :

0 on success, non-zero on error.

create_named_singleton_list ()

int                 create_named_singleton_list         (int varnum,
                                                         const char *name);


delete_list_by_name ()

int                 delete_list_by_name                 (const char *name);


destroy_saved_lists_at_level ()

int                 destroy_saved_lists_at_level        (int level);

Destroys and removes from the stack of saved lists all lists that were created at the given level. This is part of the cleanup that is performed when a user-defined function terminates.

level :

stack level of function execution.

Returns :

0 on success, non-zero on error.

gretl_lists_revise ()

int                 gretl_lists_revise                  (const int *dlist,
                                                         int dmin);

Goes through any saved lists, adjusting the ID numbers they contain to reflect the deletion from the dataset of certain variables: those referenced in dlist, if given, or if dlist is NULL, those variables with IDs greater than or equal to dmin.

dlist :

list of variables to be deleted (or NULL).

dmin :

lowest ID number of deleted var (referenced only if dlist is NULL).

Returns :

0 on success, non-zero code on failure.

gretl_lists_cleanup ()

void                gretl_lists_cleanup                 (void);

Frees all resources associated with the internal apparatus for saving and retrieving named lists.


load_user_lists_file ()

int                 load_user_lists_file                (const char *fname);


gretl_serialize_lists ()

int                 gretl_serialize_lists               (const char *fname);

Prints an XML representation of the current saved lists, if any.

fname :

name of file to which output should be written.

Returns :

0 on success, or if there are no saved lists, non-zero code on error.

gretl_list_print ()

void                gretl_list_print                    (const char *lname,
                                                         const DATAINFO *pdinfo,
                                                         PRN *prn);

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

lname :

name of list.

pdinfo :

dataset information.

prn :

gretl printing struct.

varname_match_list ()

int *               varname_match_list                  (const DATAINFO *pdinfo,
                                                         const char *pattern,
                                                         int *err);

pdinfo :

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 DATAINFO *pdinfo,
                                                         int v1,
                                                         int v2,
                                                         int *err);

pdinfo :

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 DATAINFO *pdinfo,
                                                         const char *pattern);

pdinfo :

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.