Class Block¶

Defined in File Block.hpp

Inheritance Relationships¶

Base Type¶

public nix::base::EntityWithMetadata< base::IBlock > (Template Class EntityWithMetadata)

Class Documentation¶

class Block : public nix::base::EntityWithMetadata<base::IBlock>¶

Class for grouping further data entities.

The Block entity is a top-level, summarizing element that allows to group the other data entities belonging for example to the same recording session. All data entities such as nix::Source, nix::DataArray, nix::Tag and nix::MultiTag have to be associated with one Block.

Create a new

A block can only be created on an existing file object. Do not use the blocks constructors for this purpose.

File f = ...;
Block b = f.createBlock("session one", "recording_session");

Working with blocks

After a block was created it can be used to create further entities. See the documentation of nix::Source, nix::DataArray, nix::Tag and nix::MultiTag for more information. The next example shows how some properties of a block can be accessed.

File f = ...;
Block b = f.getBlock(some_id);

// set the blocks name
std::string name = b.name("session two")

// add metadata to a block
Section s = f.getSection(sec_id);
b.metadata(s);

// get associated metadata from a block
b.metadata();

// remove associated metadata from a block
b.metadata(boost::none);

Deleting a block

When a block is deleted from a file all contained data e.g. sources, data arrays and tags will be removed too.

File f = ...;
bool deleted = f.deleteBlock(some_id);
cout << "The block was " << deleted ? "" : "not " << "deleted" << endl;

Public Functions

inline Block()¶

Constructor that creates an uninitialized Block.

Calling any method on an uninitialized block will throw a nix::UninitializedEntity exception. The following code illustrates how to check if a block is initialized:

Block e = ...;
if (e) {
    // e is initialised
} else {
    // e is uninitialized
}

inline Block(const Block &other)¶

Copy constructor.

Copying of all NIX front facing objects like block is a rather cheap operation. Semantically this is equivalent to the creation of another reference to the original object.

Parameters: other – The block to copy.

inline Block(const std::shared_ptr<base::IBlock> &p_impl)¶

Constructor that creates a new entity from a shared pointer to an implementation instance.

This constructor should only be used in the back-end.

inline Block(std::shared_ptr<base::IBlock> &&ptr)¶

Constructor with move semantics that creates a new entity from a shared pointer to an implementation instance.

This constructor should only be used in the back-end.

inline bool hasSource(const std::string &name_or_id) const¶

Checks if this block has a specific root source.

Parameters: name_or_id – Name or id of the source.
Returns: True if a source with the given id exists at the root, false otherwise.

inline bool hasSource(const Source &source) const¶

Checks if this block has a specific root source.

Parameters: source – The source to check.
Returns: True if the source exists at the root, false otherwise.

inline Source getSource(const std::string &name_or_id) const¶

Retrieves a specific root source by its id.

Parameters: name_or_id – Name or id of the source.
Returns: The source with the given id. If it doesn’t exist an exception will be thrown.

inline Source getSource(ndsize_t index) const¶

Retrieves a specific root source by index.

Parameters: index – The index of the source.
Returns: The source at the specified index.

inline ndsize_t sourceCount() const¶

Returns the number of root sources in this block.

Returns: The number of root sources.

std::vector<Source> sources(const util::Filter<Source>::type &filter = util::AcceptAll<Source>()) const¶

Get all root sources associated with this block.

The parameter filter can be used to filter sources by various criteria. By default a filter is used that accepts all sources.

Parameters: filter – A filter function.
Returns: A vector containing the matching root sources.

std::vector<Source> findSources(const util::Filter<Source>::type &filter = util::AcceptAll<Source>(), size_t max_depth = std::numeric_limits<size_t>::max()) const¶

Get all sources in this block recursively.

This method traverses the tree of all sources in the block. The traversal is accomplished via breadth first and can be limited in depth. On each node or source a filter is applied. If the filter returns true the respective source will be added to the result list. By default a filter is used that accepts all sources.

Parameters

filter – A filter function.
max_depth – The maximum depth of traversal.

Returns

A vector containing the matching sources.

Source createSource(const std::string &name, const std::string &type)¶

Create a new root source.

Parameters

name – The name of the source to create.
type – The type of the source.

Returns

The created source object.

inline bool deleteSource(const std::string &name_or_id)¶

Deletes a root source.

This will also delete all child sources of this root source from the file. The deletion of a source can’t be undone.

Parameters: name_or_id – Name or id of the source to delete.
Returns: True if the source was deleted, false otherwise.

bool deleteSource(const Source &source)¶

Deletes a root source.

This will also delete all child sources of this root source from the file. The deletion of a source can’t be undone.

Parameters: source – The source to delete.
Returns: True if the source was deleted, false otherwise.

inline bool hasDataArray(const std::string &name_or_id) const¶

Checks if a specific data array exists in this block.

Parameters: name_or_id – Name or id of a data array.
Returns: True if the data array exists, false otherwise.

inline bool hasDataArray(const DataArray &data_array) const¶

Checks if a specific data array exists in this block.

Parameters: data_array – The data array to check.
Returns: True if the data array exists, false otherwise.

inline DataArray getDataArray(const std::string &name_or_id) const¶

Retrieves a specific data array from the block by name or id.

Parameters: name_or_id – Name or id of an existing data array.
Returns: The data array with the specified id. If this doesn’t exist, an exception will be thrown.

inline DataArray getDataArray(ndsize_t index) const¶

Retrieves a data array by index.

Parameters: index – The index of the data array.
Returns: The data array at the specified index.

std::vector<DataArray> dataArrays(const util::AcceptAll<DataArray>::type &filter = util::AcceptAll<DataArray>()) const¶

Get data arrays within this block.

The parameter filter can be used to filter data arrays by various criteria. By default a filter is used that accepts all data arrays.

Parameters: filter – A filter function.
Returns: A vector that contains all filtered data arrays.

inline ndsize_t dataArrayCount() const¶

Returns the number of all data arrays of the block.

Returns: The number of data arrays of the block.

DataArray createDataArray(const std::string &name, const std::string &type, nix::DataType data_type, const NDSize &shape, const Compression &compression = Compression::Auto)¶

Create a new data array associated with this block.

Parameters

name – The name of the data array to create.
type – The type of the data array.
data_type – A nix::DataType indicating the format to store values.
shape – A NDSize holding the extent of the array to create.
compression – En-/disable dataset compression, default nix::Compression::Auto.

Returns

The newly created data array.

template<typename T> inline DataArray createDataArray(const std::string &name, const std::string &type, const T &data, DataType data_type = DataType::Nothing, const Compression &compression = Compression::Auto)¶

Create a new data array associated with this block.

Create a data array with shape and type inferred from data. After successful creation, the contents of data will be written to the data array. If data_type has been specified the DataArray will be created with the specified type instead of the type inferred from the data.

Parameters

name – The name of the data array to create.
type – The type of the data array.
data – Data to create array with.
data_type – A optional nix::DataType indicating the format to store values.
compression – En-/disable dataset compression, default nix::Compression::Auto.

Returns

The newly created data array.

inline bool deleteDataArray(const std::string &name_or_id)¶

Deletes a data array from this block.

This deletes a data array and all its dimensions from the block and the file. The deletion can’t be undone.

Parameters: name_or_id – Name or id of the data array to delete.
Returns: True if the data array was deleted, false otherwise.

inline bool deleteDataArray(const DataArray &data_array)¶

Deletes a data array from this block.

This deletes a data array and all its dimensions from the block and the file. The deletion can’t be undone.

Parameters: data_array – The data array to delete.
Returns: True if the data array was deleted, false otherwise.

inline DataFrame createDataFrame(const std::string &name, const std::string &type, const std::vector<Column> &cols, const Compression &compression = Compression::Auto)¶

Create a new data frame associated with this block.

Parameters

name – The name of the data frame to create.
type – The type of the data frame.
cols – A vector of nix::Column representing the columns to create.
compression – En-/disable dataset compression, default nix::Compression::Auto.

Returns

The newly created data frame.

inline bool hasDataFrame(const std::string &name_or_id) const¶

Checks if a specific data frame exists in this block.

Parameters: name_or_id – Name or id of a data frame.
Returns: True if the data frame exists, false otherwise.

inline bool hasDataFrame(const DataFrame &df) const¶

Checks if a specific data frame exists in this block.

Parameters: df – The data frame to check.
Returns: True if the data frame exists, false otherwise.

inline DataFrame getDataFrame(const std::string &name_or_id) const¶

Retrieves a specific data frame from the block by name or id.

Parameters: name_or_id – Name or id of an existing data frame.
Returns: The data frame with the specified id. If this doesn’t exist, an exception will be thrown.

inline DataFrame getDataFrame(ndsize_t index) const¶

Retrieves a data frame by index.

Parameters: index – The index of the data frame.
Returns: The data frame at the specified index.

std::vector<DataFrame> dataFrames(const util::AcceptAll<DataFrame>::type &filter = util::AcceptAll<DataFrame>()) const¶

Get data frames within this block.

The parameter filter can be used to filter data frames by various criteria. By default a filter is used that accepts all data frames.

Parameters: filter – A filter function.
Returns: A vector that contains all filtered data frames.

inline ndsize_t dataFrameCount() const¶

Returns the number of all data frames of the block.

Returns: The number of data frames of the block.

inline bool deleteDataFrame(const std::string &name_or_id)¶

Deletes a data frame from this block.

This deletes a data frame and all its dimensions from the block and the file. The deletion can’t be undone.

Parameters: name_or_id – Name or id of the data frame to delete.
Returns: True if the data frame was deleted, false otherwise.

inline bool deleteDataFrame(const DataFrame &df)¶

Deletes a data frame from this block.

This deletes a data frame and all its dimensions from the block and the file. The deletion can’t be undone.

Parameters: df – The data frame to delete.
Returns: True if the data frame was deleted, false otherwise.

inline bool hasTag(const std::string &name_or_id) const¶

Checks if a specific tag exists in the block.

Parameters: name_or_id – Name or id of a tag.
Returns: True if the tag exists, false otherwise.

inline bool hasTag(const Tag &tag) const¶

Checks if a specific tag exists in the block.

Parameters: tag – The tag to check.
Returns: True if the tag exists, false otherwise.

inline Tag getTag(const std::string &name_or_id) const¶

Retrieves a specific tag from the block by its id.

Parameters: name_or_id – Name or id of the tag.
Returns: The tag with the specified id. If this tag doesn’t exist an exception will be thrown.

inline Tag getTag(ndsize_t index) const¶

Retrieves a specific tag by index.

Parameters: index – The index of the tag.
Returns: The tag at the specified index.

std::vector<Tag> tags(const util::Filter<Tag>::type &filter = util::AcceptAll<Tag>()) const¶

Get tags within this block.

The parameter filter can be used to filter tags by various criteria. By default a filter is used that accepts all tags.

Parameters: filter – A filter function.
Returns: A vector that contains all filtered tags.

inline ndsize_t tagCount() const¶

Returns the number of tags within this block.

Returns: The number of tags.

Tag createTag(const std::string &name, const std::string &type, const std::vector<double> &position)¶

Create a new tag associated with this block.

Parameters

name – The name of the tag to create.
type – The type of the tag.
position – The position of the tag.

Returns

The newly created tag.

inline bool deleteTag(const std::string &name_or_id)¶

Deletes a tag from the block.

Deletes a tag with all its features from the block and the file. The deletion can’t be undone.

Parameters: name_or_id – Name or id of the tag to remove.
Returns: True if the tag was removed, false otherwise.

inline bool deleteTag(const Tag &tag)¶

Deletes a tag from the block.

Deletes a tag with all its features from the block and the file. The deletion can’t be undone.

Parameters: tag – The tag to remove.
Returns: True if the tag was removed, false otherwise.

inline bool hasMultiTag(const std::string &name_or_id) const¶

Checks if a specific multi tag exists in the block.

Parameters: name_or_id – Name or id of a multi tag.
Returns: True if the multi tag exists, false otherwise.

inline bool hasMultiTag(const MultiTag &multi_tag) const¶

Checks if a specific multi tag exists in the block.

Parameters: multi_tag – The multi tag to check.
Returns: True if the multi tag exists, false otherwise.

inline MultiTag getMultiTag(const std::string &name_or_id) const¶

Retrieves a specific multi tag from the block by its id.

Parameters: name_or_id – Name or id of the multi tag.
Returns: The tag with the specified id. If this tag doesn’t exist an exception will be thrown.

inline MultiTag getMultiTag(ndsize_t index) const¶

Retrieves a specific multi tag by index.

Parameters: index – The index of the tag.
Returns: The multi tag at the specified index.

std::vector<MultiTag> multiTags(const util::AcceptAll<MultiTag>::type &filter = util::AcceptAll<MultiTag>()) const¶

Get multi tags within this block.

The parameter filter can be used to filter multi tags by various criteria. By default a filter is used that accepts all tags.

Parameters: filter – A filter function.
Returns: A vector that contains all filtered multi tags.

inline ndsize_t multiTagCount() const¶

Returns the number of multi tags associated with this block.

Returns: The number of multi tags.

MultiTag createMultiTag(const std::string &name, const std::string &type, const DataArray &positions)¶

Create a new multi tag associated with this block.

Parameters

name – The name of the multi tag to create.
type – The type of the tag.
positions – The positions of the tag.

Returns

The newly created tag.

inline bool deleteMultiTag(const std::string &name_or_id)¶

Deletes a multi tag from the block.

Deletes a multi tag and all its features from the block and the file. The deletion can’t be undone.

Parameters: name_or_id – Name or id of the tag to remove.
Returns: True if the tag was removed, false otherwise.

inline bool deleteMultiTag(const MultiTag &multi_tag)¶

Deletes a multi tag from the block.

Deletes a multi tag and all its features from the block and the file. The deletion can’t be undone.

Parameters: multi_tag – The tag to remove.
Returns: True if the tag was removed, false otherwise.

inline bool hasGroup(const std::string &name_or_id) const¶

Checks if a specific group exists in the block.

Parameters: name_or_id – Name or id of a group.
Returns: True if the group exists, false otherwise.

inline bool hasGroup(const Group &group) const¶

Checks if a specific group exists in the block.

Parameters: group – The group to check.
Returns: True if the group exists, false otherwise.

inline Group getGroup(const std::string &name_or_id) const¶

Retrieves a specific group from the block by its id.

Parameters: name_or_id – Name or id of the group.
Returns: The group with the specified id. If this tag doesn’t exist an exception will be thrown.

inline Group getGroup(ndsize_t index) const¶

Retrieves a specific group by index.

Parameters: index – The index of the group.
Returns: The group at the specified index.

std::vector<Group> groups(const util::AcceptAll<Group>::type &filter = util::AcceptAll<Group>()) const¶

Get groups within this block.

The parameter filter can be used to filter groups by various criteria. By default a filter is used that accepts all groups.

Parameters: filter – A filter function.
Returns: A vector that contains all filtered groups.

inline ndsize_t groupCount() const¶

Returns the number of groups associated with this block.

Returns: The number of groups.

Group createGroup(const std::string &name, const std::string &type)¶

Create a new group associated with this block.

Parameters

name – The name of the group to create.
type – The type of the tag.

Returns

The newly created group.

inline bool deleteGroup(const std::string &name_or_id)¶

Deletes a Group from the block.

Deletes a group and all its features from the block and the file. The deletion can’t be undone.

Parameters: name_or_id – Name or id of the group to remove.
Returns: True if the group was removed, false otherwise.

inline bool deleteGroup(const Group &group)¶

Deletes a group from the block.

Deletes a group and all its features from the block and the file. The deletion can’t be undone.

Parameters: group – The group to remove.
Returns: True if the group was removed, false otherwise.

inline Block &operator=(const none_t &t)¶: Assignment operator for none.

inline Block &operator=(const Block &other)¶: Copy-assignment operator.

Friends

friend NIXAPI friend std::ostream & operator<< (std::ostream &out, const Block &ent): Output operator.