Path classes and functions

The pni::nexus::Path class

class Path

Nexus path class.

This class represents a full Nexus path. Such a path describes the position of an object within a Nexus file. In general the path has a form like this

filename://entry:NXentry/instrument:NXinstrument/detector/data@attrname

More specific this can be written as

[filename://]path

Usage

string path_str = .....;
nxpath path = nxpath::from_string(path_str);

A path can either be absolute or relative to a particular object. However, a path with a filename part is always absolute (for obvious reasons).

Public Types

using Element = std::pair<pni::string, pni::string>

object element (groupname:class)

using ElementList = std::list<Element>

a list of subsequent objects

using ElementIterator = ElementList::iterator

iterator over elements

using ConstElementIterator = ElementList::const_iterator

const iterator over elements

Public Functions

Path()

default constructor

Path(const fs::path &file, const ElementList &groups, const pni::string &attr)

constructor

Parameters:

• file – name of the file

• groups – a list of elements for the object path

• attr – the optional name of an attribute

explicit Path(const hdf5::Path &path)

constructor

Construct a NeXus path from an HDF5 path. This constructor is deliberately non-explicit. As an HDF5 path does not contain any file or attribute information only the element section of the path will be set.

Parameters:

path – reference to the original HDF5 path

Path(const std::string &str)

constructor

Construct a path from a string.

operator hdf5::Path()

conversion to an HDF5 path

This conversion is only possible if the NeXus path is unique. Otherwise an exception will be thrown.

As an HDF5 path does not contain any information about the file or an attribute this conversion basically copies the names of all object links to the HDF5 path.

Throws:

std::runtime_error – in case of a failure

Returns:

new instance of hdf5::Path

bool has_filename() const noexcept

true if has filename

Returns true if the path contains a file name.

Returns:

true if filename exists

bool has_attribute() const noexcept

true if has attribute

Returns true if the path contains an attribute name.

Returns:

true if path has attribute

fs::path filename() const noexcept

return the filename

void filename(const fs::path &file)

set the filename

std::string attribute() const noexcept

return the attribute name

void attribute(const std::string &attribute_name)

set the attribute name

void push_back(const Element &o)

append element

Append a new element to the end of the Nexus path.

Throws:

value_error – if one tries to push_back a root group to a non-empty path

Parameters:

o – element to append

void push_front(const Element &o)

prepend element

Append an element to the beginning of the Nexus path.

Parameters:

o – element to append

void pop_front()

last element from path

void pop_back()

remove first element from path

inline Element front() const

get last element

Return the last element of the Nexus path.

Returns:

last element

Element back() const

get first element

Return the first element of the Nexus path

Returns:

first element

size_t size() const

return number of group entries

ElementIterator begin()

get iterator to first element

ElementIterator end()

get iterator to last+1 element

ConstElementIterator begin() const

get const iterator to first element

ConstElementIterator end() const

get const iterator to last+1 element

Public Static Functions

static Path from_string(const std::string &input)

create path from string

This method creates a path from a string passed to it.

Throws:

parser_error – in case of parsing problems

Parameters:

input – string with path representation

Returns:

path instance

static std::string to_string(const Path &p)

create string from path

Returns the string representation of a path.

Parameters:

p – reference to path instance

Returns:

string representation of the path

Related

PNINEXUS_EXPORT std::istream &operator>>(std::istream &i, Path &p)

read path from an input stream

Constructing a nexus path from a stream. Analogously to the output operator this is used to read a path from a stream-able source.

nexus::Path p;
std::cin>>p;

Parameters:

• i – reference to the input stream

• p – reference to the path

Returns:

reference to the advanced original stream

PNINEXUS_EXPORT bool operator==(const Path::Element &a, const Path::Element &b)

equality operator for path elements

Two path elements are considered equal if their name and, in the case of groups class, are equal.

Parameters:

• a – reference to the element on the left hand-side of the operator

• b – reference to the element on the right hand-side of the operator

Returns:

true if the elements are equal

PNINEXUS_EXPORT bool operator!=(const Path::Element &a, const Path::Element &b)

inequality operator for path elements

Parameters:

• a – reference to the element on the left hand-side of the operator

• b – reference to the element on the right hand-side of the operator

Returns:

true if the elements are no equal

PNINEXUS_EXPORT bool operator!=(const Path &lhs, const Path &rhs)

inequality operator for two path objects

Compares two path objects and returns true if they are not equal.

Parameters:

• lhs – reference to the path on the left hand-side

• rhs – reference to the path on the right hand-side

Returns:

true if not equal, false otherwise

PNINEXUS_EXPORT std::ostream &operator<<(std::ostream &stream, const Path &p)

output operator for a nexus path

Prints a NeXus path to an output stream. One can either use this to write a Nexus path to standard out

nexus::Path p = ....;
std::cout<<p<<std::endl;

or to a string using the stringstream operator

std::stringstream ss;
ss<<p;

Parameters:

• stream – reference to the output stream

• p – reference to the path

Returns:

reference to the output operator

Related functions

Inquery functions

PNINEXUS_EXPORT bool pni::nexus::has_file_section(const Path &p)

check if path has a file section

Return true if an instance of nxpath has a non-empty file section.

Parameters:

p – reference to an instance of nxpath

Returns:

true if path has a file section, false otherwise

PNINEXUS_EXPORT bool pni::nexus::has_attribute_section(const Path &p)

check if path has an attribute section

Return true if an instance of nxpath has a non-empty attribute section.

Parameters:

p – reference to an instance of nxpath

Returns:

true if the path has an attribute section, false otherweise.

PNINEXUS_EXPORT bool pni::nexus::is_absolute(const Path &p)

check if path is absolute

Parameters:

p – path instance

Returns:

true if path is absolute, false otherwise

PNINEXUS_EXPORT bool pni::nexus::is_unique(const Path &path)

return true if a NeXus path is unique

A NeXus path is considered unique if all elements in its object section have an object name. In this case the path can be unamiguously mapped to an HDF5 path.

Parameters:

path – reference to the NeXus path

Returns:

true if path is unique, false otherwise.

Modification functions

PNINEXUS_EXPORT void pni::nexus::split_path(const Path &p, size_t s, Path &p1, Path &p2)

split a nexus path

Splits a given Nexus path in to two parts at a particular index s of the group part of the path.If the split index is larger or equal the size of the input path an exception will be thrown.

The best is to have a look at the following example

std:::string srep = "file.nx:///entry:NXentry/instrument:NXinstrument/data";
nexus::Path path = nexus::Path::from_string(srep);
nexus::Path p1,p2;
nexus::split_path(path,1,p1,p2);

std::cout<<p1<<std::endl;
std::cout<<p2<<std::endl;

// output
// file.nx:///entry:NXentry
// instrument:NXinstrument/data

Throws:

pni::index_error – if s exceeds input path size

Parameters:

• p – original path

• s – index where to split

• p1 – first part of the path

• p2 – second part of the path

PNINEXUS_EXPORT void pni::nexus::split_last(const Path &p, Path &gp, Path &op)

split path at last element

Split the path at the last element. This is a particularly usefull function for traversing through a path. The only portion of a path which mast not be a group is the last element.

Throws:

pni::index_error –

Parameters:

• p – reference to the original path

• gp – path with groups

• op – path with final object

PNINEXUS_EXPORT Path pni::nexus::join(const Path &a, const Path &b)

join two paths

Join two paths together. This operation can only be carried out if the paths satisfiy some criteria

• a must not have an attribute set

• b must not have the file section set

• b must not be an absolute path

If one of these requirements is not satisfied value_error is thrown. If one of the paths is empty the other one is returned unchanged.

Throws:

value_error – if join requirements are not met by either a or b

Parameters:

• a – first path

• b – second path

Returns:

joined path

PNINEXUS_EXPORT Path pni::nexus::make_relative(const Path &parent_path, const Path &orig_path)

make a relative path

Take a given path and make it relative with respect to a particular other path (typically the path of a parent object).

nexus::Path entry = nexus::Path::from_string("/:NXentry");
nexus::Path det   = nexus::Path::from_string("/:NXentry/:NXinstrument/:NXdetector");

nexus::Path det_rel = nexus::make_relative(entry,det);
std::cout<<det_rel<<std::endl;
// output: :NXinstrument/:NXdetector

For this procedure to work both paths must be absolute as we need a common starting point (which would be the root group). In the case that Both

• both paths must be absolute (as we need a common starting point which would be the root group

• if boths paths have a file section it must be equal

• if

Parameters:

• parent_path – reference to the path to which we want to create a relative one

• orig_path – reference to the original path

Returns:

new instance of Path relative to parent_path

Comparison

PNINEXUS_EXPORT bool pni::nexus::operator==(const Path &lhs, const Path &rhs)

equality operator for two path objects

Compare to path objects. They are considered equal if both paths contain the same components.

Parameters:

• lhs – reference to the path on the left hand-side

• rhs – reference to the path on the right hand-side

Returns:

true if equal, false otherwise

PNINEXUS_EXPORT bool pni::nexus::match(const Path &a, const Path &b)

check if paths are matching

See the users guide for details about when paths are considered as matching.

Parameters:

• a – reference to first path

• b – reference to second path

Returns:

true if paths are matching, false otherwise

NeXus path objects

pni::nexus::PathObject

class PathObject

type erasure for path addressable objects

This is a very simple type erasure (though not implemented in the classic scheme) for all objects which can be addressed with a NeXus path. The current path implementation allows to address

• groups

• datasets

• and attributes

while a common HDF5 path can only address the first two. Thus we need a special return type for all path operations when dereferencing objects in an HDF5 tree.

Public Functions

PathObject()

default constructor

We need default construction for container types. When a PathObject is default constructed its type is Type::None. In this case no conversion to any other object could be achieved.

PathObject(const hdf5::attribute::Attribute &attribute)

constructor

Build a PathObject from an attribute. In this case type() will return Type::Attribute.

Parameters:

attribute – reference to the original attribute

PathObject(const hdf5::node::Node &dataset)

constructor

Build a PathObject from a dataset. After construction type() will return Type::Dataset.

Parameters:

dataset – reference to the original dataset

PathObject(const hdf5::node::Link &link)

constructor

Build a PathObject from a link.

PathObject(const PathObject&) = default

copy constructor

We use the compiler provided default implementation here.

Type type() const noexcept

return type of the currently stored object

Return the type of the currently stored object. If the object was default constructed NONE is returned.

operator hdf5::attribute::Attribute() const

provides implicit conversion to an attribute

Returns the stored object as an HDF5 attribute. If the stored instance is not an HDF5 attribute an exception will be thrown.

Throws:

std::runtime_error – in case of a failure

Pre:

the object stored in the PathObject instance is an instance of hdf5::attribute::Attribute

operator hdf5::node::Group() const

implicit conversion to a group

Throws:

std::runtime_error – in case of a failure

Pre:

the object stored in the PathObject instance is an instance of hdf5::node::Group

operator hdf5::node::Dataset() const

implicit conversion to a dataset

Throws:

std::runtime_error – in case of a failure

Pre:

the object stored in PathObject instance is an instance of hdf5::node::Dataset.

operator hdf5::node::Node() const

implicit conversion to a general HDF5 node type

Provides implicit conversion to an HDF5 node instance. If the object stored is neither a group or a dataset an exception will be thrown.

Throws:

std::runtime_error – in case of a failure

Pre:

the object stored in the PathObject instance is an instance of hdf5::node::Dataset of hdf5::node::Group.

pni::nexus::PathObjectList

class PathObjectList : public std::list<PathObject>

container for PathObject

Used in algorithms returning several instances of PathObject. Can be used along with STL algorithms to filter particular types.

Public Functions

operator NodeList() const

implicit conversion to a NodeList

Throws:

std::runtime_error – in case of a failure

Pre:

all instances in the PathObjectList must store instances of datasets or groups.

operator AttributeList() const

implicit conversion to an AttributeList

Throws:

std::runtime_error – in case of a failure

Pre:

all instances in the PathObjectList must store attributes

operator GroupList() const

implicit conversion to a GroupList

Throws:

std::runtime_error – in case of a failure

Pre:

all instances in the PathObjectList must store groups

operator DatasetList() const

implicit conversion to a DatasetList

Throws:

std::runtime_error – in case of a failure

Pre:

all instances in the PathObjetList must store datasets

Related functions

PNINEXUS_EXPORT bool pni::nexus::is_dataset(const PathObject &object) noexcept

return true if object stores a dataset

PNINEXUS_EXPORT bool pni::nexus::is_group(const PathObject &object) noexcept

return true if object stores a group

PNINEXUS_EXPORT bool pni::nexus::is_attribute(const PathObject &object) noexcept

return true if object stores an attribute

Searching with Paths

PNINEXUS_EXPORT Path pni::nexus::get_path(const hdf5::attribute::Attribute &attribute)

get the NeXus path for an HDF5 attribute

Parameters:

attribute – reference to the attribute for which to obtain the path

Pre:

the attribute must be a valid HDF5 object

PNINEXUS_EXPORT Path pni::nexus::get_path(const hdf5::node::Node &node)

get the NeXus path for an HDF5 node

Parameters:

node – reference to the HDF5 node

Pre:

the node must be a valid HDF5 object

PNINEXUS_EXPORT PathObjectList pni::nexus::get_objects(const hdf5::node::Group &base, const Path &path)

search for objects

Searches recursively below base and return a list of path objects which match path. The function distinguishes two situations

• if path is a relative path the paths of all child objects of base are taken relative to base

• if path is an absolute path the full path of each child must match.

There are some important notes when it comes to dealing with links. Under the hood get_objects iterates over links rather than nodes. This allows the function to handle unresolvable links. If a particular link is resolvable it will be converted into the appropriate node type. In the case of an unresolvable link the link itself will be stored.

Throws:

std::runtime_error – in case of a failure

Parameters:

• base – the base group from which to start the search

• path – the path which to match

Returns:

a list of path objects

PNINEXUS_EXPORT PathObjectList pni::nexus::get_objects(const hdf5::node::Group &base, const std::string &str)

PNINEXUS_EXPORT PathObjectList pni::nexus::get_objects(const hdf5::node::Group &base, const char *str)