SItem

A class for containing linguistic items (arbitrary objects). Items are nodes in a relation which is again linked to an utterance. Items contain a key-value (string/SObject) set of features. An item can have a list of daughter items as well. Items can also be shared between relations.

Definitions

speect object SItem

The SItem structure.

Items are nodes in a relation which is again linked to an utterance. Items contain a key-value (string/object) set of features. An Item can have a list of daughter items as well. Items can be shared between relations.

SItem Structure

speect class SItemClass

The SItemClass structure.

SItemClass Structure

Macros

macro S_ITEM(SELF)

Return the given SItem child class object as a SItem object.

Parameters:

• SELF –

  The given object.

Return:

Given object as SItem* type.

Note:

This casting is not safety checked.

Functions

Initialization

void SItemInit(SItem **self, const SRelation *rel, const SItem *toShare, s_erc *error)

Initialize a newly created item.

Set it’s relation and the content it must share with another item. If the given shared item is NULL, a new content is created.

Parameters:

• self –

  The newly created item to initialize.

• rel –

  The relation of the new item.

• toShare –

  Item with which to share content. If NULL then a new content is created.

• error –

  Error code.

Note:

If this function fails the item will be deleted and the self pointer will be set to NULL.

Mostly for internal use, see SItemAppend, SItemPrepend, SItemAddDaughter, SRelationAppend and SRelationPrepend for the creation of items.

As/In Relation

SItem *SItemAs(const SItem *self, const char *relation, s_erc *error)

Find the item in the given relation that has the same shared content as the given item.

Parameters:

• self –

  The given item.

• relation –

  The relation name.

• error –

  Error code.

Return:

The given item as it is in the named relation.

s_bool SItemIn(const SItem *self, const char *relation, s_erc *error)

Query if the given item is in the named relation.

Parameters:

• self –

  The given item.

• relation –

  The relation.

• error –

  Error code.

Return:

TRUE if item is in relation else FALSE.

List Traversal

SItem *SItemNext(const SItem *self, s_erc *error)

Get the item next to the given one in the current relation.

Parameters:

• self –

  The given item.

• error –

  Error code.

Return:

Pointer to the next item.

SItem *SItemPrev(const SItem *self, s_erc *error)

Get the item previous to the given one in the current relation.

Parameters:

• self –

  The given item.

• error –

  Error code.

Return:

Pointer to the prev item.

SItem *SItemAppend(SItem *self, const SItem *toShare, s_erc *error)

Create a new item and append it after the given item self.

The new item will share it’s content with the given item toShare.

Parameters:

• self –

  The given item.

• toShare –

  The item with which the newly created item will share it’s content. If NULL then a new content will be created for the appended item.

• error –

  Error code.

Return:

Pointer to appended item.

SItem *SItemPrepend(SItem *self, const SItem *toShare, s_erc *error)

Create a new item and prepend it before the given item self.

The new item will share it’s content with the given item toShare.

Parameters:

• self –

  The given item.

• toShare –

  The item with which the newly created item will share it’s content. If NULL then a new content will be created for the prepended item.

• error –

  Error code.

Return:

Pointer to prepended item.

Tree Traversal

SItem *SItemParent(const SItem *self, s_erc *error)

Returns the parent item of the given item.

Parameters:

• self –

  The given item.

• error –

  Error code.

Return:

Pointer to the parent item of the given item.

SItem *SItemDaughter(const SItem *self, s_erc *error)

Retrieve the first daughter item of the given item.

Parameters:

• self –

  The given item.

• error –

  Error code.

Return:

Pointer to the first daughter item of the given item.

SItem *SItemNthDaughter(const SItem *self, uint32 n, s_erc *error)

Retrieve the nth daughter item of the given item.

Parameters:

• self –

  The given item.

• n –

  The index of the daughter to return.

Parameters:

• error –

  Error code.

Note:

Indexing starts at 0.

Return:

Pointer to the nth daughter item of the given item.

SItem *SItemLastDaughter(const SItem *self, s_erc *error)

Retrieve the last daughter item of the given item.

Parameters:

• self –

  The given item.

• error –

  Error code.

Return:

Pointer to the last daughter item of the given item.

SItem *SItemAddDaughter(SItem *self, const SItem *toShare, s_erc *error)

Create a new item and add it as a daughter of the given item self.

The new item will share it’s content with the given item toShare. The new item will be appended to the last daughter of the given item.

Parameters:

• self –

  The given item.

• toShare –

  The item with which the newly created item will share it’s content. If NULL then a new content will be created for the daughter item.

• error –

  Error code.

Return:

Pointer to newly added daughter item.

Feature Functions

const char *SItemGetName(const SItem *self, s_erc *error)

Get the given item’s name.

Parameters:

• self –

  The given item.

• error –

  Error code.

Return:

Pointer to the given item’s name.

void SItemSetName(SItem *self, const char *name, s_erc *error)

Set the given item’s name.

Parameters:

• self –

  The given item.

• name –

  The name of the item.

• error –

  Error code.

s_bool SItemFeatureIsPresent(const SItem *self, const char *name, s_erc *error)

Query if named feature is present in the given item.

Parameters:

• self –

  The given item.

• name –

  The feature name.

• error –

  Error code.

Return:

TRUE if present or FALSE if not.

void SItemDelFeature(SItem *self, const char *name, s_erc *error)

Delete the named feature from the given item.

Parameters:

• self –

  The given item.

• name –

  The feature name.

• error –

  Error code.

SList *SItemFeatKeys(const SItem *self, s_erc *error)

Get the keys of the features of the given item.

Parameters:

• self –

  The given item.

• error –

  Error code.

Return:

Pointer to a SList containing the keys of the features of the item. The list objects (keys) are string objects and are accessed with SObjectGetString.

Note:

Caller is responsible for the memory of the returned SList object.

Get key-value feature pairs

const SObject *SItemGetObject(const SItem *self, const char *name, s_erc *error)

Get the SObject of the named feature of the given item.

Parameters:

• self –

  The given item.

• name –

  The feature name.

• error –

  Error code.

Return:

Pointer to the SObject object.

Note:

If feature does not exist an S_ARGERROR will be raised, use SItemFeatureIsPresent to test if feature is present.

sint32 SItemGetInt(const SItem *self, const char *name, s_erc *error)

Get the integer value of the named feature of the given item.

Parameters:

• self –

  The given item.

• name –

  The feature name.

• error –

  Error code.

Return:

Integer value of named feature.

Note:

If feature does not exist an S_ARGERROR will be raised, use SItemFeatureIsPresent to test if feature is present.

float SItemGetFloat(const SItem *self, const char *name, s_erc *error)

Get the float value of the named feature of the given item.

Parameters:

• self –

  The given item.

• name –

  The feature name.

• error –

  Error code.

Return:

Float value of named feature.

Note:

If feature does not exist an S_ARGERROR will be raised, use SItemFeatureIsPresent to test if feature is present.

const char *SItemGetString(const SItem *self, const char *name, s_erc *error)

Get the string value of the named feature of the given item.

Parameters:

• self –

  The given item.

• name –

  The feature name.

• error –

  Error code.

Return:

Pointer to the string.

Note:

If feature does not exist an S_ARGERROR will be raised, use SItemFeatureIsPresent to test if feature is present.

Set key-value feature pairs

void SItemSetObject(SItem *self, const char *name, const SObject *object, s_erc *error)

Set the named feature to the given SObject object of the given item.

Parameters:

• self –

  The given item.

• name –

  The feature name.

• object –

  The SObject object.

• error –

  Error code.

void SItemSetInt(SItem *self, const char *name, sint32 i, s_erc *error)

Set the named feature to the given integer value.

Parameters:

• self –

  The given item.

• name –

  The feature name.

• i –

  The integer value.

• error –

  Error code.

void SItemSetFloat(SItem *self, const char *name, float f, s_erc *error)

Set the named feature to the given float value.

Parameters:

• self –

  The given item.

• name –

  The feature name.

• f –

  The float value.

• error –

  Error code.

void SItemSetString(SItem *self, const char *name, const char *string, s_erc *error)

Set the named feature to the given string value.

Parameters:

• self –

  The given item.

• name –

  The feature name

• string –

  The string value.

• error –

  Error code.

Path Features

Extract items, item features and item functions by navigating given paths on the HRG structure (see HRG Path topic). Paths are strings that are composed of period (”.”) separated tokens describing the path of the requested item/feature, relative to a given item. The possible tokens are:

Token	Meaning
p	previous item
n	next item
daughter	first daughter item
daughtern	last daughter item
parent	parent item
R:relname	item as it is in the given relation relname

const SItem *SItemPathToItem(const SItem *item, const char *path, s_erc *error)

Extract an item, from the given path, relative to the given item.

Parameters:

• item –

  The given path is relative to this item.

• path –

  The path to the desired item, relative to the given item.

• error –

  Error code.

Return:

The item from the path, relative to the given item.

const SObject *SItemPathToFeature(const SItem *item, const char *path, s_erc *error)

Extract an item feature, from the given path, relative to the given item.

Parameters:

• item –

  The given path is relative to this item.

• path –

  The path to the desired item feature, relative to the given item.

• error –

  Error code.

Return:

The item feature from the path, relative to the given item.

SObject *SItemPathToFeatProc(const SItem *item, const char *path, s_erc *error)

Execute the given feature processor , on the item from the given path, relative to the given item.

The name of the feature processor is the last element of the path.

Parameters:

• item –

  The given path is relative to this item.

• path –

  The path to the desired item, relative to the given item, with the last element being the feature processor.

• error –

  Error code.

Return:

The result of the feature processor executed on the item from the path, relative to the given item.

SObject *SItemPath(const SItem *item, const char *path, s_erc *error)

Follow the given path, relative to the given item, and return the object at the path.

The object may be another item, a feature, or a feature that has been calculated by a feature processor . This function can be used as a replacement for SItemPathToItem, SItemPathToFeature or SItemPathToFeatProc.

Parameters:

• item –

  The given path is relative to this item.

• path –

  The path to the desired item, feature, or feature processor, relative to the given item.

• error –

  Error code.

Return:

The object at the end of the path, which may be another item, a item feature, or a feature that has been calculated by a feature processor.

Note:

The returned object must be deleted by the caller with a call to S_DELETE. It is safe to do this call, regardless of whether the returned object was an item or a item feature.

If a feature processor and an item feature has the same name then this function will not work.

Miscellaneous

const SRelation *SItemRelation(const SItem *self, s_erc *error)

Get the relation of the given item.

Parameters:

• self –

  The given item.

• error –

  Error code.

Return:

Pointer to the given item’s relation.

const SUtterance *SItemUtterance(const SItem *self, s_erc *error)

Get the utterance of the given item.

Parameters:

• self –

  The given item.

• error –

  Error code.

Return:

Pointer to the given item’s utterance.

const SVoice *SItemVoice(const SItem *self, s_erc *error)

Get the voice of the given item.

Parameters:

• self –

  The given item.

• error –

  Error code.

Return:

Pointer to the given item’s voice.

s_bool SItemEqual(const SItem *a, const SItem *b, s_erc *error)

Query if the two given items are equal.

Equal meaning if they share the same contents.

Parameters:

• a –

  The item to test.

• b –

  The item to test against.

• error –

  Error code.

Return:

TRUE if they are equal, otherwise FALSE.