CWB
Data Structures | Typedefs | Functions | Variables
variables.h File Reference
#include "../cl/corpus.h"
#include "../cl/attributes.h"

Data Structures

struct  _variable_item
 VariableItem object: an item within a variable. More...
 
struct  _variable_buf
 The Variable object: a list of strings that can be used as a variable within a query (to match all tokens whose type is identical to one of the strings on the list). More...
 

Typedefs

typedef struct _variable_item VariableItem
 VariableItem object: an item within a variable. More...
 
typedef struct _variable_buf VariableBuffer
 The Variable object: a list of strings that can be used as a variable within a query (to match all tokens whose type is identical to one of the strings on the list). More...
 
typedef struct _variable_bufVariable
 

Functions

Variable FindVariable (char *varname)
 Finds the Variable object of the given name, if it exists in VariableSpace. More...
 
int VariableItemMember (Variable v, char *item)
 Tests whether a given string exists within the variable. More...
 
int VariableAddItem (Variable v, char *item)
 Adds a string to the variable. More...
 
int VariableSubtractItem (Variable v, const char *item)
 Remove a string from a defined Variable. More...
 
int VariableDeleteItems (Variable v)
 Deletes and frees up all memory associated with the strings contained by this variable. More...
 
int DropVariable (Variable *vp)
 Deletes all the memory associated with a given variable. More...
 
Variable NewVariable (char *varname)
 Creates a new Variable (set of strings) with the specified name within the global VariableSpace. More...
 
int SetVariableValue (char *varName, char operator, char *varValues)
 Sets the value of a variable; returns true for success, false for failure. More...
 
void variables_iterator_new (void)
 Resets the global variables iterator to the beginning of the global VariableSpace array. More...
 
Variable variables_iterator_next (void)
 Gets the next Variable object from the variables iterator. More...
 
int VerifyVariable (Variable v, Corpus *corpus, Attribute *attribute)
 Verify a variable for use with a given p-attribute of a given corpus. More...
 
int * GetVariableItems (Variable v, Corpus *corpus, Attribute *attribute, int *nr_items)
 Get lexicon IDs of variable's strings in corpus.attribute lexicon. More...
 
char ** GetVariableStrings (Variable v, int *nr_items)
 Returns an array of pointers to a variable's strings. More...
 

Variables

int nr_variables
 Number of variables in VariableArray (exported) More...
 
VariableVariableSpace
 Global array of Variables (exported) More...
 

Typedef Documentation

typedef struct _variable_buf * Variable
typedef struct _variable_buf VariableBuffer

The Variable object: a list of strings that can be used as a variable within a query (to match all tokens whose type is identical to one of the strings on the list).

(Plus also VariableBuffer: the former is a pointer to the latter.)

typedef struct _variable_item VariableItem

VariableItem object: an item within a variable.

Function Documentation

int DropVariable ( Variable vp)

Deletes all the memory associated with a given variable.

If the Variable is in VariableSpace, that slot in VariableSpace is emptied out.

Parameters
vpNote that this function takes a POINTER to a Variable object, not a Variable itself (even though Variable IS a pointer type)... allowing the object to be set to NULL once emptied out.
Returns
Always 1.

References cl_free, _variable_buf::my_attribute, _variable_buf::my_corpus, _variable_buf::my_name, nr_variables, and VariableDeleteItems().

Variable FindVariable ( char *  varname)

Finds the Variable object of the given name, if it exists in VariableSpace.

Parameters
varnameThe name of the variable required.
Returns
The Variable requested, or NULL if no Variable by that name could be found.

References nr_variables.

Referenced by do_AddSubVariables(), do_flagged_re_variable(), do_printVariableSize(), do_PrintVariableValue(), do_SetVariableValue(), SetVariableValue(), and Varref2IDList().

int* GetVariableItems ( Variable  v,
Corpus corpus,
Attribute attribute,
int *  nr_items 
)

Get lexicon IDs of variable's strings in corpus.attribute lexicon.

Parameters
vThe Variable object.
corpusThe corpus we are working with.
attributeThe attribute against which to verify the Variable's items
nr_itemsThis will be set to the number of integers in the returned array.
Returns
Pointer to block of integers based on valid items from the variable; NULL if there were no valid items (i.e. items found in the attribute's lexicon).

References cl_malloc(), _variable_item::free, intcompare(), _variable_buf::items, _variable_item::ival, _variable_buf::nr_items, _variable_buf::nr_valid_items, and VerifyVariable().

Referenced by Varref2IDList().

char** GetVariableStrings ( Variable  v,
int *  nr_items 
)

Returns an array of pointers to a variable's strings.

Return value is NULL if there were no strings stored in the variable. The number of strings that were found is inserted into nr_items.

The array that is returned must be freed by the caller.

Parameters
vThe Variable whose strings you want.
nr_itemsThe number of strings found will be put here.
Returns
Table of pointers to the Variable's strings.

References cl_malloc(), _variable_item::free, _variable_buf::items, _variable_buf::nr_items, and _variable_item::sval.

Referenced by do_AddSubVariables(), and do_flagged_re_variable().

Variable NewVariable ( char *  varname)

Creates a new Variable (set of strings) with the specified name within the global VariableSpace.

Returns NULL only if the variable string name was NULL.

References cl_malloc(), cl_realloc(), cl_strdup(), _variable_buf::items, _variable_buf::my_attribute, _variable_buf::my_corpus, _variable_buf::my_name, _variable_buf::nr_items, nr_variables, _variable_buf::valid, and VARIABLE_REALLOC.

Referenced by do_SetVariableValue(), and SetVariableValue().

int SetVariableValue ( char *  varName,
char  operator,
char *  varValues 
)
int VariableAddItem ( Variable  v,
char *  item 
)
int VariableDeleteItems ( Variable  v)

Deletes and frees up all memory associated with the strings contained by this variable.

The variable continues to exist, but is now empty.

References cl_free, _variable_buf::items, _variable_buf::nr_invalid_items, _variable_buf::nr_items, _variable_buf::nr_valid_items, _variable_item::sval, and _variable_buf::valid.

Referenced by DropVariable(), and SetVariableValue().

int VariableItemMember ( Variable  v,
char *  item 
)

Tests whether a given string exists within the variable.

Returns
Boolean: true if the variable contains the string.

References _variable_item::free, _variable_buf::items, _variable_buf::nr_items, and _variable_item::sval.

Referenced by VariableAddItem().

void variables_iterator_new ( void  )

Resets the global variables iterator to the beginning of the global VariableSpace array.

References variables_iterator_idx.

Referenced by do_PrintAllVariables().

Variable variables_iterator_next ( void  )

Gets the next Variable object from the variables iterator.

Returns NULL if the iterator has reached the end of the global VariableSpace array.

See also
VariableSpace
Returns
The next Variable object from the iterator.

References nr_variables, and variables_iterator_idx.

Referenced by do_PrintAllVariables().

int VariableSubtractItem ( Variable  v,
const char *  item 
)

Remove a string from a defined Variable.

Identification of the string to remove is by bytewise identity.

Parameters
vThe variable.
itemThe string to take out of the variable.
Returns
Always 1

References cl_free, _variable_item::free, _variable_buf::items, _variable_item::ival, _variable_buf::nr_items, _variable_item::sval, and _variable_buf::valid.

Referenced by do_AddSubVariables(), and SetVariableValue().

int VerifyVariable ( Variable  v,
Corpus corpus,
Attribute attribute 
)

Verify a variable for use with a given p-attribute of a given corpus.

This associates the variable with the supplied corpus/attribute, plus checks the variable's strings against the relevant attribute lexicon.

Returns
Boolean: true for all OK, false if something went wrong (problem with the arguments, or if none of the variable's strings match the lexicon). Same as the value of the Variable's "valid" flag after this function has run.

References _Attribute::any, ATT_POS, TCorpus::charset, cl_free, cl_str2id(), cl_strdup(), cl_string_canonical(), cl_string_validate_encoding(), cqpmessage(), Error, _variable_item::free, _variable_buf::items, _variable_item::ival, _variable_buf::my_attribute, _variable_buf::my_corpus, _variable_buf::my_name, _variable_buf::nr_invalid_items, _variable_buf::nr_items, _variable_buf::nr_valid_items, TCorpus::registry_name, REQUIRE_NFC, _variable_item::sval, utf8, and _variable_buf::valid.

Referenced by GetVariableItems().

Variable Documentation

int nr_variables

Number of variables in VariableArray (exported)

Referenced by DropVariable(), FindVariable(), NewVariable(), and variables_iterator_next().

Variable* VariableSpace

Global array of Variables (exported)