The MHash-384 core library has been written in plain **C**, and the CLI front-end has been written in **C++**. The core library provides a simple "stream processing" API, that is available in two flavors: a plain C99 version and an *object-oriented* C++ wrapper. Either way, the MHash-384 library produces hash values with a fixed length of 384 bits (48 bytes).
-MHash-384 supports a wide range of compilers, including MSVC++, GCC (MinGW/Cygwin), Clang/LLVM and Intel C++. It also runs on many platforms, including Windows and Linux. Furthermore, the MHash-384 library has already been *ported* to various other programming languages, including **Java**, **Microsoft.NET**, **Python** as well as **Delphi** and **Free Pascal**.
+MHash-384 supports a wide range of compilers, including MSVC++, GCC, MinGW/Cygwin, Clang/LLVM and Intel C++. It also runs on many platforms, including Windows, Linux, BSD and Solaris. Furthermore, the MHash-384 library has already been *ported* to various other programming languages, including **Java**, **Microsoft.NET**, **Python** as well as **Delphi**.
# Quick Start Guide
Pointer to the hash computation state of type `mhash384_t` that will be finalized by this operation.
*Note:* The MHash-384 library does **not** free this memory; it may need to be freed up by the calling application!
-* `uint8_t *digest_out`
+* `uint8_t *digest_out`
Pointer to the memory block where the final MHash-384 hash (digest) is to be stored. This memory needs to be allocated by the calling application! The size of the MHash-384 hash value, in bytes, is equal to `MHASH384_SIZE`.
*Note:* All *bytes* ranging from `digest_out[0]` up to and including `digest_out[MHASH384_SIZE-1]` will be overwritten!
*Parameters:*
-* `uint8_t *digest_out`
+* `uint8_t *digest_out`
Pointer to the memory block where the final MHash-384 hash (digest) is to be stored. This memory needs to be allocated by the calling application! This size of the MHash-384 hash value, in bytes, is equal to `MHASH384_SIZE`.
*Note:* All *bytes* ranging from `digest_out[0]` up to and including `digest_out[MHASH384_SIZE-1]` will be overwritten!
*Parameters:*
-* `uint16_t *major`
+* `uint16_t *major`
Pointer to a variable of type `uint16_t` where the *major* version of the MHash-384 library will be stored.
-* `uint16_t *minor`
+* `uint16_t *minor`
Pointer to a variable of type `uint16_t` where the *minor* version of the MHash-384 library will be stored.
-* `uint16_t *patch`
+* `uint16_t *patch`
Pointer to a variable of type `uint16_t` where the *patch* level of the MHash-384 library will be stored.
### mhash384_selftest()
### MHash384::update() [2]
+ template<size_t size>
+ void MHash384::update(const std::array<std::uint8_t, size> &data)
+
+A convenience overload of the [`MHash384::update()`](#mhash384update-1) function, which processes an `std::array<uint8_t, N>` as input.
+
+*Parameters:*
+
+* `const std::array<uint8_t, N> &data`
+ Read-only reference to the `std::array<uint8_t, N>` containing the input data to be processed.
+ *Note:* All bytes in the range from `data[0]` up to and including `data[data.size()-1]` will be processed as input.
+
+### MHash384::update() [3]
+
void MHash384::update(const std::vector<std::uint8_t> &data)
A convenience overload of the [`MHash384::update()`](#mhash384update-1) function, which processes an `std::vector<uint8_t>` as input.
*Parameters:*
-* `const std::vector<std::uint8_t> &data`
+* `const std::vector<std::uint8_t> &data`
Read-only reference to the `std::vector<uint8_t>` containing the input data to be processed.
- *Note:* All bytes in the range from `vector[0]` up to and including `vector[vector.size()-1]` will be processed as input.
+ *Note:* All bytes in the range from `data[0]` up to and including `data[data.size()-1]` will be processed as input.
-### MHash384::update() [3]
+### MHash384::update() [4]
void MHash384::update(const std::string &text)
*Parameters:*
-* `const std::vector<std::uint8_t> &data`
+* `const std::string &text`
Read-only reference to the `std::string` containing the input data to be processed.
- *Note:* All characters in the range from `str[0]` up to and including `str[str.length()-1]` will be processed as input. Each character in the `std::string` is processed as a *byte* value, disregarding any specific character encoding.
+ *Note:* All characters in the range from `text[0]` up to and including `text[text.length()-1]` will be processed as input. Each character in the `std::string` is processed as a *byte* value, disregarding any specific character encoding.
-### MHash384::update() [4]
+### MHash384::update() [5]
+
+ void MHash384::update(const char *const text)
+
+A convenience overload of the [`MHash384::update()`](#mhash384update-1) function, which processes a NULL-terminated C string as input.
+
+*Parameters:*
+
+* `const char *const text`
+ Read-only pointer to the first character of the NULL-terminated string to be processed.
+ *Note:* All characters in the range from `text[0]` up to and including `text[strlen(text)-1]` will be processed as input. Each character in the C string is processed as a *byte* value, disregarding any specific character encoding.
+
+### MHash384::update() [6]
+
+ template<typename element_type>
+ void MHash384::update(const element_type *const address);
+
+A convenience overload of the [`MHash384::update()`](#mhash384update-1) function, which processes an object designated by a pointer.
+
+*Parameters:*
+
+* `const element_type *const address`
+ Read-only pointer to the target object to be processed.
+ *Note:* The given object is processed as a byte-sequence, like a POD; all bytes in the range from `address[0]` up to and including `address[sizeof(element_type)-1]` will be processed as input.
+
+### MHash384::update() [7]
+
+ template<typename element_type>
+ void MHash384::update(const element_type &element);
+
+A convenience overload of the [`MHash384::update()`](#mhash384update-1) function, which processes an object designated by a reference.
+
+*Parameters:*
+
+* `const element_type &element`
+ Read-only reference to the target object to be processed.
+ *Note:* The given object is processed as a byte-sequence, like a POD; all bytes in the range from `addr[0]` up to and including `addr[sizeof(element_type)-1]` with `addr = std::addressof(element)` will be processed as input.
+
+### MHash384::update() [8]
template<typename iterator_type>
- void update(const iterator_type &first, const iterator_type &last)
+ void MHash384::update(const iterator_type &first, const iterator_type &last)
A convenience overload of the [`MHash384::update()`](#mhash384update-1) function, which processes a sequence of elements via iterators.
*Parameters:*
-* `const iterator_type &first`
+* `const iterator_type &first`
Read-only reference to the iterator designating the *first* element to be processed.
- *Note:* All elements in the range from `*first` up to but excluding `*last` will be processed as input. Each element in this range is processed as a byte-sequence; the size of an element is `sizeof(iterator_type::value_type)`.
+ *Note:* All elements in the range from `*first` up to but excluding `*last` will be processed as input. Each element in this range is processed as a byte-sequence, like a POD, assuming a size of `sizeof(iterator_type::value_type)`.
-* `const iterator_type &last`
- Read-only reference to the iterator designating the *last* element to be processed.
- *Note:* All elements in the range from `*first` up to but excluding `*last` will be processed as input. Each element in this range is processed as a byte-sequence; the size of an element is `sizeof(iterator_type::value_type)`.
+* `const iterator_type &last`
+ Read-only reference to the iterator designating the element just after the *last* element to be processed.
+ *Note:* All elements in the range from `*first` up to but excluding `*last` will be processed as input. Each element in this range is processed as a byte-sequence, like a POD, assuming a size of `sizeof(iterator_type::value_type)`.
### MHash384::finish()
Reset the MHash-384 hash computation. This function re-initializes the internal MHash-384 context, thus starting a new MHash-384 hash computation. It is **not** necessary to explicitly call this function on a new `MHash384` instance; it is called implicitly by the constructor. However, it is possible to re-use an existing `MHash384` instance for multiple (strictly serialized) MHash-384 hash computations, by calling this function in between each pair of consecutive hash computations.
+# Supported platforms
+
+MHash-384 has been tested to successfully build and run on (at least) the following platforms:
+
+## C/C++ library and CLI front-end
+
+* **Microsoft Windows (x84/x64)**
+ - Microsoft Visual C++, version 16.00 (Visual Studio 2010) or newer
+ - Mingw-w64 (from MSYS2), tested with version 8.0.0, using GCC 9.2.0 or Clang 9.0.0
+ - MinGW (mingw.org), tested with version 5.3.2, using GCC 8.2.0
+ - Cygwin, tested with version 3.1.2 (x64), using GCC 7.4.0 or Clang 8.0.1
+
+* **Linux/GNU (x86/x64)**
+ - Ubuntu, tested with version 16.04 (Xenial), using GCC 5.4.0 or Clang 3.8.0
+ - CentOS/Red Hat Enterprise Linux, tested with version 8.1, using GCC 8.3.1 or Clang 8.0.1
+ - Manjaro, tested with version 18.1.5, using GCC 9.2.0 or Clang 9.0.1
+ - openSUSE (Leap), tested with version 15.1, using GCC 7.5.0 or Clang 7.0.1
+
+* **BSD-Family (x86/x64)**
+ - FreeBSD, tested with TrueOS version 18.12, using GCC 7.4.0 or Clang 7.0.1
+ - OpenBSD, tested with version 6.6, using GCC 8.2.0 or Clang 8.0.1
+
+* **Solaris (x86/x64)**
+ - OpenSolaris/Illumos, tested with OpenIndiana version 2019.10, using GCC 9.2.0
+
+## Ports to other lanuguages
+
+* **Java**
+ - Java SE 8, tested with OpenJDK Runtime Environment 1.8.0_242
+ - Java SE 11, tested with OpenJDK Runtime Environment 11.0.5
+
+* **.NET Framework**
+ - Microsoft.NET Framework 4.5 (or newer), tested with Visual Studio 2019 (version 15.9.20)
+ - Mono, tested with Mono C# Compiler version 5.18.0 (Ubuntu 19.10)
+
+* **Python**
+ - CPython 3.x, tested with version 3.8.1
+ - PyPy (Python 3.6 compatible), tested with version 7.3.0, highly recommended for improved performance!
+
+* **Delphi (Object Pascal)**
+ - Bordland Delphi, tested with Delphi 7.1 (DCC 15.00)
+ - Lazarus/Free Pascal, tested with Lazarus 2.06 (Free Pascal Compiler 3.04)
+
+
# License
**MHash-384 - Simple fast portable secure hashing library**
OSDN Git Service
