diff --git a/include/Athena/DNA.hpp b/include/Athena/DNA.hpp index 5383b99..85dd91f 100644 --- a/include/Athena/DNA.hpp +++ b/include/Athena/DNA.hpp @@ -34,6 +34,7 @@ struct WStringAsString; /** * @brief Base DNA class used against 'atdna' + * @tparam DNAE Default-endianness for contained DNA values * * Athena bundles a build-tool called 'atdna'. This tool functions * just like the 'clang' compiler, except it emits a full .cpp implementation @@ -43,36 +44,88 @@ struct WStringAsString; template struct DNA { + /** + * @brief Common virtual read function for all DNA types + */ virtual void read(IStreamReader&)=0; + /** + * @brief Common virtual write function for all DNA types + */ virtual void write(IStreamWriter&) const=0; + /** + * @brief Template type signaling atdna to capture the value where it's used + * @tparam T The type of the value. Can be any numeric type or atVec* type + * @tparam VE Endianness of the value + */ template using Value = T; + /** + * @brief Template type wrapping std::vector and signaling atdna to manipulate it where it's used + * @tparam T The type of contained elements. Can be any numeric type, atVec* type, or another DNA subclass + * @tparam cntVar C++ expression wrapped in DNA_COUNT macro to determine number of elements for vector + * @tparam VE Endianness of the contained values + */ template using Vector = std::vector; + /** + * @brief Template type wrapping std::unique_ptr and signaling atdna to read a + * raw byte-buffer where it's used + * @tparam sizeVar C++ expression wrapped in DNA_COUNT macro to determine number of bytes for buffer + */ template using Buffer = struct Athena::io::Buffer; + /** + * @brief Template type wrapping std::string and signaling atdna to read string data where it's used + * @tparam sizeVar C++ expression wrapped in DNA_COUNT macro to determine number of characters for string + * -1 literal indicates null-terminated string + */ template using String = struct Athena::io::String; + /** + * @brief Template type wrapping std::wstring and signaling atdna to read wstring data where it's used + * @tparam sizeVar C++ expression wrapped in DNA_COUNT macro to determine number of characters for wstring + * -1 literal indicates null-terminated wstring + */ template using WString = struct Athena::io::WString; + /** + * @brief Template type wrapping std::string and signaling atdna to read wstring data where it's used + * @tparam sizeVar C++ expression wrapped in DNA_COUNT macro to determine number of characters for string + * -1 literal indicates null-terminated string + */ template using WStringAsString = struct Athena::io::WStringAsString; + /** + * @brief Meta Template signaling atdna to insert a stream seek where it's used + * @tparam offset C++ expression wrapped in DNA_COUNT macro to determine number of bytes to seek + * @tparam direction SeekOrigin to seek relative to + */ template struct Seek {}; + /** + * @brief Meta Template signaling atdna to insert an aligning stream seek where it's used + * @tparam align Number of bytes to align to + */ template struct Align {}; + /** + * @brief Meta Template preventing atdna from emitting read/write implementations + */ struct Delete {}; }; +/** + * @brief Concrete buffer type used by DNA::Buffer + */ template struct Buffer : public DNA, public std::unique_ptr { @@ -88,6 +141,9 @@ struct Buffer : public DNA, public std::unique_ptr } }; +/** + * @brief Concrete string type used by DNA::String + */ template struct String : public DNA, public std::string { @@ -102,6 +158,9 @@ struct String : public DNA, public std::string {this->swap(__str); return *this;} }; +/** + * @brief Concrete wstring type used by DNA::WString + */ template struct WString : public DNA, public std::wstring { @@ -122,6 +181,9 @@ struct WString : public DNA, public std::wstring {this->swap(__str); return *this;} }; +/** + * @brief Concrete converting-wstring type used by DNA::WStringAsString + */ template struct WStringAsString : public DNA, public std::string { diff --git a/include/Athena/IStreamReader.hpp b/include/Athena/IStreamReader.hpp index 2175244..21a74db 100644 --- a/include/Athena/IStreamReader.hpp +++ b/include/Athena/IStreamReader.hpp @@ -15,86 +15,86 @@ class IStreamReader : public IStream public: virtual ~IStreamReader() {} - /*! \brief Sets the Endianness of the stream + /** @brief Sets the Endianness of the stream * - * \param endian The Endianness to set \sa Endian + * @param endian The Endianness to set */ inline void setEndian(Endian endian) {m_endian = endian;} - /*! \brief Returns the current Endianness of the stream + /** @brief Returns the current Endianness of the stream * - * \return Endian The current Stream Endianness + * @return The current Stream Endianness */ inline Endian endian() const {return m_endian;} - /*! \brief Returns whether the stream is BigEndian + /** @brief Returns whether the stream is BigEndian * - * \return bool True for BigEndian; False for LittleEndian + * @return bool True for BigEndian; False for LittleEndian */ inline bool isBigEndian() const {return (m_endian == Endian::BigEndian);} - /*! \brief Returns whether the stream is LittleEndian + /** @brief Returns whether the stream is LittleEndian * - * \return bool True for LittleEndian; False for BigEndian + * @return True for LittleEndian; False for BigEndian */ inline bool isLittleEndian()const {return (m_endian == Endian::LittleEndian);} - /*! \brief Sets the buffers position relative to the specified position.
+ /** @brief Sets the buffers position relative to the specified position.
* It seeks relative to the current position by default. - * \param position where in the buffer to seek - * \param origin The Origin to seek \sa SeekOrigin + * @param position where in the buffer to seek + * @param origin The Origin to seek relative to */ virtual void seek(atInt64 pos, SeekOrigin origin = SeekOrigin::Current)=0; - /*! \brief Sets the buffers position relative to the next 32-byte aligned position.
+ /** @brief Sets the buffers position relative to the next 32-byte aligned position.
*/ inline void seekAlign32() {seek(ROUND_UP_32(position()), SeekOrigin::Begin);} - /*! \brief Returns whether or not the stream is at the end. + /** @brief Returns whether or not the stream is at the end. * - * \return bool True if at end; False otherwise. + * @return True if at end; False otherwise. */ inline bool atEnd() const {return position() >= length();} - /*! \brief Returns the current position in the stream. + /** @brief Returns the current position in the stream. * - * \return Int64 The current position in the stream. + * @return The current position in the stream. */ virtual atUint64 position() const=0; - /*! \brief Returns whether or not the stream is at the end. + /** @brief Returns whether or not the stream is at the end. * - * \return bool True if at end; False otherwise. + * @return True if at end; False otherwise. */ virtual atUint64 length() const=0; - /*! \brief Reads a byte at the current position and advances the current position + /** @brief Reads a byte at the current position and advances the current position * - * \return Int8 The value at the current position + * @return The value at the current position */ inline atInt8 readByte() {atInt8 val; readUBytesToBuf(&val, 1); return val;} template inline atInt8 readVal(typename std::enable_if::value>::type* = 0) {return readByte();} - /*! \brief Reads a byte at the current position and advances the current position + /** @brief Reads a byte at the current position and advances the current position * - * \return Uint8 The value at the current position + * @return The value at the current position */ inline atUint8 readUByte() {return readByte();} template inline atUint8 readVal(typename std::enable_if::value>::type* = 0) {return readUByte();} - /*! \brief Reads a byte at the current position and advances the current position. + /** @brief Reads a byte at the current position and advances the current position. * - * \return Uint8* The buffer at the current position from the given length. + * @return The buffer at the current position from the given length. */ inline std::unique_ptr readBytes(atUint64 length) { @@ -103,9 +103,9 @@ public: return std::unique_ptr(buf); } - /*! \brief Reads a byte at the current position and advances the current position. + /** @brief Reads a byte at the current position and advances the current position. * - * \return Int8* The buffer at the current position from the given length. + * @return The buffer at the current position from the given length. */ inline std::unique_ptr readUBytes(atUint64 length) { @@ -117,13 +117,10 @@ public: inline atUint64 readBytesToBuf(void* buf, atUint64 len) {return readUBytesToBuf(buf, len);} virtual atUint64 readUBytesToBuf(void* buf, atUint64 len)=0; - /*! \brief Reads a Int16 and swaps to proper endianness depending on platform - * and Stream settings, and advances the current position + /** @brief Reads a Int16 and swaps to endianness specified by setEndian depending on platform + * and advances the current position * - * \sa Endian - * - * \return Int16 The value at the current address - * \throw IOException when address is out of range + * @return The value at the current address */ inline atInt16 readInt16() { @@ -135,6 +132,11 @@ public: inline atInt16 readVal(typename std::enable_if::value>::type* = 0) {return readInt16();} + /** @brief Reads a Int16 and swaps against little endianness depending on platform + * and advances the current position + * + * @return The value at the current address + */ inline atInt16 readInt16Little() { atInt16 val; @@ -145,6 +147,11 @@ public: inline atInt16 readValLittle(typename std::enable_if::value>::type* = 0) {return readInt16Little();} + /** @brief Reads a Int16 and swaps against big endianness depending on platform + * and advances the current position + * + * @return The value at the current address + */ inline atInt16 readInt16Big() { atInt16 val; @@ -155,13 +162,10 @@ public: inline atInt16 readValBig(typename std::enable_if::value>::type* = 0) {return readInt16Big();} - /*! \brief Reads a Uint16 and swaps to proper endianness depending on platform - * and Stream settings, and advances the current position + /** @brief Reads a Uint16 and swaps to endianness specified by setEndian depending on platform + * and advances the current position * - * \sa Endian - * - * \return Uint16 The value at the current address - * \throw IOException when address is out of range + * @return The value at the current address */ inline atUint16 readUint16() {return readInt16();} @@ -169,6 +173,11 @@ public: inline atUint16 readVal(typename std::enable_if::value>::type* = 0) {return readUint16();} + /** @brief Reads a Uint16 and swaps against little endianness depending on platform + * and advances the current position + * + * @return The value at the current address + */ inline atUint16 readUint16Little() { atUint16 val; @@ -179,6 +188,11 @@ public: inline atUint16 readValLittle(typename std::enable_if::value>::type* = 0) {return readUint16Little();} + /** @brief Reads a Uint16 and swaps against big endianness depending on platform + * and advances the current position + * + * @return The value at the current address + */ inline atUint16 readUint16Big() { atUint16 val; @@ -189,13 +203,10 @@ public: inline atUint16 readValBig(typename std::enable_if::value>::type* = 0) {return readUint16Big();} - /*! \brief Reads a Int32 and swaps to proper endianness depending on platform - * and Stream settings, and advances the current position + /** @brief Reads a Int32 and swaps to endianness specified by setEndian depending on platform + * and advances the current position * - * \sa Endian - * - * \return Int32 The value at the current address - * \throw IOException when address is out of range + * @return The value at the current address */ inline atInt32 readInt32() { @@ -207,6 +218,11 @@ public: inline atInt32 readVal(typename std::enable_if::value>::type* = 0) {return readInt32();} + /** @brief Reads a Int32 and swaps against little endianness depending on platform + * and advances the current position + * + * @return The value at the current address + */ inline atInt32 readInt32Little() { atInt32 val; @@ -217,6 +233,11 @@ public: inline atInt32 readValLittle(typename std::enable_if::value>::type* = 0) {return readInt32Little();} + /** @brief Reads a Int32 and swaps against big endianness depending on platform + * and advances the current position + * + * @return The value at the current address + */ inline atInt32 readInt32Big() { atInt32 val; @@ -227,13 +248,10 @@ public: inline atInt32 readValBig(typename std::enable_if::value>::type* = 0) {return readInt32Big();} - /*! \brief Reads a Uint32 and swaps to proper endianness depending on platform - * and Stream settings, and advances the current position + /** @brief Reads a Uint32 and swaps to endianness specified by setEndian depending on platform + * and advances the current position * - * \sa Endian - * - * \return Uint32 The value at the current address - * \throw IOException when address is out of range + * @return The value at the current address */ inline atUint32 readUint32() {return readInt32();} @@ -241,6 +259,11 @@ public: inline atUint32 readVal(typename std::enable_if::value>::type* = 0) {return readUint32();} + /** @brief Reads a Uint32 and swaps against little endianness depending on platform + * and advances the current position + * + * @return The value at the current address + */ inline atUint32 readUint32Little() { atUint32 val; @@ -251,6 +274,11 @@ public: inline atInt32 readValLittle(typename std::enable_if::value>::type* = 0) {return readUint32Little();} + /** @brief Reads a Uint32 and swaps against big endianness depending on platform + * and advances the current position + * + * @return The value at the current address + */ inline atUint32 readUint32Big() { atUint32 val; @@ -261,13 +289,10 @@ public: inline atUint32 readValBig(typename std::enable_if::value>::type* = 0) {return readUint32Big();} - /*! \brief Reads a Int64 and swaps to proper endianness depending on platform - * and Stream settings, and advances the current position + /** @brief Reads a Int64 and swaps to endianness specified by setEndian depending on platform + * and advances the current position * - * \sa Endian - * - * \return Int64 The value at the current address - * \throw IOException when address is out of range + * @return The value at the current address */ inline atInt64 readInt64() { @@ -279,6 +304,11 @@ public: inline atInt64 readVal(typename std::enable_if::value>::type* = 0) {return readInt64();} + /** @brief Reads a Int64 and swaps against little endianness depending on platform + * and advances the current position + * + * @return The value at the current address + */ inline atInt64 readInt64Little() { atInt64 val; @@ -289,6 +319,11 @@ public: inline atInt64 readValLittle(typename std::enable_if::value>::type* = 0) {return readInt64Little();} + /** @brief Reads a Int64 and swaps against big endianness depending on platform + * and advances the current position + * + * @return The value at the current address + */ inline atInt64 readInt64Big() { atInt64 val; @@ -299,13 +334,10 @@ public: inline atInt64 readValBig(typename std::enable_if::value>::type* = 0) {return readInt64Big();} - /*! \brief Reads a Uint64 and swaps to proper endianness depending on platform - * and Stream settings, and advances the current position + /** @brief Reads a Uint64 and swaps to endianness specified by setEndian depending on platform + * and advances the current position * - * \sa Endian - * - * \return Uint64 The value at the current address - * \throw IOException when address is out of range + * @return The value at the current address */ inline atUint64 readUint64() {return readInt64();} @@ -313,6 +345,11 @@ public: inline atUint64 readVal(typename std::enable_if::value>::type* = 0) {return readUint64();} + /** @brief Reads a Uint64 and swaps against little endianness depending on platform + * and advances the current position + * + * @return The value at the current address + */ inline atUint64 readUint64Little() { atUint64 val; @@ -323,6 +360,11 @@ public: inline atUint64 readValLittle(typename std::enable_if::value>::type* = 0) {return readUint64Little();} + /** @brief Reads a Uint64 and swaps against big endianness depending on platform + * and advances the current position + * + * @return The value at the current address + */ inline atUint64 readUint64Big() { atUint64 val; @@ -333,13 +375,10 @@ public: inline atUint64 readValBig(typename std::enable_if::value>::type* = 0) {return readUint64Big();} - /*! \brief Reads a float and swaps to proper endianness depending on platform - * and Stream settings, and advances the current position + /** @brief Reads a float and swaps to endianness specified by setEndian depending on platform + * and advances the current position * - * \sa Endian - * - * \return float The value at the current address - * \throw IOException when address is out of range + * @return The value at the current address */ inline float readFloat() { @@ -351,6 +390,11 @@ public: inline float readVal(typename std::enable_if::value>::type* = 0) {return readFloat();} + /** @brief Reads a float and swaps against little endianness depending on platform + * and advances the current position + * + * @return The value at the current address + */ inline float readFloatLittle() { float val; @@ -361,6 +405,11 @@ public: inline float readValLittle(typename std::enable_if::value>::type* = 0) {return readFloatLittle();} + /** @brief Reads a float and swaps against big endianness depending on platform + * and advances the current position + * + * @return The value at the current address + */ inline float readFloatBig() { float val; @@ -371,13 +420,10 @@ public: inline float readValBig(typename std::enable_if::value>::type* = 0) {return readFloatBig();} - /*! \brief Reads a double and swaps to proper endianness depending on platform - * and Stream settings, and advances the current position + /** @brief Reads a double and swaps to endianness specified by setEndian depending on platform + * and advances the current position * - * \sa Endian - * - * \return double The value at the current address - * \throw IOException when address is out of range + * @return The value at the current address */ inline double readDouble() { @@ -389,6 +435,11 @@ public: inline double readVal(typename std::enable_if::value>::type* = 0) {return readDouble();} + /** @brief Reads a double and swaps against little endianness depending on platform + * and advances the current position + * + * @return The value at the current address + */ inline double readDoubleLittle() { double val; @@ -399,6 +450,11 @@ public: inline double readValLittle(typename std::enable_if::value>::type* = 0) {return readDoubleLittle();} + /** @brief Reads a double and swaps against big endianness depending on platform + * and advances the current position + * + * @return The value at the current address + */ inline double readDoubleBig() { double val; @@ -409,10 +465,9 @@ public: inline double readValBig(typename std::enable_if::value>::type* = 0) {return readDoubleBig();} - /*! \brief Reads a bool and advances the current position + /** @brief Reads a bool and advances the current position * - * \return bool The value at the current address - * \throw IOException when address is out of range + * @return The value at the current address */ inline bool readBool() { @@ -424,10 +479,10 @@ public: inline bool readVal(typename std::enable_if::value>::type* = 0) {return readBool();} - /*! \brief Reads an atVec2f (8 bytes) and advances the current position + /** @brief Reads an atVec2f (8 bytes), swaps to endianness specified by setEndian depending on platform + * and advances the current position * - * \return atVec2f The value at the current address - * \throw IOException when address is out of range + * @return The value at the current address */ inline atVec2f readVec2f() { @@ -449,6 +504,11 @@ public: inline atVec2f readVal(typename std::enable_if::value>::type* = 0) {return readVec2f();} + /** @brief Reads an atVec2f (8 bytes), swaps against little endianness depending on platform + * and advances the current position + * + * @return The value at the current address + */ inline atVec2f readVec2fLittle() { atVec2f val; @@ -461,6 +521,11 @@ public: inline atVec2f readValLittle(typename std::enable_if::value>::type* = 0) {return readVec2fLittle();} + /** @brief Reads an atVec2f (8 bytes), swaps against big endianness depending on platform + * and advances the current position + * + * @return The value at the current address + */ inline atVec2f readVec2fBig() { atVec2f val; @@ -473,10 +538,10 @@ public: inline atVec2f readValBig(typename std::enable_if::value>::type* = 0) {return readVec2fBig();} - /*! \brief Reads an atVec3f (12 bytes) and advances the current position + /** @brief Reads an atVec3f (12 bytes), swaps to endianness specified by setEndian depending on platform + * and advances the current position * - * \return atVec3f The value at the current address - * \throw IOException when address is out of range + * @return The value at the current address */ inline atVec3f readVec3f() { @@ -500,6 +565,11 @@ public: inline atVec3f readVal(typename std::enable_if::value>::type* = 0) {return readVec3f();} + /** @brief Reads an atVec3f (12 bytes), swaps against little endianness depending on platform + * and advances the current position + * + * @return The value at the current address + */ inline atVec3f readVec3fLittle() { atVec3f val; @@ -513,6 +583,11 @@ public: inline atVec3f readValLittle(typename std::enable_if::value>::type* = 0) {return readVec3fLittle();} + /** @brief Reads an atVec3f (12 bytes), swaps against big endianness depending on platform + * and advances the current position + * + * @return The value at the current address + */ inline atVec3f readVec3fBig() { atVec3f val; @@ -526,10 +601,10 @@ public: inline atVec3f readValBig(typename std::enable_if::value>::type* = 0) {return readVec3fBig();} - /*! \brief Reads an atVec4f (16 bytes) and advances the current position + /** @brief Reads an atVec4f (16 bytes), swaps to endianness specified by setEndian depending on platform + * and advances the current position * - * \return atVec4f The value at the current address - * \throw IOException when address is out of range + * @return The value at the current address */ inline atVec4f readVec4f() { @@ -555,6 +630,11 @@ public: inline atVec4f readVal(typename std::enable_if::value>::type* = 0) {return readVec4f();} + /** @brief Reads an atVec4f (16 bytes), swaps against little endianness depending on platform + * and advances the current position + * + * @return The value at the current address + */ inline atVec4f readVec4fLittle() { atVec4f val; @@ -569,6 +649,11 @@ public: inline atVec4f readValLittle(typename std::enable_if::value>::type* = 0) {return readVec4fLittle();} + /** @brief Reads an atVec4f (16 bytes), swaps against big endianness depending on platform + * and advances the current position + * + * @return The value at the current address + */ inline atVec4f readVec4fBig() { atVec4f val; @@ -583,11 +668,11 @@ public: inline atVec4f readValBig(typename std::enable_if::value>::type* = 0) {return readVec4fBig();} - /*! \brief Reads a wide-char string, converts to UTF8 and advances the position in the file + /** @brief Reads a wide-char string (using endianness from setEndian), + * converts to UTF8 and advances the position in the file * - * \param fixedLen If non-negative, this is a fixed-length string read - * \return std::string The value at the current address - * \throw IOException when address is out of range + * @param fixedLen If non-negative, this is a fixed-length string read + * @return The read string */ inline std::string readWStringAsString(atInt32 fixedLen = -1) { @@ -621,6 +706,12 @@ public: return retval; } + /** @brief Reads a wide-char string (against little-endian), + * converts to UTF8 and advances the position in the file + * + * @param fixedLen If non-negative, this is a fixed-length string read + * @return The read string + */ inline std::string readWStringAsStringLittle(atInt32 fixedLen = -1) { std::string retval; @@ -653,6 +744,12 @@ public: return retval; } + /** @brief Reads a wide-char string (against big-endian), + * converts to UTF8 and advances the position in the file + * + * @param fixedLen If non-negative, this is a fixed-length string read + * @return The read string + */ inline std::string readWStringAsStringBig(atInt32 fixedLen = -1) { std::string retval; @@ -685,11 +782,10 @@ public: return retval; } - /*! \brief Reads a string and advances the position in the file + /** @brief Reads a string and advances the position in the file * - * \param fixedLen If non-negative, this is a fixed-length string read - * \return std::string The value at the current address - * \throw IOException when address is out of range + * @param fixedLen If non-negative, this is a fixed-length string read + * @return The read string */ inline std::string readString(atInt32 fixedLen = -1) { @@ -716,11 +812,10 @@ public: inline std::string readVal(typename std::enable_if::value>::type* = 0) {return readString();} - /*! \brief Reads a wstring and advances the position in the file + /** @brief Reads a wstring and advances the position in the file * - * \param fixedLen If non-negative, this is a fixed-length string read - * \return std::wstring The value at the current address - * \throw IOException when address is out of range + * @param fixedLen If non-negative, this is a fixed-length string read + * @return The read wstring */ inline std::wstring readWString(atInt32 fixedLen = -1) { @@ -747,6 +842,12 @@ public: inline std::wstring readVal(typename std::enable_if::value>::type* = 0) {return readWString();} + /** @brief Reads a wstring assuming little-endian characters + * and advances the position in the file + * + * @param fixedLen If non-negative, this is a fixed-length string read + * @return The read wstring + */ inline std::wstring readWStringLittle(atInt32 fixedLen = -1) { std::wstring ret; @@ -772,6 +873,12 @@ public: inline std::wstring readValLittle(typename std::enable_if::value>::type* = 0) {return readWStringLittle();} + /** @brief Reads a wstring assuming big-endian characters + * and advances the position in the file + * + * @param fixedLen If non-negative, this is a fixed-length string read + * @return The read wstring + */ inline std::wstring readWStringBig(atInt32 fixedLen = -1) { std::wstring ret; @@ -797,6 +904,13 @@ public: inline std::wstring readValBig(typename std::enable_if::value>::type* = 0) {return readWStringBig();} + /** @brief Performs automatic std::vector enumeration reads using numeric type T + * + * @param vector The std::vector to clear and populate using read data + * @param count The number of elements to read into vector + * + * Endianness is set with setEndian + */ template void enumerate(std::vector& vector, size_t count, typename std::enable_if::value || @@ -810,6 +924,13 @@ public: vector.emplace_back(readVal()); } + /** @brief Performs automatic std::vector enumeration reads using numeric type T + * + * @param vector The std::vector to clear and populate using read data + * @param count The number of elements to read into vector + * + * Endianness is little + */ template void enumerateLittle(std::vector& vector, size_t count, typename std::enable_if::value || @@ -823,6 +944,13 @@ public: vector.emplace_back(readValLittle()); } + /** @brief Performs automatic std::vector enumeration reads using numeric type T + * + * @param vector The std::vector to clear and populate using read data + * @param count The number of elements to read into vector + * + * Endianness is big + */ template void enumerateBig(std::vector& vector, size_t count, typename std::enable_if::value || @@ -836,6 +964,11 @@ public: vector.emplace_back(readValBig()); } + /** @brief Performs automatic std::vector enumeration reads using non-numeric type T + * + * @param vector The std::vector to clear and populate using read data + * @param count The number of elements to read into vector + */ template void enumerate(std::vector& vector, size_t count, typename std::enable_if::value && @@ -852,6 +985,13 @@ public: } } + /** @brief Performs lambda-assisted std::vector enumeration reads using type T + * + * @param vector The std::vector to clear and populate using read data + * @param count The number of elements to read into vector + * @param readf Function (e.g. a lambda) that reads *one* element and + * assigns the value through the second argument + */ template void enumerate(std::vector& vector, size_t count, std::function readf) { diff --git a/include/Athena/IStreamWriter.hpp b/include/Athena/IStreamWriter.hpp index 133c892..05e9bdf 100644 --- a/include/Athena/IStreamWriter.hpp +++ b/include/Athena/IStreamWriter.hpp @@ -12,97 +12,95 @@ class IStreamWriter : public IStream { public: virtual ~IStreamWriter() {} - /*! \brief Sets the Endianness of the stream + /** @brief Sets the Endianness of the stream * - * \param endian The Endianness to set \sa Endian + * @param endian The Endianness to set */ inline void setEndian(Endian endian) {m_endian = endian;} - /*! \brief Returns the current Endianness of the stream + /** @brief Returns the current Endianness of the stream * - * \return Endian The current Stream Endianness + * @return The current Stream Endianness */ inline Endian endian() const {return m_endian;} - /*! \brief Returns whether the stream is BigEndian + /** @brief Returns whether the stream is BigEndian * - * \return bool True for BigEndian; False for LittleEndian + * @return True for BigEndian; False for LittleEndian */ inline bool isBigEndian() const {return (m_endian == Endian::BigEndian);} - /*! \brief Returns whether the stream is LittleEndian + /** @brief Returns whether the stream is LittleEndian * - * \return bool True for LittleEndian; False for BigEndian + * @return True for LittleEndian; False for BigEndian */ inline bool isLittleEndian() const {return (m_endian == Endian::LittleEndian);} - /*! \brief Sets the buffers position relative to the specified position.
+ /** @brief Sets the buffers position relative to the specified position.
* It seeks relative to the current position by default. - * \param position where in the buffer to seek - * \param origin The Origin to seek \sa SeekOrigin + * @param position where in the buffer to seek + * @param origin The location to seek relative to */ virtual void seek(atInt64 pos, SeekOrigin origin = SeekOrigin::Current)=0; - /*! \brief Sets the buffers position relative to the next 32-byte aligned position.
+ /** @brief Sets the buffers position relative to the next 32-byte aligned position.
*/ inline void seekAlign32() {seek(ROUND_UP_32(position()), SeekOrigin::Begin);} - /*! \brief Returns whether or not the stream is at the end. + /** @brief Returns whether or not the stream is at the end. * - * \return bool True if at end; False otherwise. + * @return True if at end; False otherwise. */ inline bool atEnd() const {return position() >= length();} - /*! \brief Returns the current position in the stream. + /** @brief Returns the current position in the stream. * - * \return Int64 The current position in the stream. + * @return The current position in the stream. */ virtual atUint64 position() const=0; - /*! \brief Returns whether or not the stream is at the end. + /** @brief Returns whether or not the stream is at the end. * - * \return bool True if at end; False otherwise. + * @return True if at end; False otherwise. */ virtual atUint64 length() const=0; - /*! \brief Writes a byte at the current position and advances the position by one byte. - * \param byte The value to write + /** @brief Writes a byte at the current position and advances the position by one byte. + * @param val The value to write */ inline void writeUByte(atUint8 val) {writeUBytes(&val, 1);} inline void writeVal(atUint8 val) {return writeUByte(val);} - /*! \brief Writes a byte at the current position and advances the position by one byte. - * \param byte The value to write - * \throw IOException + /** @brief Writes a byte at the current position and advances the position by one byte. + * @param val The value to write */ inline void writeByte(atInt8 val) {writeUByte(val);} inline void writeVal(atInt8 val) {return writeByte(val);} - /*! \brief Writes the given buffer with the specified length, buffers can be bigger than the length + /** @brief Writes the given buffer with the specified length, buffers can be bigger than the length * however it's undefined behavior to try and write a buffer which is smaller than the given length. * - * \param data The buffer to write - * \param length The amount to write + * @param data The buffer to write + * @param length The amount to write */ virtual void writeUBytes(const atUint8* data, atUint64 len)=0; - /*! \brief Writes the given buffer with the specified length, buffers can be bigger than the length + /** @brief Writes the given buffer with the specified length, buffers can be bigger than the length * however it's undefined behavior to try and write a buffer which is smaller than the given length. * - * \param data The buffer to write - * \param length The amount to write + * @param data The buffer to write + * @param length The amount to write */ inline void writeBytes(const atInt8* data, atUint64 len) {writeUBytes((atUint8*)data, len);} - /*! \brief Writes an Int16 to the buffer and advances the buffer. + /** @brief Writes an Int16 to the buffer and advances the buffer. * It also swaps the bytes depending on the platform and Stream settings. * - * \sa Endian - * \param val The value to write to the buffer + * @param val The value to write to the buffer */ inline void writeInt16(atInt16 val) { @@ -114,6 +112,11 @@ public: } inline void writeVal(atInt16 val) {return writeInt16(val);} + /** @brief Writes an Int16 to the buffer and advances the buffer. + * It also swaps the bytes against little depending on the platform. + * + * @param val The value to write to the buffer + */ inline void writeInt16Little(atInt16 val) { utility::LittleInt16(val); @@ -121,6 +124,11 @@ public: } inline void writeValLittle(atInt16 val) {return writeInt16Little(val);} + /** @brief Writes an Int16 to the buffer and advances the buffer. + * It also swaps the bytes against big depending on the platform. + * + * @param val The value to write to the buffer + */ inline void writeInt16Big(atInt16 val) { utility::BigInt16(val); @@ -128,26 +136,34 @@ public: } inline void writeValBig(atInt16 val) {return writeInt16Big(val);} - /*! \brief Writes an Uint16 to the buffer and advances the buffer. + /** @brief Writes an Uint16 to the buffer and advances the buffer. * It also swaps the bytes depending on the platform and Stream settings * - * \sa Endian - * \param val The value to write to the buffer + * @param val The value to write to the buffer */ inline void writeUint16(atUint16 val) {writeInt16(val);} inline void writeVal(atUint16 val) {return writeUint16(val);} + /** @brief Writes an Uint16 to the buffer and advances the buffer. + * It also swaps the bytes against little depending on the platform + * + * @param val The value to write to the buffer + */ inline void writeUint16Little(atUint16 val) {writeInt16Little(val);} inline void writeValLittle(atUint16 val) {return writeUint16Little(val);} + /** @brief Writes an Uint16 to the buffer and advances the buffer. + * It also swaps the bytes against big depending on the platform + * + * @param val The value to write to the buffer + */ inline void writeUint16Big(atUint16 val) {writeInt16Big(val);} inline void writeValBig(atUint16 val) {return writeUint16Big(val);} - /*! \brief Writes an Int32 to the buffer and advances the buffer. + /** @brief Writes an Int32 to the buffer and advances the buffer. * It also swaps the bytes depending on the platform and Stream settings. * - * \sa Endian - * \param val The value to write to the buffer + * @param val The value to write to the buffer */ inline void writeInt32(atInt32 val) { @@ -159,6 +175,11 @@ public: } inline void writeVal(atInt32 val) {return writeInt32(val);} + /** @brief Writes an Int32 to the buffer and advances the buffer. + * It also swaps the bytes against little depending on the platform. + * + * @param val The value to write to the buffer + */ inline void writeInt32Little(atInt32 val) { utility::LittleInt32(val); @@ -166,6 +187,11 @@ public: } inline void writeValLittle(atInt32 val) {return writeInt32Little(val);} + /** @brief Writes an Int32 to the buffer and advances the buffer. + * It also swaps the bytes against big depending on the platform. + * + * @param val The value to write to the buffer + */ inline void writeInt32Big(atInt32 val) { utility::BigInt32(val); @@ -173,26 +199,34 @@ public: } inline void writeValBig(atInt32 val) {return writeInt32Big(val);} - /*! \brief Writes an Uint32 to the buffer and advances the buffer. + /** @brief Writes an Uint32 to the buffer and advances the buffer. * It also swaps the bytes depending on the platform and Stream settings. * - * \sa Endian - * \param val The value to write to the buffer + * @param val The value to write to the buffer */ inline void writeUint32(atUint32 val) {writeInt32(val);} inline void writeVal(atUint32 val) {return writeUint32(val);} + /** @brief Writes an Uint32 to the buffer and advances the buffer. + * It also swaps the bytes against little depending on the platform. + * + * @param val The value to write to the buffer + */ inline void writeUint32Little(atUint32 val) {writeInt32Little(val);} inline void writeValLittle(atUint32 val) {return writeUint32Little(val);} + /** @brief Writes an Uint32 to the buffer and advances the buffer. + * It also swaps the bytes against big depending on the platform. + * + * @param val The value to write to the buffer + */ inline void writeUint32Big(atUint32 val) {writeInt32Big(val);} inline void writeValBig(atUint32 val) {return writeUint32Big(val);} - /*! \brief Writes an Int64 to the buffer and advances the buffer. + /** @brief Writes an Int64 to the buffer and advances the buffer. * It also swaps the bytes depending on the platform and Stream settings. * - * \sa Endian - * \param val The value to write to the buffer + * @param val The value to write to the buffer */ inline void writeInt64(atInt64 val) { @@ -204,6 +238,11 @@ public: } inline void writeVal(atInt64 val) {return writeInt64(val);} + /** @brief Writes an Int64 to the buffer and advances the buffer. + * It also swaps the bytes against little depending on the platform. + * + * @param val The value to write to the buffer + */ inline void writeInt64Little(atInt64 val) { utility::LittleInt64(val); @@ -211,6 +250,11 @@ public: } inline void writeValLittle(atInt64 val) {return writeInt64Little(val);} + /** @brief Writes an Int64 to the buffer and advances the buffer. + * It also swaps the bytes against big depending on the platform. + * + * @param val The value to write to the buffer + */ inline void writeInt64Big(atInt64 val) { utility::BigInt64(val); @@ -218,26 +262,34 @@ public: } inline void writeValBig(atInt64 val) {return writeInt64Big(val);} - /*! \brief Writes an Uint64 to the buffer and advances the buffer. + /** @brief Writes an Uint64 to the buffer and advances the buffer. * It also swaps the bytes depending on the platform and Stream settings. * - * \sa Endian - * \param val The value to write to the buffer + * @param val The value to write to the buffer */ inline void writeUint64(atUint64 val) {writeInt64(val);} inline void writeVal(atUint64 val) {return writeUint64(val);} + /** @brief Writes an Uint64 to the buffer and advances the buffer. + * It also swaps the bytes against little depending on the platform. + * + * @param val The value to write to the buffer + */ inline void writeUint64Little(atUint64 val) {writeInt64Little(val);} inline void writeValLittle(atUint64 val) {return writeUint64Little(val);} + /** @brief Writes an Uint64 to the buffer and advances the buffer. + * It also swaps the bytes against big depending on the platform. + * + * @param val The value to write to the buffer + */ inline void writeUint64Big(atUint64 val) {writeInt64Big(val);} inline void writeValBig(atUint64 val) {return writeUint64Big(val);} - /*! \brief Writes an float to the buffer and advances the buffer. + /** @brief Writes an float to the buffer and advances the buffer. * It also swaps the bytes depending on the platform and Stream settings. * - * \sa Endian - * \param val The value to write to the buffer + * @param val The value to write to the buffer */ inline void writeFloat(float val) { @@ -249,6 +301,11 @@ public: } inline void writeVal(float val) {return writeFloat(val);} + /** @brief Writes an float to the buffer and advances the buffer. + * It also swaps the bytes against little depending on the platform. + * + * @param val The value to write to the buffer + */ inline void writeFloatLittle(float val) { utility::LittleFloat(val); @@ -256,6 +313,11 @@ public: } inline void writeValLittle(float val) {return writeFloatLittle(val);} + /** @brief Writes an float to the buffer and advances the buffer. + * It also swaps the bytes against big depending on the platform. + * + * @param val The value to write to the buffer + */ inline void writeFloatBig(float val) { utility::BigFloat(val); @@ -263,11 +325,10 @@ public: } inline void writeValBig(float val) {return writeFloatBig(val);} - /*! \brief Writes an double to the buffer and advances the buffer. + /** @brief Writes an double to the buffer and advances the buffer. * It also swaps the bytes depending on the platform and Stream settings. * - * \sa Endian - * \param val The value to write to the buffer + * @param val The value to write to the buffer */ inline void writeDouble(double val) { @@ -279,6 +340,11 @@ public: } inline void writeVal(double val) {return writeDouble(val);} + /** @brief Writes an double to the buffer and advances the buffer. + * It also swaps the bytes against little depending on the platform. + * + * @param val The value to write to the buffer + */ inline void writeDoubleLittle(double val) { utility::LittleDouble(val); @@ -286,6 +352,11 @@ public: } inline void writeValLittle(double val) {return writeDoubleLittle(val);} + /** @brief Writes an double to the buffer and advances the buffer. + * It also swaps the bytes against big depending on the platform. + * + * @param val The value to write to the buffer + */ inline void writeDoubleBig(double val) { utility::BigDouble(val); @@ -293,20 +364,18 @@ public: } inline void writeValBig(double val) {return writeDoubleBig(val);} - /*! \brief Writes an bool to the buffer and advances the buffer. + /** @brief Writes an bool to the buffer and advances the buffer. * It also swaps the bytes depending on the platform and Stream settings. * - * \sa Endian - * \param val The value to write to the buffer + * @param val The value to write to the buffer */ inline void writeBool(bool val) {writeUBytes((atUint8*)&val, 1);} inline void writeVal(bool val) {return writeBool(val);} - /*! \brief Writes an atVec2f (8 bytes) to the buffer and advances the buffer. + /** @brief Writes an atVec2f (8 bytes) to the buffer and advances the buffer. * It also swaps the bytes depending on the platform and Stream settings. * - * \sa Endian - * \param vec The value to write to the buffer + * @param vec The value to write to the buffer */ inline void writeVec2f(atVec2f vec) { @@ -324,6 +393,11 @@ public: } inline void writeVal(atVec2f val) {return writeVec2f(val);} + /** @brief Writes an atVec2f (8 bytes) to the buffer and advances the buffer. + * It also swaps the bytes against little depending on the platform. + * + * @param vec The value to write to the buffer + */ inline void writeVec2fLittle(atVec2f vec) { utility::LittleFloat(vec.vec[0]); @@ -332,6 +406,11 @@ public: } inline void writeValLittle(atVec2f val) {return writeVec2fLittle(val);} + /** @brief Writes an atVec2f (8 bytes) to the buffer and advances the buffer. + * It also swaps the bytes against big depending on the platform. + * + * @param vec The value to write to the buffer + */ inline void writeVec2fBig(atVec2f vec) { utility::BigFloat(vec.vec[0]); @@ -340,11 +419,10 @@ public: } inline void writeValBig(atVec2f val) {return writeVec2fBig(val);} - /*! \brief Writes an atVec3f (12 bytes) to the buffer and advances the buffer. + /** @brief Writes an atVec3f (12 bytes) to the buffer and advances the buffer. * It also swaps the bytes depending on the platform and Stream settings. * - * \sa Endian - * \param vec The value to write to the buffer + * @param vec The value to write to the buffer */ inline void writeVec3f(atVec3f vec) { @@ -364,6 +442,11 @@ public: } inline void writeVal(atVec3f val) {return writeVec3f(val);} + /** @brief Writes an atVec3f (12 bytes) to the buffer and advances the buffer. + * It also swaps the bytes against little depending on the platform. + * + * @param vec The value to write to the buffer + */ inline void writeVec3fLittle(atVec3f vec) { utility::LittleFloat(vec.vec[0]); @@ -373,6 +456,11 @@ public: } inline void writeValLittle(atVec3f val) {return writeVec3fLittle(val);} + /** @brief Writes an atVec3f (12 bytes) to the buffer and advances the buffer. + * It also swaps the bytes against big depending on the platform. + * + * @param vec The value to write to the buffer + */ inline void writeVec3fBig(atVec3f vec) { utility::BigFloat(vec.vec[0]); @@ -382,11 +470,10 @@ public: } inline void writeValBig(atVec3f val) {return writeVec3fBig(val);} - /*! \brief Writes an atVec4f (16 bytes) to the buffer and advances the buffer. + /** @brief Writes an atVec4f (16 bytes) to the buffer and advances the buffer. * It also swaps the bytes depending on the platform and Stream settings. * - * \sa Endian - * \param vec The value to write to the buffer + * @param vec The value to write to the buffer */ inline void writeVec4f(atVec4f vec) { @@ -408,6 +495,11 @@ public: } inline void writeVal(atVec4f val) {return writeVec4f(val);} + /** @brief Writes an atVec4f (16 bytes) to the buffer and advances the buffer. + * It also swaps the bytes against little depending on the platform. + * + * @param vec The value to write to the buffer + */ inline void writeVec4fLittle(atVec4f vec) { utility::LittleFloat(vec.vec[0]); @@ -418,6 +510,11 @@ public: } inline void writeValLittle(atVec4f val) {return writeVec4fLittle(val);} + /** @brief Writes an atVec4f (16 bytes) to the buffer and advances the buffer. + * It also swaps the bytes against big depending on the platform. + * + * @param vec The value to write to the buffer + */ inline void writeVec4fBig(atVec4f vec) { utility::BigFloat(vec.vec[0]); @@ -428,12 +525,13 @@ public: } inline void writeValBig(atVec4f val) {return writeVec4fBig(val);} - /*! \brief Converts a UTF8 string to a wide-char string in the buffer and advances the buffer. + /** @brief Converts a UTF8 string to a wide-char string in the buffer and advances the buffer. * It also swaps the bytes depending on the platform and Stream settings. * - * \sa Endian - * \param str The string to write to the buffer - * \param fixedLen If not -1, the number of characters to zero-fill string to + * @param str The string to write to the buffer + * @param fixedLen If not -1, the number of characters to zero-fill string to + * + * Endianness is set with setEndian */ inline void writeStringAsWString(const std::string& str, atInt32 fixedLen = -1) { @@ -483,6 +581,14 @@ public: } } + /** @brief Converts a UTF8 string to a wide-char string in the buffer and advances the buffer. + * It also swaps the bytes depending on the platform and Stream settings. + * + * @param str The string to write to the buffer + * @param fixedLen If not -1, the number of characters to zero-fill string to + * + * Endianness is little + */ inline void writeStringAsWStringLittle(const std::string& str, atInt32 fixedLen = -1) { std::string tmpStr = "\xEF\xBB\xBF" + str; @@ -531,6 +637,14 @@ public: } } + /** @brief Converts a UTF8 string to a wide-char string in the buffer and advances the buffer. + * It also swaps the bytes depending on the platform and Stream settings. + * + * @param str The string to write to the buffer + * @param fixedLen If not -1, the number of characters to zero-fill string to + * + * Endianness is big + */ inline void writeStringAsWStringBig(const std::string& str, atInt32 fixedLen = -1) { std::string tmpStr = "\xEF\xBB\xBF" + str; @@ -579,11 +693,10 @@ public: } } - /*! \brief Writes an string to the buffer and advances the buffer. + /** @brief Writes an string to the buffer and advances the buffer. * - * \sa Endian - * \param str The string to write to the buffer - * \param fixedLen If not -1, the number of characters to zero-fill string to + * @param str The string to write to the buffer + * @param fixedLen If not -1, the number of characters to zero-fill string to */ inline void writeString(const std::string& str, atInt32 fixedLen = -1) { @@ -614,11 +727,12 @@ public: } inline void writeVal(const std::string& val) {return writeString(val);} - /*! \brief Writes an wstring to the buffer and advances the buffer. + /** @brief Writes an wstring to the buffer and advances the buffer. * - * \sa Endian - * \param str The string to write to the buffer - * \param fixedLen If not -1, the number of characters to zero-fill string to + * @param str The string to write to the buffer + * @param fixedLen If not -1, the number of characters to zero-fill string to + * + * Endianness is set with setEndian */ inline void writeWString(const std::wstring& str, atInt32 fixedLen = -1) { @@ -649,6 +763,13 @@ public: } inline void writeVal(const std::wstring& val) {return writeWString(val);} + /** @brief Writes an wstring to the buffer and advances the buffer. + * + * @param str The string to write to the buffer + * @param fixedLen If not -1, the number of characters to zero-fill string to + * + * Endianness is little + */ inline void writeWStringLittle(const std::wstring& str, atInt32 fixedLen = -1) { if (fixedLen < 0) @@ -678,6 +799,13 @@ public: } inline void writeValLittle(const std::wstring& val) {return writeWStringLittle(val);} + /** @brief Writes an wstring to the buffer and advances the buffer. + * + * @param str The string to write to the buffer + * @param fixedLen If not -1, the number of characters to zero-fill string to + * + * Endianness is big + */ inline void writeWStringBig(const std::wstring& str, atInt32 fixedLen = -1) { if (fixedLen < 0) @@ -712,6 +840,11 @@ public: inline void fill(atInt8 val, atUint64 length) {fill((atUint8)val, length);} + /** @brief Performs automatic std::vector enumeration writes using numeric type T + * @param vector The std::vector read from when writing data + * + * Endianness is set with setEndian + */ template void enumerate(const std::vector& vector, typename std::enable_if::value || @@ -723,6 +856,11 @@ public: writeVal(item); } + /** @brief Performs automatic std::vector enumeration writes using numeric type T + * @param vector The std::vector read from when writing data + * + * Endianness is little + */ template void enumerateLittle(const std::vector& vector, typename std::enable_if::value || @@ -734,6 +872,11 @@ public: writeValLittle(item); } + /** @brief Performs automatic std::vector enumeration writes using numeric type T + * @param vector The std::vector read from when writing data + * + * Endianness is big + */ template void enumerateBig(const std::vector& vector, typename std::enable_if::value || @@ -745,6 +888,9 @@ public: writeValBig(item); } + /** @brief Performs automatic std::vector enumeration writes using non-numeric type T + * @param vector The std::vector read from when writing data + */ template void enumerate(const std::vector& vector, typename std::enable_if::value &&