Release 2.2 (#303)

* Release 2.2

Co-Authored-By: Fernando Pereira <ferdonline@gmail.com>

CHANGELOG.md

@@ -1,4 +1,26 @@
-## Version 2.1 - 2019/10/XX
+## Version 2.2 - 2020/03/23
+### New Features:
+    - Compound Types: API to register and read/write structs (#78). Thanks to Richard Shaw.
+    - Fixed-length strings. API via char[] and `FixedLenStringArray`(#277)
+    - Enum data types (#297)
+    - Datasets of HDF5 References. Support to dereference groups and datasets (#306)
+    - Objects (hard/soft link) can now be deleted with `unlink` (#284). Thanks to Tom Vander Aa.
+    - Attributes can be deleted with `deleteAttribute` (#239)
+
+### Improvements:
+    - `Attribute`s (metadata) now support additional types (#298)
+    - H5Easy: Reworked for compatibility with `Eigen::ref` and `Eigen::Map` (#291, #293)
+    - Hdf5 1.12 compatibility: working `Object::getInfo` and marking getAddress deprecated (#311)
+    - Strict compatibility with CMake 3.1 and C++11 (#304)
+    - CMake: Dependencies may be re-detected on FindPackage, fixed export targets and added integration tests (#255, #304, #312, #317)
+    - Support for array of `Eigen::Matrix` (#258)
+    - Selection: `ElementSet` working for N-dimensions (#247)
+
+### Bug Fixes:
+    - Shortcut syntax with c arrays (#273)
+    - Compatibility with in MSVC (Exception messages #263 and avoid throwing in `exist` check #308)
+
+## Version 2.1 - 2019/10/30
 ### New Features:
     - Inspection: API to get the type of links/objects and datasets data-types (#221)
     - H5Easy: API for simple import/export to Eigen and xtensor (#141)
@@ -7,7 +29,7 @@
     - Shortcut syntax: ability to create a filled dataset in a single line (#130)
     - DataSet now accepts `std::complex` and `std::array`'s (#128, #129)
 
-### Improvements
+### Improvements:
     - Improved compat with MSVC and ICC compilers
     - CMake build system: modernized, create exported targets, better messages, etc.
     - Building and publishing documentation: https://bluebrain.github.io/HighFive/

README.md

@@ -1,24 +1,33 @@
 # HighFive - HDF5 header-only C++ Library
 
 [![Build Status](https://travis-ci.org/BlueBrain/HighFive.svg?branch=master)](https://travis-ci.org/BlueBrain/HighFive)
-
 [![Coverity Statys](https://scan.coverity.com/projects/13635/badge.svg)](https://scan.coverity.com/projects/highfive)
 
 ## Brief
 
-HighFive is a modern C++/C++11 friendly interface for libhdf5.
+HighFive is a modern header-only C++11 friendly interface for libhdf5.
 
-HighFive supports STL vector/string, Boost::UBLAS and Boost::Multi-array. It handles C++ from/to HDF5 automatic type mapping.
-HighFive does not require an additional library and supports both HDF5 thread safety and Parallel HDF5 (contrary to the official hdf5 cpp)
+HighFive supports STL vector/string, Boost::UBLAS, Boost::Multi-array, Eigen and Xtensor. It handles C++ from/to HDF5 with automatic type mapping.
+HighFive does not require additional libraries (see dependencies) and supports both HDF5 thread safety and Parallel HDF5 (contrary to the official hdf5 cpp)
 
+It integrates nicely with other CMake projects by defining (and exporting) a HighFive target.
 
-### Design
 
+### Design
 - Simple C++-ish minimalist interface
 - No other dependency than libhdf5
 - Zero overhead
 - Support C++11
 
+### Feature support
+- create/read/write files, datasets, attributes, groups, dataspaces.
+- automatic memory management / ref counting
+- automatic conversion of `std::vector` and nested `std::vector` from/to any dataset with basic types
+- automatic conversion of `std::string` to/from variable length string dataset
+- selection() / slice support
+- parallel Read/Write operations from several nodes with Parallel HDF5
+- Advanced types: Compound, Enum, Arrays of Fixed-length strings, References
+- etc... (see [ChangeLog](./CHANGELOG.md))
 
 ### Dependencies
 - hdf5 (dev)
@@ -28,23 +37,7 @@ HighFive does not require an additional library and supports both HDF5 thread sa
 - xtensor (optional, opt-in with -D*HIGHFIVE_USE_XTENSOR*=ON)
 
 
-### CMake integration
-
-HighFive can easily be used by other C++ CMake projects.
-Below is a very simple *foo* project creating a *bar* C++ program
-using HighFive library:
-
-```cmake
-cmake_minimum_required(VERSION 3.1 FATAL_ERROR)
-project(foo)
-set(CMAKE_CXX_STANDARD 11)
-
-find_package(HighFive 2.1 REQUIRED)
-add_executable(bar bar.cpp)
-target_link_libraries(bar HighFive)
-```
-
-### Usage
+## Examples
 
 #### Write a std::vector<int> to 1D HDF5 dataset and read it back
 
@@ -66,13 +59,11 @@ std::vector<int> result;
 dataset.read(result);
 ```
 
-> Note: if you can use `DataSpace::From` on your data, you can combine the create and write into one statement:
-> 
-> ```c++
-> DataSet dataset = file.createDataSet("/dataset_one",  data);
-> ```
->
-> This works with `createAttribute`, as well.
+**Note:** if you can use `DataSpace::From` on your data, you can combine the create and write into one statement.
+Such shortcut syntax is available for both `createDataSet` and `createAttribute`.
+```c++
+DataSet dataset = file.createDataSet("/dataset_one",  data);
+```
 
 #### Write a 2 dimensional C double float array to a 2D HDF5 dataset
 
@@ -94,41 +85,40 @@ See [create_attribute_string_integer.cpp](src/examples/create_attribute_string_i
 
 See [src/examples/](src/examples/) subdirectory for more info.
 
-### Compile with HighFive
+
+### Compiling with HighFive
 
 ```bash
 c++ -o program -I/path/to/highfive/include source.cpp  -lhdf5
 ```
 
-#### H5Easy
+### H5Easy
 
 For several 'standard' use cases the [highfive/H5Easy.hpp](include/highfive/H5Easy.hpp) interface is available. It allows:
 
-*   Reading/writing in a single line of:
+* Reading/writing in a single line of:
 
-    -   scalars (to/from an extendible DataSet),
-    -   strings,
-    -   vectors (of standard types),
-    -   [Eigen::Matrix](http://eigen.tuxfamily.org) (optional, enable CMake option `HIGHFIVE_USE_EIGEN`),
-    -   [xt::xarray](https://github.com/QuantStack/xtensor) and [xt::xtensor](https://github.com/QuantStack/xtensor)
-        (optional, enable CMake option `HIGHFIVE_USE_XTENSOR`).
+    - scalars (to/from an extendible DataSet),
+    - strings,
+    - vectors (of standard types),
+    - [Eigen::Matrix](http://eigen.tuxfamily.org) (optional, enable CMake option `HIGHFIVE_USE_EIGEN`),
+    - [xt::xarray](https://github.com/QuantStack/xtensor) and [xt::xtensor](https://github.com/QuantStack/xtensor)
+      (optional, enable CMake option `HIGHFIVE_USE_XTENSOR`).
 
-*   Getting in a single line:
+* Getting in a single line:
 
-     -   the size of a DataSet,
-     -   the shape of a DataSet.
+    - the size of a DataSet,
+    - the shape of a DataSet.
 
-The general idea is to 
+#### Example
 
 ```cpp
 #include <highfive/H5Easy.hpp>
 
-int main()
-{
+int main() {
     H5Easy::File file("example.h5", H5Easy::File::Overwrite);
 
     int A = ...;
-
     H5Easy::dump(file, "/path/to/A", A);
 
     A = H5Easy::load<int>(file, "/path/to/A");
@@ -137,40 +127,69 @@ int main()
 
 whereby the `int` type of this example can be replaced by any of the above types. See [easy_load_dump.cpp](src/examples/easy_load_dump.cpp) for more details.
 
-> Note that classes such as `H5Easy::File` are just short for the regular `HighFive` classes (in this case `HighFive::File`). They can thus be used interchangeably.
+**Note:** Classes such as `H5Easy::File` are just short for the regular `HighFive` classes (in this case `HighFive::File`). They can thus be used interchangeably.
+
+
+## CMake integration
+
+HighFive can easily be used by other C++ CMake projects.
+
+You may use HighFive from a folder in your project (typically a git submodule).
+```cmake
+cmake_minimum_required(VERSION 3.1 FATAL_ERROR)
+project(foo)
+set(CMAKE_CXX_STANDARD 11)
+
+add_subdirectory(highfive_folder)
+add_executable(bar bar.cpp)
+target_link_libraries(bar HighFive)
+```
+
+Alternativelly you can install HighFive once and use it in several projects via `find_package()`.
+
+A HighFive target will bring the compilation settings to find HighFive headers and all chosen dependencies.
+
+```cmake
+# ...
+find_package(HighFive REQUIRED)
+add_executable(bar bar.cpp)
+target_link_libraries(bar HighFive)
+```
+**Note:** Like with other libraries you may need to provide CMake the location to find highfive: `CMAKE_PREFIX_PATH=<highfive_install_dir>`
+
+**Note:** `find_package(HighFive)` will search dependencies as well (e.g. Boost if requested). In order to use the same dependencies found at HighFive install time (e.g. for system deployments) you may set `HIGHFIVE_USE_INSTALL_DEPS=YES`
+
+### Installing
+When installing via CMake, besides the headers, a HighFiveConfig.cmake is generated which provides the HighFive target, as seen before. Note: You may need to set `CMAKE_INSTALL_PREFIX`:
+```bash
+mkdir build && cd build
+# Look up HighFive CMake options, consider inspecting with `ccmake`
+cmake .. -DHIGHFIVE_EXAMPLES=OFF -DCMAKE_INSTALL_PREFIX="<highfive_install_dir>"
+make install
+```
 
 ### Test Compilation
-Remember: Compilation is not required. Used only for unit test and examples
-Unit tests need boost (*USE_BOOST*).
+As a header-only library, HighFive doesn't require compilation. You may however build tests and examples.
 
 ```bash
-mkdir build; pushd build
+mkdir build && cd build
 cmake ../
-make
-make test
+make  # build tests and examples
+make test  # build and run unit tests
 ```
 
-### Feature support
-
-- create/read/write file, dataset, group, dataspace.
-- automatic memory management / ref counting
-- automatic conversion of `std::vector` and nested `std::vector` from/to any dataset with basic types
-- automatic conversion of `std::string` to/from variable length string dataset
-- selection() / slice support
-- parallel Read/Write operations from several nodes with Parallel HDF5
-- support HDF5 attributes
+**Note:** Unit tests require Boost. In case it's unavailable you may use `-DHIGHFIVE_USE_BOOST=OFF`.
+HighFive with disable support for Boost types as well as unit tests (though most examples will build).
 
 
 ### Contributors
 
-- Adrien Devresse <adrien.devresse@epfl.ch> - Blue Brain Project
-- Ali Can Demiralp <demiralpali@gmail.com> -
-- Fernando Pereira <fernando.pereira@epfl.ch> - Blue Brain Project
-- Stefan Eilemann <stefan.eilemann@epfl.ch> - Blue Brain Project
-- Tristan Carel <tristan.carel@epfl.ch> - Blue Brain Project
-- Wolf Vollprecht <w.vollprecht@gmail.com> - QuantStack
-- Tom de Geus <tom@geus.me> - EPFL
-- Nicolas Cornu <nicolas.cornu@epfl.ch> - Blue Brain Project
+See the list of contributors on [GitHub](https://github.com/BlueBrain/HighFive/graphs/contributors)
+
+Originally created by Adrien Devresse adrien.devresse@epfl.ch - Blue Brain Project
+
+Maintained by the Computing/HPC team, Blue Brain Project - EPFL
+
 
 ### License
 

VERSION

@@ -1 +1 @@
-2.1
+2.2