gretl_bundle

gretl_bundle

Functions

gretl_bundle * gretl_bundle_new ()
int gretl_is_bundle ()
int type_can_be_bundled ()
gretl_bundle * get_bundle_by_name ()
void * gretl_bundle_get_content ()
void * gretl_bundle_get_data ()
void * gretl_bundle_steal_data ()
void * gretl_bundle_get_private_data ()
GretlType gretl_bundle_get_member_type ()
int gretl_bundle_has_key ()
gretl_matrix * gretl_bundle_get_matrix ()
double * gretl_bundle_get_series ()
int * gretl_bundle_get_list ()
double gretl_bundle_get_scalar ()
int gretl_bundle_get_int ()
const char * gretl_bundle_get_string ()
void * gretl_bundle_get_array ()
const char * gretl_bundle_get_note ()
const char * gretl_bundle_get_creator ()
void * bundled_item_get_data ()
const char * bundled_item_get_note ()
int gretl_bundle_donate_data ()
int gretl_bundle_set_data ()
int gretl_bundle_set_string ()
int gretl_bundle_set_scalar ()
int gretl_bundle_set_int ()
int gretl_bundle_set_series ()
int gretl_bundle_set_list ()
int gretl_bundle_set_matrix ()
int gretl_bundle_set_note ()
int gretl_bundle_delete_data ()
int gretl_bundle_add_or_replace ()
int gretl_bundle_copy_as ()
gretl_bundle * gretl_bundle_copy ()
int gretl_bundle_set_creator ()
int gretl_bundle_print ()
int gretl_bundle_is_stacked ()
int gretl_bundle_get_n_keys ()
int gretl_bundle_get_n_members ()
int gretl_bundle_has_content ()
gretl_bundle * gretl_bundle_pull_from_stack ()
gretl_bundle * gretl_bundle_union ()
void gretl_bundle_destroy ()
void gretl_bundle_void_content ()
void gretl_bundle_serialize ()
gretl_bundle * gretl_bundle_deserialize ()
int gretl_bundle_write_to_file ()
char * gretl_bundle_write_to_buffer ()
gretl_bundle * gretl_bundle_read_from_file ()
gretl_bundle * gretl_bundle_read_from_buffer ()
gretl_bundle * get_sysinfo_bundle ()
void * sysinfo_bundle_get_data ()
gretl_bundle * bundle_from_model ()
gretl_bundle * kalman_bundle_new ()
void gretl_bundle_cleanup ()

Types and Values

#define BUNDLE_PRINT
#define BUNDLE_PLOT
#define BUNDLE_TEST
#define BUNDLE_FCAST
#define BUNDLE_EXTRA
#define GUI_MAIN
#define GUI_PRECHECK
#define LIST_MAKER
enum BundleType
typedef gretl_bundle
typedef bundled_item

Description

Functions

gretl_bundle_new ()

gretl_bundle *
gretl_bundle_new (void);

Returns

a newly allocated, empty gretl bundle.


gretl_is_bundle ()

int
gretl_is_bundle (const char *name);

type_can_be_bundled ()

int
type_can_be_bundled (GretlType type);

get_bundle_by_name ()

gretl_bundle *
get_bundle_by_name (const char *name);

Parameters

name

the name to look up.

 

Returns

pointer to a saved bundle, if found, else NULL.


gretl_bundle_get_content ()

void *
gretl_bundle_get_content (gretl_bundle *bundle);

Parameters

bundle

bundle to access.

 

Returns

the content of bundle , which is in fact a GHashTable object.


gretl_bundle_get_data ()

void *
gretl_bundle_get_data (gretl_bundle *bundle,
                       const char *key,
                       GretlType *type,
                       int *size,
                       int *err);

Parameters

bundle

bundle to access.

 

key

name of key to access.

 

type

location to receive data type, or NULL.

 

size

location to receive size of data (= series length for GRETL_TYPE_SERIES, otherwise 0), or NULL.

 

err

location to receive error code.

 

Returns

the item pointer associated with key in the specified bundle , or NULL if there is no such item. If err is non-NULL, its content is set to a non-zero value if bundle contains no item with key key . If the intent is simply to determine whether bundle contains an item under the specified key , err should generally be left NULL.

Note that the value returned is the actual data pointer from within the bundle, not a copy of the data; so the pointer must not be freed, and in general its content should not be modified.


gretl_bundle_steal_data ()

void *
gretl_bundle_steal_data (gretl_bundle *bundle,
                         const char *key,
                         GretlType *type,
                         int *size,
                         int *err);

Works like gretl_bundle_get_data() except that the data pointer in question is removed from bundle before it is returned to the caller; so in effect the caller assumes ownership of the item.

Parameters

bundle

bundle to access.

 

key

name of key to access.

 

type

location to receive data type, or NULL.

 

size

location to receive size of data (= series length for GRETL_TYPE_SERIES, otherwise 0), or NULL.

 

err

location to receive error code, or NULL.

 

Returns

the item pointer associated with key in the specified bundle , or NULL if there is no such item.


gretl_bundle_get_private_data ()

void *
gretl_bundle_get_private_data (gretl_bundle *bundle);

gretl_bundle_get_member_type ()

GretlType
gretl_bundle_get_member_type (gretl_bundle *bundle,
                              const char *key,
                              int *err);

Parameters

bundle

bundle to access.

 

key

name of key to access.

 

err

location to receive error code.

 

Returns

the data type associated with key in the specified bundle , or 0 on failure.


gretl_bundle_has_key ()

int
gretl_bundle_has_key (gretl_bundle *bundle,
                      const char *key);

Parameters

bundle

bundle to access.

 

key

name of key to test.

 

Returns

1 if there is an item under the given key in the specified bundle , 0 otherwise.


gretl_bundle_get_matrix ()

gretl_matrix *
gretl_bundle_get_matrix (gretl_bundle *bundle,
                         const char *key,
                         int *err);

Parameters

bundle

bundle to access.

 

key

name of key to access.

 

err

location to receive error code.

 

Returns

the matrix associated with key in the specified bundle , if any; otherwise NULL.


gretl_bundle_get_series ()

double *
gretl_bundle_get_series (gretl_bundle *bundle,
                         const char *key,
                         int *n,
                         int *err);

Parameters

bundle

bundle to access.

 

key

name of key to access.

 

n

location to receive length of series.

 

err

location to receive error code.

 

Returns

the series associated with key in the specified bundle , if any; otherwise NULL.


gretl_bundle_get_list ()

int *
gretl_bundle_get_list (gretl_bundle *bundle,
                       const char *key,
                       int *err);

Parameters

bundle

bundle to access.

 

key

name of key to access.

 

err

location to receive error code.

 

Returns

the list associated with key in the specified bundle , if any; otherwise NULL.


gretl_bundle_get_scalar ()

double
gretl_bundle_get_scalar (gretl_bundle *bundle,
                         const char *key,
                         int *err);

Parameters

bundle

bundle to access.

 

key

name of key to access.

 

err

location to receive error code.

 

Returns

the scalar value associated with key in the specified bundle , if any; otherwise NADBL.


gretl_bundle_get_int ()

int
gretl_bundle_get_int (gretl_bundle *bundle,
                      const char *key,
                      int *err);

Parameters

bundle

bundle to access.

 

key

name of key to access.

 

err

location to receive error code.

 

Returns

the integer value associated with key in the specified bundle , if any; otherwise 0.


gretl_bundle_get_string ()

const char *
gretl_bundle_get_string (gretl_bundle *bundle,
                         const char *key,
                         int *err);

Parameters

bundle

bundle to access.

 

key

name of key to access.

 

err

location to receive error code.

 

Returns

the string value associated with key in the specified bundle , if any; otherwise NADBL.


gretl_bundle_get_array ()

void *
gretl_bundle_get_array (gretl_bundle *bundle,
                        const char *key,
                        int *err);

Parameters

bundle

bundle to access.

 

key

name of key to access.

 

err

location to receive error code.

 

Returns

the array associated with key in the specified bundle , if any; otherwise NULL.


gretl_bundle_get_note ()

const char *
gretl_bundle_get_note (gretl_bundle *bundle,
                       const char *key);

Parameters

bundle

bundle to access.

 

key

name of key to access.

 

Returns

the note associated with key in the specified bundle , if any; otherwise NULL.


gretl_bundle_get_creator ()

const char *
gretl_bundle_get_creator (gretl_bundle *bundle);

Parameters

bundle

bundle to access.

 

Returns

the name of the package that created bundle , if any, otherwise NULL.


bundled_item_get_data ()

void *
bundled_item_get_data (bundled_item *item,
                       GretlType *type,
                       int *size);

Parameters

item

bundled item to access.

 

type

location to receive data type.

 

size

location to receive size of data (= series length for GRETL_TYPE_SERIES, otherwise 0).

 

Returns

the data pointer associated with item , or NULL on failure.


bundled_item_get_note ()

const char *
bundled_item_get_note (bundled_item *item);

Parameters

item

bundled item.

 

Returns

the note associated with item (may be NULL).


gretl_bundle_donate_data ()

int
gretl_bundle_donate_data (gretl_bundle *bundle,
                          const char *key,
                          void *ptr,
                          GretlType type,
                          int size);

Sets the data type and pointer to be associated with key in the bundle given by name . If key is already present in the bundle's hash table the original value is replaced and destroyed. The value of ptr is transcribed into the bundle, which therefore "takes ownership" of the data; compare gretl_bundle_set_data().

Parameters

bundle

target bundle.

 

key

name of key to create or replace.

 

ptr

data pointer.

 

type

type of data.

 

size

if type == GRETL_TYPE_SERIES, the length of the series, otherwise 0.

 

Returns

0 on success, error code on error.


gretl_bundle_set_data ()

int
gretl_bundle_set_data (gretl_bundle *bundle,
                       const char *key,
                       void *ptr,
                       GretlType type,
                       int size);

Sets the data type and pointer to be associated with key in the bundle given by name . If key is already present in the bundle's hash table the original value is replaced and destroyed. The content of ptr is copied into the bundle; compare gretl_bundle_donate_data().

Parameters

bundle

target bundle.

 

key

name of key to create or replace.

 

ptr

data pointer.

 

type

type of data.

 

size

if type == GRETL_TYPE_SERIES, the length of the series, otherwise 0.

 

Returns

0 on success, error code on error.


gretl_bundle_set_string ()

int
gretl_bundle_set_string (gretl_bundle *bundle,
                         const char *key,
                         const char *str);

Sets str as a member of bundle under the name key . If key is already present in the bundle the original value is replaced and destroyed.

Parameters

bundle

target bundle.

 

key

name of key to create or replace.

 

str

the string to set.

 

Returns

0 on success, error code on error.


gretl_bundle_set_scalar ()

int
gretl_bundle_set_scalar (gretl_bundle *bundle,
                         const char *key,
                         double val);

Sets val as a member of bundle under the name key . If key is already present in the bundle the original value is replaced and destroyed.

Parameters

bundle

target bundle.

 

key

name of key to create or replace.

 

val

the value to set.

 

Returns

0 on success, error code on error.


gretl_bundle_set_int ()

int
gretl_bundle_set_int (gretl_bundle *bundle,
                      const char *key,
                      int val);

Sets val as a member of bundle under the name key . If key is already present in the bundle the original value is replaced and destroyed.

Parameters

bundle

target bundle.

 

key

name of key to create or replace.

 

val

the value to set.

 

Returns

0 on success, error code on error.


gretl_bundle_set_series ()

int
gretl_bundle_set_series (gretl_bundle *bundle,
                         const char *key,
                         const double *x,
                         int n);

Sets x as a member of bundle under the name key . If key is already present in the bundle the original value is replaced and destroyed.

Parameters

bundle

target bundle.

 

key

name of key to create or replace.

 

x

array of doubles.

 

n

the length of x .

 

Returns

0 on success, error code on error.


gretl_bundle_set_list ()

int
gretl_bundle_set_list (gretl_bundle *bundle,
                       const char *key,
                       const int *list);

Sets list as a member of bundle under the name key . If key is already present in the bundle the original value is replaced and destroyed.

Parameters

bundle

target bundle.

 

key

name of key to create or replace.

 

list

gretl list.

 

Returns

0 on success, error code on error.


gretl_bundle_set_matrix ()

int
gretl_bundle_set_matrix (gretl_bundle *bundle,
                         const char *key,
                         const gretl_matrix *m);

Sets m as a member of bundle under the name key . If key is already present in the bundle the original value is replaced and destroyed.

Parameters

bundle

target bundle.

 

key

name of key to create or replace.

 

m

gretl matrix.

 

Returns

0 on success, error code on error.


gretl_bundle_set_note ()

int
gretl_bundle_set_note (gretl_bundle *bundle,
                       const char *key,
                       const char *note);

Adds a descriptive note to the item under key in bundle . If a note is already present it is replaced by the new one.

Parameters

bundle

target bundle.

 

key

name of key to access.

 

note

note to add.

 

Returns

0 on success, error code on error.


gretl_bundle_delete_data ()

int
gretl_bundle_delete_data (gretl_bundle *bundle,
                          const char *key);

Deletes the data item under key from bundle , if such an item is present.

Parameters

bundle

target bundle.

 

key

name of key to delete.

 

gretl_bundle_add_or_replace ()

int
gretl_bundle_add_or_replace (gretl_bundle *bundle,
                             const char *name);

gretl_bundle_copy_as ()

int
gretl_bundle_copy_as (const char *name,
                      const char *copyname);

Look for a saved bundle specified by name , and if found, make a full copy and save it under copyname . This is called from geneval.c on completion of assignment to a bundle named copyname , where the returned value on the right-hand side is a pre-existing saved bundle.

Parameters

name

name of source bundle.

 

copyname

name for copy.

 

Returns

0 on success, non-zero code on error.


gretl_bundle_copy ()

gretl_bundle *
gretl_bundle_copy (const gretl_bundle *bundle,
                   int *err);

Parameters

bundle

gretl bundle to be copied.

 

err

location to receive error code.

 

Returns

a "deep copy" of bundle (all the items in bundle are themselves copied), or NULL on failure.


gretl_bundle_set_creator ()

int
gretl_bundle_set_creator (gretl_bundle *b,
                          const char *name);

Sets the "creator" attribute of bundle . This is called automatically when a bundle is returned to top-level userspace by a packaged function.

Parameters

bundle

target bundle.

 

name

name of function package that built the bundle.

 

Returns

0 on success, error code on error.


gretl_bundle_print ()

int
gretl_bundle_print (gretl_bundle *bundle,
                    PRN *prn);

Prints to prn a list of the keys defined in bundle , along with descriptive notes, if any.

Parameters

bundle

gretl bundle.

 

prn

gretl printer.

 

Returns

0 on success, non-zero code on failure.


gretl_bundle_is_stacked ()

int
gretl_bundle_is_stacked (gretl_bundle *b);

gretl_bundle_get_n_keys ()

int
gretl_bundle_get_n_keys (gretl_bundle *b);

gretl_bundle_get_n_members ()

int
gretl_bundle_get_n_members (gretl_bundle *b);

gretl_bundle_has_content ()

int
gretl_bundle_has_content (gretl_bundle *b);

gretl_bundle_pull_from_stack ()

gretl_bundle *
gretl_bundle_pull_from_stack (const char *name,
                              int *err);

gretl_bundle_union ()

gretl_bundle *
gretl_bundle_union (const gretl_bundle *bundle1,
                    const gretl_bundle *bundle2,
                    int *err);

gretl_bundle_destroy ()

void
gretl_bundle_destroy (gretl_bundle *bundle);

Frees all contents of bundle as well as the pointer itself.

Parameters

bundle

bundle to destroy.

 

gretl_bundle_void_content ()

void
gretl_bundle_void_content (gretl_bundle *bundle);

Frees all contents of bundle .

Parameters

bundle

target bundle.

 

gretl_bundle_serialize ()

void
gretl_bundle_serialize (gretl_bundle *b,
                        const char *name,
                        FILE *fp);

gretl_bundle_deserialize ()

gretl_bundle *
gretl_bundle_deserialize (void *p1,
                          void *p2,
                          int *err);

gretl_bundle_write_to_file ()

int
gretl_bundle_write_to_file (gretl_bundle *b,
                            const char *fname,
                            int to_dotdir);

gretl_bundle_write_to_buffer ()

char *
gretl_bundle_write_to_buffer (gretl_bundle *b,
                              int *bytes,
                              int *err);

gretl_bundle_read_from_file ()

gretl_bundle *
gretl_bundle_read_from_file (const char *fname,
                             int from_dotdir,
                             int *err);

gretl_bundle_read_from_buffer ()

gretl_bundle *
gretl_bundle_read_from_buffer (const char *buf,
                               int len,
                               int *err);

get_sysinfo_bundle ()

gretl_bundle *
get_sysinfo_bundle (int *err);

sysinfo_bundle_get_data ()

void *
sysinfo_bundle_get_data (const char *key,
                         GretlType *type,
                         int *err);

bundle_from_model ()

gretl_bundle *
bundle_from_model (MODEL *pmod,
                   DATASET *dset,
                   int *err);

kalman_bundle_new ()

gretl_bundle *
kalman_bundle_new (gretl_matrix *M[],
                   int copy[],
                   int nmat,
                   int *err);

gretl_bundle_cleanup ()

void
gretl_bundle_cleanup (void);

Types and Values

BUNDLE_PRINT

#define BUNDLE_PRINT "bundle-print"

BUNDLE_PLOT

#define BUNDLE_PLOT  "bundle-plot"

BUNDLE_TEST

#define BUNDLE_TEST  "bundle-test"

BUNDLE_FCAST

#define BUNDLE_FCAST "bundle-fcast"

BUNDLE_EXTRA

#define BUNDLE_EXTRA "bundle-extra"

GUI_MAIN

#define GUI_MAIN     "gui-main"

GUI_PRECHECK

#define GUI_PRECHECK "gui-precheck"

LIST_MAKER

#define LIST_MAKER   "list-maker"

enum BundleType

Members

BUNDLE_PLAIN

   

BUNDLE_KALMAN

   

gretl_bundle

typedef struct gretl_bundle_ gretl_bundle;

An opaque type; use the relevant accessor functions.


bundled_item

typedef struct bundled_item_ bundled_item;

An item of data within a gretl_bundle. This is an opaque type; use the relevant accessor functions.