Class RangeDimension

Inheritance Relationships

Base Type

Class Documentation

class RangeDimension : public nix::base::ImplContainer<base::IRangeDimension>

Dimension descriptor for a dimension that is irregularly sampled.

The RangeDimension covers cases in which indicess of a dimension are mapped to other values in a non-regular fashion. For example, when event times are recorded that would occur in irregularly intervals. To achieve the mapping of the indexes an array of mapping values must be provided. Those values are stored in the dimensions ticks property. In analogy to the sampled dimension a unit and a label can be defined.

Public Functions

RangeDimension()

Constructor that creates an uninitialized RangeDimension.

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

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

RangeDimension(const DataArray &array)

Constructor that sets up the RangeDimension to use the values stored in the DataArray as ticks.

This is only valid for DataArray that are 1D and contain numeric values!

Parameters

array – The DataArray.

RangeDimension(const std::shared_ptr<base::IRangeDimension> &p_impl)

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

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

RangeDimension(std::shared_ptr<base::IRangeDimension> &&ptr)

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

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

RangeDimension(const RangeDimension &other)

Copy constructor.

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

Parameters

other – The dimension to copy.

inline bool alias() const

tells if the RangeDimension uses the contents of a linked DataArray for ticks, i.e. is an alias.

Returns

bool true, if RangeDimension is an alias, false otherwise.

inline ndsize_t index() const

The actual dimension that is described by the dimension descriptor.

The index of the dimension entity representing the dimension of the actual data that is defined by this descriptor.

Returns

The dimension index of the dimension.

inline DimensionType dimensionType() const

The type of the dimension.

This field indicates whether the dimension is a SampledDimension, SetDimension or RangeDimension.

Returns

The dimension type.

inline boost::optional<std::string> label() const

Getter for the label of the dimension.

The label of a RangeDimension corresponds to the axis label in a plot of the respective dimension.

Returns

The label of the dimension.

void label(const std::string &label)

Sets the label of the dimension.

Parameters

label – The label of the dimension.

inline void label(const none_t t)

Remove the label of the dimension.

Parameters

t – None

inline boost::optional<std::string> unit() const

Gets the unit of a dimension.

The unit describes which SI unit applies to this dimension and to its sampling interval.

Returns

The unit of the dimension.

void unit(const std::string &unit)

Sets the unit of a dimension.

Parameters

unit – The unit to set.

inline void unit(const none_t t)

Removes the unit from a dimension.

Parameters

t – None

inline std::vector<double> ticks() const

Get the ticks of the dimension.

The ticks map the index of the data at the respective dimension to other values. This can be used to store data that is sampled at irregular intervals.

Returns

A vector with all ticks for the dimension.

inline std::vector<double> ticks(ndsize_t start, size_t count) const

Get a number of ticks from the dimension.

The ticks map the index of the data at the respective dimension to other values. This can be used to store data that is sampled at irregular intervals.

Parameters

  • start – ndsize_t the start index.

  • count – size_t the number of ticks to read.

Returns

A vector with the ticks for the dimension.

void ticks(const std::vector<double> &ticks)

Set the ticks vector for the dimension.

Ticks must be ordered in ascending order.

Parameters

ticks – The new ticks for the dimension provided as a vector.

double tickAt(const ndsize_t index) const

Returns the entry of the range dimension at a given index.

Method will throw an nix::OutOfBounds Exception if the index is invalid

Parameters

index – The index.

Returns

The tick at the given index.

PositionInRange positionInRange(const double position) const

Checks whether a given position is in the Range of ticks in this dimension.

Parameters

position – The position.

Returns

PositionInRange which can be either Less, Greater, or InRange

boost::optional<ndsize_t> indexOf(const double position, PositionMatch matching) const

Returns the index of the given position.

Method will return the index of the tick that matches or is close to position. The way of matching can be controlled using the PositionMatch enum.

Parameters

  • position – The position.

  • matching – PositionMatch enum entry that defines the matching behavior.

Returns

boost optional containing the index if valid

boost::optional<std::pair<ndsize_t, ndsize_t>> indexOf(double start, double end, std::vector<double> ticks, RangeMatch match = RangeMatch::Exclusive) const

Returns the start and end index of the given start and end positions. By default, the range includes the end position. This can be controlled via the RangeMatch enum.

Parameters

  • start – The start position

  • end – The end position

  • ticks – std::vector<double> of ticks, if empty ({}) they are automatically retrieved

  • range – RangeMatch enum, controls whether end is included or not, defaults to RangeMatch::Inclusive

Returns

Start and end indices returned in a boost::optional<std::pair> which is invalid if out of range.

DEPRECATED ndsize_t indexOf (const double position, bool less_or_equal=true) const

Returns the index of the given position.

Method will return the index of the tick that matches or is close to position. If “less_or_equal” is true, the index of the first tick that is less or equal is given. If “less_or_equal” is false the index of the first index that is greater than than position is returned.

Version 1.4.5: The behavior of this function has been slightly changed, it now throws an OutOfBounds exception if the position is not in the range. Use positionInRange(position) to check before calling this function.

Deprecated:

This function has been deprecated! Use indexOf(position, PositionMatch) instead.

Parameters

  • position – The position.

  • less_or_equal – If true, the first index that is less or equal will be returned. Else, the first index that is not less than position will be returned.

Returns

The index.

DEPRECATED std::pair< ndsize_t, ndsize_t > indexOf (const double start, const double end) const

Returns the start and end index of the given start and end positions.

Method will return the index equal or larger than the respective positions

Version 1.4.5: The behavior of this function has been slightly changed, it now throws an OutOfBounds exception if the position is not in the range. Use positionInRange(position) to check before calling this function.

Deprecated:

This function has been deprecated! Use indexOf(position, PositionMatch) instead.

Parameters

  • start – The start position

  • end – The end position

Returns

Start and end index returned in a std::pair.

DEPRECATED std::vector< std::pair< ndsize_t, ndsize_t > > indexOf (const std::vector< double > &start_positions, const std::vector< double > &end_positions, bool strict, RangeMatch match=RangeMatch::Inclusive) const

Returns a vector of start and end indices of given start and end positions.

Method will return the index equal or larger than the respective positions

Deprecated:

This function has been deprecated and will be removed in future versions!

Parameters

  • start_positions – Vector of start positions

  • end_positions – Vector of end positions

  • strict – Bool that indicates whether the function will throw an OutOfBounds exception when an invalid range occurred or if such ranges are silently ignored. Default is true.

  • match – Enum entry that defines whether the range is inclusive or exclusive regarding the end position

Returns

Vector of pairs of start and end indices.

std::vector<boost::optional<std::pair<ndsize_t, ndsize_t>>> indexOf(const std::vector<double> &start_positions, const std::vector<double> &end_positions, RangeMatch match = RangeMatch::Exclusive) const

Returns a vector of start and end indices of given start and end positions.

Method will return the index equal or larger than the respective positions

Parameters

  • start_positions – Vector of start positions

  • end_positions – Vector of end positions

  • match – Enum entry that defines whether the range is inclusive or exclusive regarding the end position

Returns

Vector of optional pairs of start and end indices.

std::vector<double> axis(const ndsize_t count, const ndsize_t startIndex = 0) const

Returns a vector containing a number of ticks.

The result vector contains a given number of ticks starting from a starting index

Method will throw a nix::OutOfBounds exception if startIndex + count is beyond the number of ticks.

Parameters

  • count – The number of ticks.

  • startIndex – The starting index. Default 0.

Returns

vector<double> containing the ticks.

RangeDimension &operator=(const RangeDimension &other)

Assignment operator.

Parameters

other – The dimension to assign.

RangeDimension &operator=(const Dimension &other)

Assignment operator that converts a Dimension to a RangeDimension.

Parameters

other – The dimension to assign.

inline RangeDimension &operator=(const none_t &t)

Assignment operator for none.

inline double operator[](const ndsize_t index)

Returns the position at the given index.

See also

positionAt for more information.

Parameters

index – The index.

Returns

The position at the given index, e.g. the time.