---

Sparse matrices

Operations for sparse matrices. More...

Defines
#define	SMAT_TABLE_INIT(flags, resize, extra)
	Sparse matrix table static initializer. More...
#define	st_verify(table)
	Sparse matrix table verification macro. More...
#define	st_flags(table)
	Sparse matrix table flags. More...
#define	st_frozen(table)
	Determine if a sparse matrix is frozen. More...
#define	st_modulus(table)
	Sparse matrix table modulus. More...
#define	st_count(table)
	Sparse matrix table count. More...
#define	st_extra(table)
	Extra pointer data in a sparse matrix table. More...
#define	st_size(table)
	Sparse matrix table memory size. More...
#define	SMAT_HEAD_INIT(elem, object)
	Sparse matrix list head static initializer. More...
#define	sh_verify(head)
	Sparse matrix list head verification macro. More...
#define	sh_elem(head)
	Sparse matrix list head element macro. More...
#define	sh_table(head)
	Sparse matrix list head table pointer. More...
#define	sh_frozen(head)
	Determine if a sparse matrix is frozen. More...
#define	sh_count(head)
	Sparse matrix list count. More...
#define	sh_first(head)
	First element in sparse matrix list. More...
#define	sh_last(head)
	Last element in sparse matrix list. More...
#define	sh_object(head)
	Object represented by a sparse matrix list head. More...
#define	sh_size(head)
	Sparse matrix list memory size. More...
#define	se_verify(entry)
	Sparse matrix entry verification macro. More...
#define	se_table(entry)
	Sparse matrix entry table. More...
#define	_se_link(entry)
	Sparse matrix entry linked list element. More...
#define	se_flags(entry)
	Sparse matrix entry flags. More...
#define	se_hash(entry)
	Sparse matrix table entry hash value. More...
#define	se_next(entry, n)
	Next element in sparse matrix list. More...
#define	se_prev(entry, n)
	Previous element in sparse matrix list. More...
#define	se_lflags(entry, n)
	Flags associated with an entry in a sparse matrix list. More...
#define	se_object(entry, n)
	Object associated with an entry in a sparse matrix list. More...
Typedefs
typedef struct _smat_table_s	smat_table_t
	Sparse matrix table. More...
typedef struct _smat_head_s	smat_head_t
	Sparse matrix list head. More...
typedef struct _smat_entry_s	smat_entry_t
	Sparse matrix entry. More...
typedef unsigned long (*	smat_resize_t )(smat_table_t *, unsigned long)
	Sparse matrix table resize callback. More...
typedef unsigned long (*	smat_iter_t )(smat_table_t *, smat_entry_t *, void *)
	Sparse matrix iteration callback. More...
typedef unsigned long (*	smat_comp_t )(db_key_t *, smat_entry_t *)
	Sparse matrix comparison callback. More...
typedef enum _smat_loc_e	smat_loc_t
	Sparse matrix location. More...
Enumerations
enum	_smat_loc_e { SMAT_LOC_FIRST, SMAT_LOC_SECOND }
	Sparse matrix location. More...
Functions
unsigned long	smat_cleanup (void)
	Clean up the smat free list. More...
unsigned long	smat_freemem (void)
	Report how much memory is used by the free list. More...
unsigned long	st_init (smat_table_t *table, unsigned long flags, smat_resize_t resize, void *extra, unsigned long init_mod)
unsigned long	st_add (smat_table_t *table, smat_entry_t **entry_p, smat_head_t *head1, link_loc_t loc1, smat_entry_t *ent1, smat_head_t *head2, link_loc_t loc2, smat_entry_t *ent2)
	Add an entry to a sparse matrix. More...
unsigned long	st_remove (smat_table_t *table, smat_entry_t *entry)
	Remove an entry from a sparse matrix. More...
unsigned long	st_find (smat_table_t *table, smat_entry_t **entry_p, smat_head_t *head1, smat_head_t *head2)
	Find an entry in a sparse matrix. More...
unsigned long	st_iter (smat_table_t *table, smat_iter_t iter_func, void *extra)
	Iterate over each entry in a sparse matrix. More...
unsigned long	st_flush (smat_table_t *table, smat_iter_t flush_func, void *extra)
	Flush a sparse matrix. More...
unsigned long	st_resize (smat_table_t *table, unsigned long new_size)
	Resize a sparse matrix table. More...
unsigned long	st_free (smat_table_t *table)
	Free memory used by an empty sparse matrix table. More...
unsigned long	sh_init (smat_head_t *head, smat_loc_t elem, void *object)
	Dynamically initialize a sparse matrix row or column head. More...
unsigned long	sh_move (smat_head_t *head, smat_entry_t *elem, link_loc_t loc, smat_entry_t *elem2)
	Move an entry within a row or column list. More...
unsigned long	sh_find (smat_head_t *head, smat_entry_t **elem_p, smat_comp_t comp_func, smat_entry_t *start, db_key_t *key)
	Find an entry in a row or column of a sparse matrix. More...
unsigned long	sh_iter (smat_head_t *head, smat_iter_t iter_func, void *extra)
	Iterate over each entry in a row or column of a sparse matrix. More...

---

Detailed Description

Sparse matrices are advanced data structures used to represent associations. For instance, a manager may have several employees, but several of those employees may report to more than one manager. (Yes, this is a contrived example, so sue me.) The simplest way to represent such assocations is with a matrix, or a two-dimensional array. However, such an implementation cannot easily be extended dynamically--imagine if a manager retires and two more are hired, for instance. It would also use an enormous amount of memory, as most employees would only report to one or two managers.

A sparse matrix solves this problem by only allocating memory for the cells in the full matrix which are actually used. That is, no memory is allocated to represent Alice reporting to Bob unless Alice actually does report to Bob. This is a simple concept, but fairly difficult to implement efficiently--how do you tell if Alice reports to Bob? The solution utilized by this library is to combine the strengths of linked lists and hash tables. Each cell is in two linked lists, rooted at the rows and columns of the matrix, but a hash table is used when attempting to look up a given cell. If the cell is allocated, then there will be an entry in the hash table, and finding the given cell is as fast as a hash table look-up.

Because sparse matrices are so complicated, there are three structures and a variety of operations used. Two of the structures, smat_table_t and smat_head_t, are caller-allocated. However, the third structure, smat_entry_t, must be allocated by the library. To avoid too much overhead from malloc(), a free list is used. The free list may be managed with the smat_cleanup() and smat_freemem() calls.

The smat_table_t contains the hash table. Only one of these need be allocated per type of association--for instance, in the above example, only one smat_table_t needs to be allocated to represent the manager-employee relationship.

The smat_head_t contains the linked list. There are actually two kinds of these structures--one is SMAT_LOC_FIRST, which could be regarded as a ``row,'' and the other is SMAT_LOC_SECOND, which could be regarded as a ``column.'' Which one is used for which type of data is irrelevant, as long as consistency is maintained. For the above example, a smat_head_t for a manager may be SMAT_LOC_FIRST, and one for an employee must then be SMAT_LOC_SECOND. (These values are set when initializing the smat_head_t structure.)

An association may be created with the st_add() function, which allows an arbitrary ordering in the associated linked lists by the same mechanism as for the linked list component of the library. An association may be removed with st_remove(), or looked up with st_find(). If iteration over all associations is desired, use the st_iter() function. Removing all associations from a table may be performed with st_flush(), which optionally calls a user-defined clean-up function. The associated hash table may be resized with st_resize(), and the bucket table may be released with st_free().

An association may also be reordered within the linked lists using the sh_move() function. If a particular entry is desired, use the sh_find() function with a user-defined comparison function to locate it. Iteration may be performed with the sh_iter() function, and all entries in a given linked list may be removed with the sh_flush() function, which again may optionally call a user-defined clean-up function.

---

Define Documentation

#define SMAT_HEAD_INIT( elem, object )

This macro statically initializes a smat_head_t. Parameters: elem   One of SMAT_LOC_FIRST or SMAT_LOC_SECOND specifing whether the object is a member of the set of rows or columns. object   A pointer to void representing the object associated with the list head.

#define SMAT_TABLE_INIT( flags, resize, extra )

This macro statically initializes a smat_table_t. Parameters: flags   A bit-wise OR of HASH_FLAG_AUTOGROW and HASH_FLAG_AUTOSHRINK. If neither behavior is desired, use 0. resize   A smat_resize_t function pointer for determining whether resizing is permitted and/or for notification of the resize. extra   Extra pointer data that should be associated with the sparse matrix.

#define _se_link( entry )

For internal use only.

#define se_flags( entry )

This macro retrieves a set of user-defined flags associated with the entry. It may be used as an lvalue to set those flags. Parameters: entry   A pointer to a smat_entry_t. Returns: An unsigned long containing the flags associated with the entry.

#define se_hash( entry )

This macro retrieves the hash value of the given sparse matrix entry. If the sparse matrix hash been resized, this value may not be the same as a previous value. Parameters: entry   A pointer to a smat_entry_t. Returns: An unsigned long containing the hash code for the entry.

#define se_lflags( entry, n )

This macro retrieves a set of user-defined flags associated with the entry in a sparse matrix list. It may be used as an lvalue to set those flags. Parameters: entry   A pointer to smat_entry_t. n   One of SMAT_LOC_FIRST or SMAT_LOC_SECOND to specify which list thread is desired. Returns: An unsigned long containing the flags associated with the entry.

#define se_next( entry, n )

This macro retrieves a pointer to the link_elem_t for the next element in the sparse matrix list. Warning: This macro may evaluate the entry and n arguments twice. Parameters: entry   A pointer to smat_entry_t. n   One of SMAT_LOC_FIRST or SMAT_LOC_SECOND to specify which list thread is desired. Returns: A pointer to smat_entry_t.

#define se_object( entry, n )

This macro retrieves a pointer to one of the object represented by the entry. It may be used as an lvalue to change the object pointed to. Care should be taken when using this feature. Parameters: entry   A pointer to smat_entry_t. n   One of SMAT_LOC_FIRST or SMAT_LOC_SECOND to specify which list thread is desired. Returns: A pointer to void representing the object.

#define se_prev( entry, n )

This macro retrieves a pointer to the link_elem_t for the previous element in the sparse matrix list. Warning: This macro may evaluate the entry and n arguments twice. Parameters: entry   A pointer to smat_entry_t. n   One of SMAT_LOC_FIRST or SMAT_LOC_SECOND to specify which list thread is desired. Returns: A pointer to smat_entry_t.

#define se_table( entry )

This macro retrieves a pointer to the table that the sparse matrix entry is in. Parameters: entry   A pointer to a smat_entry_t. Returns: A pointer to a smat_table_t.

#define se_verify( entry )

This macro verifies that a given pointer actually does point to a sparse matrix entry. Parameters: entry   A pointer to a smat_entry_t. Returns: Boolean true if entry is a valid sparse matrix entry or false otherwise.

#define sh_count( head )

This macro retrieves the number of elements in the sparse matrix list rooted at head. Parameters: head   A pointer to smat_head_t. Returns: An unsigned long containing a count of the number of elements in the sparse matrix list.

#define sh_elem( head )

This macro retrieves the position indicator for the sparse matrix head. It will return one of SMAT_LOC_FIRST or SMAT_LOC_SECOND. Parameters: head   A pointer to smat_head_t. Returns: An smat_loc_t.

#define sh_first( head )

This macro retrieves a pointer to the smat_entry_t for the first element in the sparse matrix list. Warning: This macro may evaluate the head argument twice. Parameters: head   A pointer to smat_head_t. Returns: A pointer to smat_entry_t.

#define sh_frozen( head )

This macro returns a non-zero value if the matrix is currently frozen. The sparse matrix may be frozen if there is an iteration in progress. Parameters: head   A pointer to a smat_head_t. Returns: A zero value if the matrix is not frozen or a non-zero value if the matrix is frozen.

#define sh_last( head )

This macro retrieves a pointer to the smat_entry_t for the last element in the sparse matrix list. Warning: This macro may evaluate the head argument twice. Parameters: head   A pointer to smat_head_t. Returns: A pointer to smat_entry_t.

#define sh_object( head )

This macro retrieves a pointer to the object referenced by the sparse matrix list head. Parameters: head   A pointer to smat_head_t. Returns: A pointer to void.

#define sh_size( head )

This macro returns the physical size of the memory allocated by the library for this sparse matrix list. Note: The st_size() macro already counts the memory for each list in the table. Summing the results of sh_size() and st_size() will over-count the amount of memory actually in use. Parameters: head   A pointer to smat_head_t. Returns: A size_t.

#define sh_table( head )

If there are any elements in this sparse matrix list head, this macro will retrieve a pointer to the table in which they reside. Parameters: head   A pointer to smat_head_t. Returns: A pointer to smat_table_t.

#define sh_verify( head )

This macro verifies that a given pointer actually does point to a sparse matrix head. Parameters: head   A pointer to a smat_head_t. Returns: Boolean true if head is a valid sparse matrix head or false otherwise.

#define st_count( table )

This macro retrieves the total number of items actually in the sparse matrix table. Parameters: table   A pointer to a smat_table_t. Returns: An unsigned long containing a count of the number of items in the sparse matrix table.

#define st_extra( table )

This macro retrieves the extra pointer data associated with a particular sparse matrix table. Parameters: table   A pointer to a smat_table_t. Returns: A pointer to void.

#define st_flags( table )

This macro retrieves the flags associated with the sparse matrix table. Only HASH_FLAG_AUTOGROW and HASH_FLAG_AUTOSHRINK have any meaning to the application; all other bits are reserved for use in the library. This macro may be used as an lvalue, but care must be taken to avoid modifying the library-specific bits. Parameters: table   A pointer to a smat_table_t. Returns: An unsigned long containing the flags for the sparse matrix table.

#define st_frozen( table )

This macro returns a non-zero value if the matrix is currently frozen. The sparse matrix may be frozen if there is an iteration in progress. Parameters: table   A pointer to a smat_table_t. Returns: A zero value if the matrix is not frozen or a non-zero value if the matrix is frozen.

#define st_modulus( table )

This macro retrieves the number of buckets allocated for the sparse matrix table. An application may wish to save this value between invocations to avoid the overhead of growing the table while filling it with data. Parameters: table   A pointer to a smat_table_t. Returns: An unsigned long containing the number of buckets allocated for the sparse matrix table.

#define st_size( table )

This macro returns the physical size of the memory allocated by the library for this sparse matrix table. Note: The st_size() macro already counts the memory for each list in the table. Summing the results of sh_size() and st_size() will over-count the amount of memory actually in use. Parameters: table   A pointer to a smat_table_t. Returns: A size_t.

#define st_verify( table )

This macro verifies that a given pointer actually does point to a sparse matrix table. Parameters: table   A pointer to a smat_table_t. Returns: Boolean true if table is a valid sparse matrix table or false otherwise.

---

Typedef Documentation

typedef unsigned long(* smat_comp_t)(db_key_t *, smat_entry_t *)

This function pointer references a callback used by sh_find(). It should return 0 if the sparse matrix entry represented by the second argument matches the key passed as the first argument.

typedef struct _smat_entry_s smat_entry_t

This structure is allocated by the library and represents a single element in a sparse matrix.

typedef struct _smat_head_s smat_head_t

This structure is the head of a linked list of sparse matrix entries.

typedef unsigned long(* smat_iter_t)(smat_table_t *, smat_entry_t *, void *)

This function pointer references a callback used by st_iter(), st_flush(), sh_iter(), and sh_flush(). It should return 0 for success. A non-zero return value will terminate the operation and will become the return value of the call.

typedef enum _smat_loc_e smat_loc_t

See the documentation for the enumeration _smat_loc_e.

typedef unsigned long(* smat_resize_t)(smat_table_t *, unsigned long)

This function pointer references a callback that will be called with both the old and new sparse matrix table sizes whenever a sparse matrix's hash table table is resized. It should return non-zero only when the resize should be inhibited.

typedef struct _smat_table_s smat_table_t

This structure is the basis of all sparse matrices maintained by this library.

---

Enumeration Type Documentation

enum _smat_loc_e

This enumeration is used to specify whether an element is a row or column element. It should be referenced by the typedef smat_loc_t. Enumeration values: SMAT_LOC_FIRST   First entry (``row''). SMAT_LOC_SECOND   Second entry (``column'').

---

Function Documentation

unsigned long sh_find ( smat_head_t * head, smat_entry_t ** elem_p, smat_comp_t comp_func, smat_entry_t * start, db_key_t * key )

This function iterates through the given row or column of a sparse matrix looking for an element that matches the given key. Parameters: head   A pointer to a smat_head_t. elem_p   A pointer to a pointer to a smat_entry_t. This is a result pramater. NULL is an invalid value. comp_func   A pointer to a comparison function used to compare the key to a particular entry. See the documentation for smat_comp_t for more information. start   A pointer to a smat_entry_t describing where in the row or column to start. If NULL is passed, the beginning of the row or column will be assumed. key   A key to search for. Return values: DB_ERR_BADARGS   An argument was invalid. DB_ERR_WRONGTABLE   start is not in this row or column. DB_ERR_NOENTRY   No matching entry was found.

unsigned long sh_init ( smat_head_t * head, smat_loc_t elem, void * object )

This function dynamically initializes a sparse matrix row or column linked list head. The elem argument specifies whether the object is to be associated with a SMAT_LOC_FIRST list or a SMAT_LOC_SECOND list. Parameters: head   A pointer to a smat_head_t to be initialized. elem   Either SMAT_LOC_FIRST or SMAT_LOC_SECOND. object   A pointer to the object containing the sparse matrix row or column head. Return values: DB_ERR_BADARGS   An invalid argument was given.

unsigned long sh_iter ( smat_head_t * head, smat_iter_t iter_func, void * extra )

This function iterates over a row or column of a sparse matrix, executing the given iter_func for each entry. Parameters: head   A pointer to a smat_head_t. iter_func   A pointer to a callback function used to perform user-specified actions on an entry in a row or column of a sparse matrix. NULL is an invalid value. See the documentation for smat_iter_t for more information. extra   A void pointer that will be passed to iter_func. Return values: DB_ERR_BADARGS   An argument was invalid.

unsigned long sh_move ( smat_head_t * head, smat_entry_t * elem, link_loc_t loc, smat_entry_t * elem2 )

This function allows the specified entry to be shifted within the linked list describing the row or column. It is very similar to the ll_move() function. Parameters: head   A pointer to a smat_head_t. elem   A pointer to the smat_entry_t describing the entry to be moved. loc   A link_loc_t indicating where the entry should be moved to. elem2   A pointer to a smat_entry_t describing another entry in the list if loc is LINK_LOC_BEFORE or LINK_LOC_AFTER. Return values: DB_ERR_BADARGS   An argument was invalid. DB_ERR_BUSY   elem and elem2 are the same entry. DB_ERR_WRONGTABLE   elem or elem2 are in a different row or column. DB_ERR_UNUSED   elem or elem2 are not in any row or column.

unsigned long smat_cleanup ( void )

This function frees all smat_entry_t objects on the internal free list. It is always successful and returns 0.

unsigned long smat_freemem ( void )

This function returns the amount of memory being used by the internal free list of smat_entry_t objects. Returns: A number indicating the size, in bytes, of the memory allocated for smat_entry_t objects on the free list.

unsigned long st_add ( smat_table_t * table, smat_entry_t ** entry_p, smat_head_t * head1, link_loc_t loc1, smat_entry_t * ent1, smat_head_t * head2, link_loc_t loc2, smat_entry_t * ent2 )

This function adds an entry to a sparse matrix. The entry is referenced in three different places, thus the complex set of arguments. This function will allocate a smat_entry_t and return it through the entry_p result parameter. Parameters: table   A pointer to a smat_table_t. entry_p   A pointer to a pointer to a smat_entry_t. This is a result parameter. If NULL is passed, the addition will be performed and an appropriate error code returned. head1   A pointer to a smat_head_t representing a SMAT_LOC_FIRST sparse matrix list. loc1   A link_loc_t indicating where the entry should be added for head1. ent1   A pointer to a smat_entry_t describing another element in the list represented by head1 if loc1 is LINK_LOC_BEFORE or LINK_LOC_AFTER. head2   A pointer to a smat_head_t representing a SMAT_LOC_SECOND sparse matrix list. loc2   A link_loc_t indicating where the entry should be added for head2. ent2   A pointer to a smat_entry_t describing another element in the list represented by head2 if loc2 is LINK_LOC_BEFORE or LINK_LOC_AFTER. Return values: DB_ERR_BADARGS   An argument was invalid. DB_ERR_BUSY   One of the arguments is already in the table. DB_ERR_FROZEN   The table is currently frozen. DB_ERR_NOTABLE   The bucket table has not been allocated and automatic growth is not enabled. DB_ERR_WRONGTABLE   One of the arguments was not in the proper table or list. DB_ERR_UNUSED   One of the ent arguments is not presently in a list. DB_ERR_UNRECOVERABLE   An unrecoverable error occurred while resizing the table. ENOMEM   No memory could be allocated for the smat_entry_t structure.

unsigned long st_find ( smat_table_t * table, smat_entry_t ** entry_p, smat_head_t * head1, smat_head_t * head2 )

This function looks up the entry matching the given head1 and head2. Parameters: table   A pointer to a smat_table_t. entry_p   A pointer to a pointer to a smat_entry_t. This is a result parameter. If NULL is passed, the lookup will be performed and an appropriate error code returned. head1   A pointer to a smat_head_t initialized to SMAT_LOC_FIRST. head2   A pointer to a smat_head_t initialized to SMAT_LOC_SECOND. Return values: DB_ERR_BADARGS   An argument was invalid. DB_ERR_WRONGTABLE   One or both of head1 or head2 are not referenced in this table. DB_ERR_NOENTRY   No matching entry was found.

unsigned long st_flush ( smat_table_t * table, smat_iter_t flush_func, void * extra )

This function flushes a sparse matrix--that is, it removes each entry from the matrix. If a flush_func is specified, it will be called on the entry after it has been removed from the table, and may safely call free(). Parameters: table   A pointer to a smat_table_t. flush_func   A pointer to a callback function used to perform user-specified actions on an entry after removing it from the table. May be NULL. See the documentation for smat_iter_t for more information. extra   A void pointer that will be passed to iter_func. Return values: DB_ERR_BADARGS   An argument was invalid. DB_ERR_FROZEN   The sparse matrix is frozen.

unsigned long st_free ( smat_table_t * table )

This function releases the memory used by the bucket table of the empty hash table associated with a sparse matrix. Parameters: table   A pointer to a smat_table_t. Return values: DB_ERR_BADARGS   An invalid argument was given. DB_ERR_FROZEN   The table is frozen. DB_ERR_NOTEMPTY   The table is not empty.

unsigned long st_init ( smat_table_t * table, unsigned long flags, smat_resize_t resize, void * extra, unsigned long init_mod )

This function dynamically initializes a sparse matrix table. Parameters: table   A pointer to a smat_table_t to be initialized. flags   A bit-wise OR of HASH_FLAG_AUTOGROW and HASH_FLAG_AUTOSHRINK. If neither behavior is desired, use 0. resize   A hash_resize_t function pointer for determining whether resizing is permitted and/or for notification of the resize. extra   Extra pointer data that should be associated with the sparse matrix table. init_mod   An initial modulus for the table. This will presumably be extracted by st_modulus() in a previous invocation of the application. A 0 value is valid. Return values: DB_ERR_BADARGS   An invalid argument was given. ENOMEM   Unable to allocate memory.

unsigned long st_iter ( smat_table_t * table, smat_iter_t iter_func, void * extra )

This function iterates over every entry in a sparse matrix (in an unspecified order), executing the given iter_func on each entry. Parameters: table   A pointer to a smat_table_t. iter_func   A pointer to a callback function used to perform user-specified actions on an entry in a sparse matrix. NULL is an invalid value. See the documentation for smat_iter_t for more information. extra   A void pointer that will be passed to iter_func. Return values: DB_ERR_BADARGS   An argument was invalid. DB_ERR_FROZEN   The sparse matrix is frozen.

unsigned long st_remove ( smat_table_t * table, smat_entry_t * entry )

This function removes the given entry from the specified sparse matrix. Parameters: table   A pointer to a smat_table_t. entry   A pointer to a smat_entry_t to be removed from the table. Return values: DB_ERR_BADARGS   An invalid argument was given. DB_ERR_WRONGTABLE   Entry is not in this sparse matrix. DB_ERR_UNRECOVERABLE   An unrecoverable error occurred while removing the entry from the table.

unsigned long st_resize ( smat_table_t * table, unsigned long new_size )

This function resizes the hash table associated with a sparse matrix based on the new_size parameter. See the documentation for ht_resize() for more information. Parameters: table   A pointer to a smat_table_t. new_size   A new size value for the table. Return values: DB_ERR_BADARGS   An argument was invalid. DB_ERR_FROZEN   The table is currently frozen. DB_ERR_UNRECOVERABLE   A catastrophic error was encountered. The table is now unusable. ENOMEM   No memory could be allocated for the new bucket table.

---