Kind: A type definition for Jazz Blocks and Tuples. More...

#include <kind.h>

Inheritance diagram for jazz_elements::Kind:

Public Member Functions
char *	item_name (int idx)

int	index (pChar name)

void	dimensions (Dimensions &dims)

int	new_kind (int num_items, int num_bytes, AttributeMap *att=nullptr)

bool	add_item (int idx, char const p_name, int p_dim, int cell_type, AttributeMap *p_dims)

int	audit ()
	Audit a Kind.

Public Member Functions inherited from jazz_elements::Block
void	set_dimensions (int *p_dim)

void	get_dimensions (int *p_dim)

bool	validate_index (int *p_idx)

int	validate_offset (int offset)

int	get_offset (int *p_idx)

void	get_index (int offset, int *p_idx)

char *	get_string (int *p_idx)

char *	get_string (int offset)

void	set_string (int p_idx, const char p_str)

void	set_string (int offset, const char *p_str)

char *	get_attribute (int attribute_id)

void	set_attributes (AttributeMap *all_att)

void	get_attributes (AttributeMap *all_att)

void	init_string_buffer ()

bool	find_NAs_in_tensor ()

int *	align64bit (uintptr_t ipt)
	Align a pointer (as uintptr_t) to the next 8 byte boundary assuming the block is aligned.

int *	p_attribute_keys ()

pStringBuffer	p_string_buffer ()

int	get_string_offset (pStringBuffer psb, const char *p_str)

bool	is_a_filter ()
	Check (in depth) the validity of a filter.

bool	can_filter (pBlock p_block)

void	close_block (int set_has_NA=SET_HAS_NA_FALSE, bool set_hash=true, bool set_time=true)

bool	check_hash ()

Additional Inherited Members
Data Fields inherited from jazz_elements::StaticBlockHeader
int	cell_type
	The type for the cells in the tensor. See CELL_TYPE_*.

int	size
	The total number of cells in the tensor.

TimePoint	created
	Timestamp when the block was created.

int	rank
	The number of dimensions.

TensorDim	range
	The dimensions of the tensor in terms of ranges (Max. size is 2 Gb.)

int	num_attributes
	Number of elements in the JazzAttributesMap.

int	total_bytes
	Total size of the block everything included.

bool	has_NA
	If true, at least one value is a NA and block requires NA-aware arithmetic.

uint64_t	hash64
	Hash of everything but the header.

Tensor	tensor
	A tensor for type cell_type and dimensions set by Block.set_dimensions()

Detailed Description

Kind: A type definition for Jazz Blocks and Tuples.

Kind objects contain the metadata only. A Tuple is a data object of a Kind. Kinds define more complex types than (raw) Blocks, even if they are blocks. E.g., A Block can store a video of a fixed shape (image only or soundtrack only). A Kind can store both and have dimensions** defining things like: image_width, image_height, number_of_frames and, possibly, a subtitle track as another vector of strings.

It is a block with special attributes to store an array of Tensor. A Kind is a single Block! A kind has dimensions which are integer variables that are used to define variable shapes.

Technically, a Kind is a Block of type CELL_TYPE_KIND_ITEM. Each item contains the Tensor metadata.

Since kinds keep only metadata, the space, unlike in Tuples, is uninterrupted as in a normal block: (header, vector of CELL_TYPE_KIND_ITEM, attribute keys, StringBuffer).

The StringBuffer contains the item names and dimension names.

Creating Kinds

More advanced Kind functionalities (including creating kinds) can be done by Containers. This object, has a minimum of functionality to build by parts: new_kind(), add_item() to do the basic building. It also has function to check the content and validate a Kind.

Also, kinds should define, these attributes, but that is left to the Container:

BLOCK_ATTRIB_BLOCKTYPE as the const "Kind"
BLOCK_ATTRIB_SOURCE as the location where the definition of the Kind can be found. Kind names are global.

Member Function Documentation

◆ item_name()

char * jazz_elements::Kind::item_name ( int idx )

inline

Get the name for an item of a Kind by index without checking index range.

Parameters

idx	The index of the item.

Returns: A pointer to where the (zero ended) string is stored in the Block or nullptr for an invalid index.

NOTE: Use the pointer as read-only (more than one cell may point to the same value) and never try to free it.

◆ index()

int jazz_elements::Kind::index ( pChar name )

inline

Get the index for an item of a Kind by name.

Parameters

name	The name of the item.

Returns: A invalid index or -1 for "not found".

◆ dimensions()

void jazz_elements::Kind::dimensions ( Dimensions & dims )

inline

Pushes the Kind's dimension names into an std::set.

Parameters

dims	The set where the dimension names will be stored.

◆ new_kind()

int jazz_elements::Kind::new_kind	(	int	num_items,
		int	num_bytes,
		AttributeMap *	att = `nullptr`
	)

inline

Initializes a Kind object (step 1): Initializes the space.

Parameters

num_items	The number of items the Kind will have. This call must be followed by one add_item() for each of them.
num_bytes	The size in bytes allocated. Should be enough for all names, dimensions and attributes + ItemHeaders.
att	The attributes for the Kind. Set "as is", without adding BLOCK_ATTRIB_BLOCKTYPE or anything.

Returns: 0, SERVICE_ERROR_WRONG_ARGUMENTS (range of num_items) or SERVICE_ERROR_NO_MEM (insufficient alloc size).

◆ add_item()

bool jazz_elements::Kind::add_item	(	int	idx,
		char const *	p_name,
		int *	p_dim,
		int	cell_type,
		AttributeMap *	p_dims
	)

inline

Initializes a Kind object (step 2): Adds each of the items.

Parameters

idx	The index of the items to add. Must be in range [0..num_items-1] of the previous new_kind() call.
p_name	The name of the item.
p_dim	The shape of the item. Rank will be set automatically on the first zero.
cell_type	The cell type of the item.
p_dims	Names for the dimensions. See below.

Returns: False on error (insufficient alloc space, wrong shape, wrong dimension names).

How dimensions are defined.

Dimensions are placeholders in the tensor shapes that contain an integer variable such as "width" instead of a constant. They are defined by placing a unique negative number for each dimension in the tensor and giving it a name inside the dims map. E.g., if an image has shape [-1, -2, 3] and dims[-1] == "width" and dims[-2] == "height", The kind will store these variable dimensions together with their names.

◆ audit()

int jazz_elements::Kind::audit ( )

Audit a Kind.

Check the internal validity of a Kind (item structure, dimensions, etc.) not repeated of invalid item names.

Returns: MIXED_TYPE_INVALID on error or MIXED_TYPE_KIND if every check passes ok.

The documentation for this class was generated from the following files:

kind.h
kind.cpp

Public Member Functions

Additional Inherited Members

Detailed Description

Creating Kinds

Member Function Documentation

◆ item_name()

◆ index()

◆ dimensions()

◆ new_kind()

◆ add_item()

How dimensions are defined.

◆ audit()