t8  1.2.0
t8code is a C library to manage a forest of adaptive space-trees of general element classes in parallel.
Data Structures | Functions
t8_containers.h File Reference

We define the t8_element_array that stores elements of a given eclass scheme. More...

#include <t8.h>
#include <t8_element.h>

Go to the source code of this file.

Data Structures

struct  t8_element_array_t
 The t8_element_array_t is an array to store t8_element_t * of a given eclass_scheme implementation. More...
 

Functions

t8_element_array_t * t8_element_array_new (t8_eclass_scheme_c *scheme)
 Creates a new array structure with 0 elements. More...
 
t8_element_array_t * t8_element_array_new_count (t8_eclass_scheme_c *scheme, size_t num_elements)
 Creates a new array structure with a given length (number of elements) and calls t8_element_new for those elements. More...
 
void t8_element_array_init (t8_element_array_t *element_array, t8_eclass_scheme_c *scheme)
 Initializes an already allocated (or static) array structure. More...
 
void t8_element_array_init_size (t8_element_array_t *element_array, t8_eclass_scheme_c *scheme, size_t num_elements)
 Initializes an already allocated (or static) array structure and allocates a given number of elements and initializes them with t8_element_init. More...
 
void t8_element_array_init_view (t8_element_array_t *view, t8_element_array_t *array, size_t offset, size_t length)
 Initializes an already allocated (or static) view from existing t8_element_array. More...
 
void t8_element_array_init_data (t8_element_array_t *view, t8_element_t *base, t8_eclass_scheme_c *scheme, size_t elem_count)
 Initializes an already allocated (or static) view from given plain C data (array of t8_element_t). More...
 
void t8_element_array_init_copy (t8_element_array_t *element_array, t8_eclass_scheme_c *scheme, t8_element_t *data, size_t num_elements)
 Initializes an already allocated (or static) array structure and copy an existing array of t8_element_t into it. More...
 
void t8_element_array_resize (t8_element_array_t *element_array, size_t new_count)
 Change the number of elements stored in an element array. More...
 
void t8_element_array_copy (t8_element_array_t *dest, t8_element_array_t *src)
 Copy the contents of an array into another. More...
 
t8_element_t * t8_element_array_push (t8_element_array_t *element_array)
 Enlarge an array by one element. More...
 
t8_element_t * t8_element_array_push_count (t8_element_array_t *element_array, size_t count)
 Enlarge an array by a number of elements. More...
 
t8_element_t * t8_element_array_index_locidx (t8_element_array_t *element_array, t8_locidx_t index)
 Return a given element in an array. More...
 
t8_element_t * t8_element_array_index_int (t8_element_array_t *element_array, int index)
 Return a given element in an array. More...
 
t8_eclass_scheme_c * t8_element_array_get_scheme (t8_element_array_t *element_array)
 Return the eclass scheme associated to a t8_element_array. More...
 
size_t t8_element_array_get_count (t8_element_array_t *element_array)
 Return the number of elements stored in a t8_element_array_t. More...
 
size_t t8_element_array_get_size (t8_element_array_t *element_array)
 Return the data size of elements stored in a t8_element_array_t. More...
 
t8_element_t * t8_element_array_get_data (t8_element_array_t *element_array)
 Return a pointer to the real data array stored in a t8_element_array. More...
 
sc_array_t * t8_element_array_get_array (t8_element_array_t *element_array)
 Return a pointer to the sc_array stored in a t8_element_array. More...
 
void t8_element_array_reset (t8_element_array_t *element_array)
 Sets the array count to zero and frees all elements. More...
 
void t8_element_array_truncate (t8_element_array_t *element_array)
 Sets the array count to zero, but does not free elements. More...
 

Detailed Description

We define the t8_element_array that stores elements of a given eclass scheme.

Function Documentation

◆ t8_element_array_copy()

void t8_element_array_copy ( t8_element_array_t *  dest,
t8_element_array_t *  src 
)

Copy the contents of an array into another.

Both arrays must have the same eclass_scheme.

Parameters
[in]destArray will be resized and get new data.
[in]srcArray used as source of new data, will not be changed.

◆ t8_element_array_get_array()

sc_array_t* t8_element_array_get_array ( t8_element_array_t *  element_array)

Return a pointer to the sc_array stored in a t8_element_array.

Parameters
[in]element_arrayArray structure.
Returns
A pointer to the sc_array storing the data.

◆ t8_element_array_get_count()

size_t t8_element_array_get_count ( t8_element_array_t *  element_array)

Return the number of elements stored in a t8_element_array_t.

Parameters
[in]element_arrayArray structure.
Returns
The number of elements stored in element_array.

◆ t8_element_array_get_data()

t8_element_t* t8_element_array_get_data ( t8_element_array_t *  element_array)

Return a pointer to the real data array stored in a t8_element_array.

Parameters
[in]element_arrayArray structure.
Returns
A pointer to the stored data. If the number of stored elements is 0, then NULL is returned.

◆ t8_element_array_get_scheme()

t8_eclass_scheme_c* t8_element_array_get_scheme ( t8_element_array_t *  element_array)

Return the eclass scheme associated to a t8_element_array.

Parameters
[in]element_arrayArray of elements.
Returns
The eclass scheme stored at element_array.

◆ t8_element_array_get_size()

size_t t8_element_array_get_size ( t8_element_array_t *  element_array)

Return the data size of elements stored in a t8_element_array_t.

Parameters
[in]element_arrayArray structure.
Returns
The size (in bytes) of a single element in element_array.

◆ t8_element_array_index_int()

t8_element_t* t8_element_array_index_int ( t8_element_array_t *  element_array,
int  index 
)

Return a given element in an array.

Parameters
[in]element_arrayArray of elements.
[in]indexThe index of an element whithin the array.
Returns
A pointer to the element stored at position index in element_array.

◆ t8_element_array_index_locidx()

t8_element_t* t8_element_array_index_locidx ( t8_element_array_t *  element_array,
t8_locidx_t  index 
)

Return a given element in an array.

Parameters
[in]element_arrayArray of elements.
[in]indexThe index of an element whithin the array.
Returns
A pointer to the element stored at position index in element_array.

◆ t8_element_array_init()

void t8_element_array_init ( t8_element_array_t *  element_array,
t8_eclass_scheme_c *  scheme 
)

Initializes an already allocated (or static) array structure.

Parameters
[in,out]element_arrayArray structure to be initialized.
[in]schemeThe eclass scheme of which elements should be stored.

◆ t8_element_array_init_copy()

void t8_element_array_init_copy ( t8_element_array_t *  element_array,
t8_eclass_scheme_c *  scheme,
t8_element_t *  data,
size_t  num_elements 
)

Initializes an already allocated (or static) array structure and copy an existing array of t8_element_t into it.

Parameters
[in,out]element_arrayArray structure to be initialized.
[in]schemeThe eclass scheme of which elements should be stored.
[in]dataAn array of t8_element_t which will be copied into element_array. The elements in data must belong to scheme and must be properly initialized with either t8_element_new or t8_element_init.
[in]num_elementsNumber of elements in data to be copied.

◆ t8_element_array_init_data()

void t8_element_array_init_data ( t8_element_array_t *  view,
t8_element_t *  base,
t8_eclass_scheme_c *  scheme,
size_t  elem_count 
)

Initializes an already allocated (or static) view from given plain C data (array of t8_element_t).

The array view returned does not require t8_element_array_reset (doesn't hurt though).

Parameters
[in,out]viewArray structure to be initialized.
[in]baseThe data must not be moved while view is alive. Must be an array of t8_element_t corresponding to scheme.
[in]schemeThe eclass scheme of the elements stored in base.
[in]elem_countThe length of the view in element units. The view cannot be resized to exceed this length. It is not necessary to call t8_element_array_reset later.

◆ t8_element_array_init_size()

void t8_element_array_init_size ( t8_element_array_t *  element_array,
t8_eclass_scheme_c *  scheme,
size_t  num_elements 
)

Initializes an already allocated (or static) array structure and allocates a given number of elements and initializes them with t8_element_init.

Parameters
[in,out]element_arrayArray structure to be initialized.
[in]schemeThe eclass scheme of which elements should be stored.
[in]num_elementsNumber of initial array elements.

◆ t8_element_array_init_view()

void t8_element_array_init_view ( t8_element_array_t *  view,
t8_element_array_t *  array,
size_t  offset,
size_t  length 
)

Initializes an already allocated (or static) view from existing t8_element_array.

The array view returned does not require t8_element_array_reset (doesn't hurt though).

Parameters
[in,out]viewArray structure to be initialized.
[in]arrayThe array must not be resized while view is alive.
[in]offsetThe offset of the viewed section in element units. This offset cannot be changed until the view is reset.
[in]lengthThe length of the view in element units. The view cannot be resized to exceed this length. It is not necessary to call sc_array_reset later.

◆ t8_element_array_new()

t8_element_array_t* t8_element_array_new ( t8_eclass_scheme_c *  scheme)

Creates a new array structure with 0 elements.

Parameters
[in]schemeThe eclass scheme of which elements should be stored.
Returns
Return an allocated array of zero length.

◆ t8_element_array_new_count()

t8_element_array_t* t8_element_array_new_count ( t8_eclass_scheme_c *  scheme,
size_t  num_elements 
)

Creates a new array structure with a given length (number of elements) and calls t8_element_new for those elements.

Parameters
[in]schemeThe eclass scheme of which elements should be stored.
[in]num_elementsInitial number of array elements.
Returns
Return an allocated array with allocated and initialized elements for which t8_element_new was called.

◆ t8_element_array_push()

t8_element_t* t8_element_array_push ( t8_element_array_t *  element_array)

Enlarge an array by one element.

Parameters
[in,ou]element_array Array structure to be modified.
Returns
Returns a pointer to a newly added element for which t8_element_init was called.

◆ t8_element_array_push_count()

t8_element_t* t8_element_array_push_count ( t8_element_array_t *  element_array,
size_t  count 
)

Enlarge an array by a number of elements.

Parameters
[in,ou]element_array Array structure to be modified.
[in]countThe number of elements to add.
Returns
Returns a pointer to the newly added elements for which t8_element_init was called.

◆ t8_element_array_reset()

void t8_element_array_reset ( t8_element_array_t *  element_array)

Sets the array count to zero and frees all elements.

Parameters
[in,out]element_arrayArray structure to be reset.
Note
Calling t8_element_array_init, then any array operations, then t8_element_array_reset is memory neutral.

◆ t8_element_array_resize()

void t8_element_array_resize ( t8_element_array_t *  element_array,
size_t  new_count 
)

Change the number of elements stored in an element array.

Parameters
[in,out]element_arrayThe element array to be modified.
[in]new_countThe new element count of the array. If it is zero the effect equals t8_element_array_reset.
Note
If new_count is larger than the number of current elements on element_array, then t8_element_init is called for the new elements.

◆ t8_element_array_truncate()

void t8_element_array_truncate ( t8_element_array_t *  element_array)

Sets the array count to zero, but does not free elements.

Parameters
[in,out]element_arrayElement array structure to be truncated.
Note
This is intended to allow an t8_element_array to be used as a reusable buffer, where the "high water mark" of the buffer is preserved, so that O(log (max n)) reallocs occur over the life of the buffer.