SequenceBuilders.hpp

/*
(c) Copyright, Real-Time Innovations, 2018-2024.
All rights reserved.
 
No duplications, whole or partial, manual or electronic, may be made
without express written permission.  Any such copies, or
revisions thereof, must display this notice unaltered.
This code contains trade secrets of Real-Time Innovations, Inc.
*/
 
#ifndef RTI_DDS_FLAT_SEQUENCEBUILDERS_HPP_
#define RTI_DDS_FLAT_SEQUENCEBUILDERS_HPP_
 
#include "rti/flat/Builder.hpp"
 
//
// Builders for sequences, strings, and arrays.
//
// Type hierarchy (- indicates an abstract builder; * a concrete, usable builder)
//
// - AbstractListBuilder
//     * MutableArrayBuilder
//     - AbstractSequenceBuilder 
//         * MutableSequenceBuilder
//         * FinalSequenceBuilder
//         * PrimitiveSequenceBuilder
//             * StringBuilder
//
// Notes: 
//   - there's no "FinalArrayBuilder" because that's a fixed-size type and
//     doesn't need a builder (it's constructed via an "add" operation, not a "build"
//     operation).
//   - MutableSequenceBuilder "builds" its elements
//   - FinalSequenceBuilder "adds" its elements
//
 
namespace rti { namespace flat {
 
namespace detail {
 
template <bool IsForEnum>
struct DHeaderGeneratorImpl {
    static bool reserve_dheader(rti::xcdr::Stream& stream)
    {
        if (collection_dheader_traits<IsForEnum>::dheader_required()) {
            return stream.serialize_dheader() != NULL;
        } else {
            return true;
        }
    }
 
    static bool finish_dheader(
            rti::xcdr::Stream& stream,
            unsigned char *dheader_position)
    {
        if (collection_dheader_traits<IsForEnum>::dheader_required()) {
            return stream.finish_dheader((char *) dheader_position);
        } else {
            return true;
        }
    }
 
    static bool move_after_dheader(
            rti::xcdr::Stream& stream,
            unsigned char *begin_position)
    {
        stream.current_position(begin_position);
 
        if (collection_dheader_traits<IsForEnum>::dheader_required()) {
            return stream.skip(RTI_XCDR_DHEADER_SIZE);
        } else {
            return true;
        }
    }
};
 
struct NoDHeaderGenerator {
    static bool reserve_dheader(rti::xcdr::Stream&)
    {
        return true;
    }
 
    static bool finish_dheader(rti::xcdr::Stream&, unsigned char *)
    {
        return true;
    }
 
    static bool move_after_dheader(
            rti::xcdr::Stream& stream,
            unsigned char *begin_position)
    {
        stream.current_position(begin_position);
        return true;
    }
};
 
typedef DHeaderGeneratorImpl<false> DHeaderGenerator;
typedef DHeaderGeneratorImpl<true> DHeaderGeneratorForEnum;
 
// Maybe specialized for enums to select DHeaderGenerator
template <typename T, typename Enable = void>
struct primitive_sequence_dheader_gen {
    typedef NoDHeaderGenerator type;
};
 
} // namespace detail
 
/*i
    * Extends and specializes AbstractBuilder to add or override the
    * functionality required to build a collection of consecutive elements
    * (sequence or array):
    *
    * - Add or build elements
    * - Keep track of the element count
    * - Handle element alignment
    *
    */
template <typename DHeaderGen>
class AbstractListBuilder : public AbstractBuilder {
protected:
    AbstractListBuilder() : element_count_(0)
    { }
 
    AbstractListBuilder(
            nested_tag_t,
            AbstractBuilder& parent,
            unsigned int alignment)
            : AbstractBuilder(nested_tag_t(), parent, alignment),
                element_count_(0)
    {
        DHeaderGen::reserve_dheader(stream());
    }
 
    template <typename ElementBuilder>
    ElementBuilder build_next()
    {
        rti::xcdr::Stream::Memento stream_memento(stream());
        return build_element<ElementBuilder>(stream_memento);
    }
 
    template <typename ElementOffset>
    ElementOffset add_next()
    {
        RTI_FLAT_BUILDER_CHECK_VALID(return ElementOffset());
 
        // save state in case of error
        rti::xcdr::Stream::Memento stream_memento(stream());
 
        if (!stream().align(ElementOffset::required_alignment)) {
            RTI_FLAT_BUILDER_OUT_OF_RESOURCES_ERROR(return ElementOffset());
        }
 
        ElementOffset element = add_element<ElementOffset>();
        if (element.is_null()) {
            return ElementOffset();
        }
 
        // Success: clear memento, increment element count
        stream_memento.discard();
        element_count_++;
 
        return element;
    }
 
    template <typename ElementOffset>
    void add_n(unsigned int count)
    {
        RTI_FLAT_BUILDER_CHECK_VALID(return);
 
        if (count == 0) {
            return;
        }
 
        if (!stream().align(ElementOffset::required_alignment)) {
            RTI_FLAT_BUILDER_OUT_OF_RESOURCES_ERROR(return);
        }
 
        offset_t elements_size = ElementOffset::serialized_size(0)
                + ElementOffset::serialized_size_w_padding() * (count - 1);
        if (!stream().skip(elements_size)) {
            RTI_FLAT_BUILDER_OUT_OF_RESOURCES_ERROR(return);
        }
 
        element_count_ += count;
    }
 
    unsigned int element_count() const
    {
        return element_count_;
    }
 
#if defined(RTI_FLAT_DATA_CXX11_RVALUE_REFERENCES)
    AbstractListBuilder(AbstractListBuilder&& other) = default;
    AbstractListBuilder& operator=(AbstractListBuilder&& other)
    {
        if (this == &other) {
            return *this;
        }
 
        finish_untyped_impl();
 
        AbstractBuilder::operator=(static_cast<AbstractBuilder&&>(other));
 
        element_count_ = other.element_count_;
        other.element_count_ = 0;
 
        return *this;
    }
  #else
public:
    // Enables the safe-move-constructor idiom without C++11 move constructors
    struct AbstractListBuilderMoveProxy : AbstractBuilderMoveProxy {
        unsigned int element_count_;
    };
 
    operator AbstractListBuilderMoveProxy () throw() // move-constructor idiom
    {
        AbstractListBuilderMoveProxy other;
        move_to(other);
        return other;
    } 
 
protected:
    void move_from(AbstractListBuilderMoveProxy& other)
    {
        AbstractBuilder::move_from(other);
        element_count_ = other.element_count_;
    }
 
    void move_to(AbstractListBuilderMoveProxy& other)
    {
        AbstractBuilder::move_to(other);
        other.element_count_ = element_count_;
    }
 
#endif
 
private:
    friend class AbstractBuilder;
 
    virtual void finish_member() // override
    {
        RTI_FLAT_BUILDER_CHECK_VALID(return);
 
        // Increment element count after the nested element  builder finishes,
        // instead of on build_next(). This makes it easier to roll back the
        // state if the element building doesn't complete.
        element_count_++;
        AbstractBuilder::finish_member();
    }
 
protected:
    bool finish_dheader()
    {
        return DHeaderGen::finish_dheader(stream(), begin_position());
    }
 
    unsigned int element_count_;
};
 
// --- Array: -----------------------------------------------------------------
//
// (Note: there is no FinalArrayBuilder, because a final array's size is fixed,
// and is handled directly returning its offset with add_*; on the other hand,
// sequences are never fixed-size.)
 
template <typename ElementBuilder, unsigned int N>
class MutableArrayBuilder : public AbstractListBuilder<detail::DHeaderGenerator> {
public:
    typedef MutableArrayOffset<typename ElementBuilder::Offset, N> Offset;
    typedef AbstractListBuilder<detail::DHeaderGenerator> Base;
 
    MutableArrayBuilder()
    { }
 
    // The destructor does the same as finish_impl() but doesn't need to return
    // an Offset
    ~MutableArrayBuilder()
    {
        finish_untyped_impl();
    }
 
#if defined(RTI_FLAT_DATA_CXX11_RVALUE_REFERENCES)
    MutableArrayBuilder(MutableArrayBuilder&& other) = default;
 
    MutableArrayBuilder& operator=(MutableArrayBuilder&& other)
    {
        finish_untyped_impl();
        Base::operator=(static_cast<Base&&>(other));
 
        return *this;
    }
#endif
 
    void finish_untyped_impl()
    {
        if (!Base::is_valid() || !Base::is_nested()) {
            return;
        }
 
        Base::finish_dheader();
        Base::finish_untyped_impl();
    }
 
private:
    friend class AbstractBuilder; // to allow access to the constructor
 
    MutableArrayBuilder(
            nested_tag_t, 
            AbstractBuilder& parent,
            unsigned int alignment = 0)
        : AbstractListBuilder(nested_tag_t(), parent, alignment)
    {
    }
 
public:
    ElementBuilder build_next()
    {
        if (element_count() == N) {
            RTI_FLAT_BUILDER_PRECONDITION_ERROR(
                "Array builder build_next: too many elements",
                return ElementBuilder());
        }
 
        return AbstractListBuilder::build_next<ElementBuilder>();
    }
 
    Offset finish()
    {
        RTI_FLAT_BUILDER_CHECK_CAN_FINISH(return Offset());
        
        if (element_count() != N) {
            RTI_FLAT_BUILDER_PRECONDITION_ERROR(
                "Cannot finish array builder: too few elements",
                return Offset());                     
        }
 
        if (!finish_dheader()) {
            RTI_FLAT_BUILDER_OUT_OF_RESOURCES_ERROR(return Offset());
        }
 
        return finish_impl<Offset>();
    }
 
    RTI_FLAT_BUILDER_DEFINE_MOVE_OPERATIONS_IMPL(\
            MutableArrayBuilder, AbstractListBuilder, AbstractListBuilderMoveProxy)
    
};
 
// --- Sequences: -------------------------------------------------------------
 
// Specializes AbstractListBuilder to handle the length header serialization
// common to all sequences (which arrays don't have)
template <typename DHeaderGen>
class AbstractSequenceBuilder : public AbstractListBuilder<DHeaderGen> {
public:
    typedef AbstractListBuilder<DHeaderGen> Base;
    using Base::element_count;
    using Base::is_nested;
    using Base::is_valid;
    using Base::stream;
    using typename Base::nested_tag_t;
  #if !defined(RTI_FLAT_DATA_CXX11_RVALUE_REFERENCES)
    using typename Base::AbstractListBuilderMoveProxy;
  #endif
 
protected:
 
    AbstractSequenceBuilder()
    {
    }
 
    AbstractSequenceBuilder(
            nested_tag_t,
            AbstractBuilder& parent,
            unsigned int alignment)
            : Base(nested_tag_t(), parent, alignment)
    {
        // leave space for sequence length
        if (!stream().check_size(sizeof(rti::xcdr::length_t))) {
            RTI_FLAT_BUILDER_OUT_OF_RESOURCES_ERROR(this->invalidate());
        } else {
            // No need to align; the base constructor already aligned to 4 the
            // begin_position
            stream().template serialize_fast<rti::xcdr::length_t>(0);
        }
    }
 
    // The destructor does the same as finish_impl() but doesn't need to return
    // an Offset
    ~AbstractSequenceBuilder()
    {
        finish_untyped_impl();
    }
 
#if defined(RTI_FLAT_DATA_CXX11_RVALUE_REFERENCES)
    AbstractSequenceBuilder(AbstractSequenceBuilder&& other) = default;
    AbstractSequenceBuilder& operator=(AbstractSequenceBuilder&& other)
    {
        finish_untyped_impl();
        Base::operator=(static_cast<Base&&>(other));
 
        return *this;
    }
#endif
 
    void finish_untyped_impl()
    {
        if (!Base::is_valid() || !Base::is_nested()) {
            return;
        }
 
        Base::finish_dheader();
        finish_length();
        Base::finish_untyped_impl();
    }
 
    // Concrete sequences must call this method in their own finish() function
    template <typename Offset>
    Offset finish_impl()
    {
        RTI_FLAT_BUILDER_CHECK_VALID(return Offset());
        RTI_FLAT_BUILDER_CHECK_CAN_FINISH(return Offset());
 
        Base::finish_dheader();
        finish_length(); // serialize the length header
        return Base::template finish_impl<Offset>();
    }
 
private:
    // Serializes the sequence length when finishing the builder.
    void finish_length()
    {
        rti::xcdr::Stream::Memento stream_memento(stream());
        DHeaderGen::move_after_dheader(stream(), Base::begin_position());
 
        // Coverity found examples where element_count() is checked, but
        // that's only done in Array builders, which are unrelated to this
        // class, AbstractSequenceBuilder.
        // coverity[CHECKED_RETURN : FALSE]
        stream().template serialize_fast<rti::xcdr::length_t>(element_count());
    }
};
 
template <typename ElementBuilder>
class MutableSequenceBuilder
        : public AbstractSequenceBuilder<detail::DHeaderGenerator> {
public:
    typedef SequenceOffset<typename ElementBuilder::Offset> Offset;
 
    MutableSequenceBuilder()
    {
    }
 
private:
    typedef AbstractSequenceBuilder<detail::DHeaderGenerator> Base;
 
    friend class AbstractBuilder; // to allow access to the constructor
 
    MutableSequenceBuilder(
            nested_tag_t, 
            AbstractBuilder& parent,
            unsigned int alignment = RTI_XCDR_DHEADER_ALIGNMENT)
        : Base(nested_tag_t(), parent, alignment)
    {
    }
 
public:
    ElementBuilder build_next()
    {
        return AbstractListBuilder::build_next<ElementBuilder>();
    }
 
    Offset finish()
    {
        return finish_impl<Offset>();
    }
 
    RTI_FLAT_BUILDER_DEFINE_MOVE_OPERATIONS_IMPL(
            MutableSequenceBuilder,
            Base,
            AbstractListBuilderMoveProxy)
};
 
template <typename ElementOffset>
class FinalSequenceBuilder
        : public AbstractSequenceBuilder<detail::DHeaderGenerator> {
public:
    typedef SequenceOffset<ElementOffset> Offset;
 
    FinalSequenceBuilder()
    {
    }
 
private:
    friend class AbstractBuilder; // to allow access to the constructor
 
    FinalSequenceBuilder(
            nested_tag_t, 
            AbstractBuilder& parent,
            unsigned int alignment = RTI_XCDR_SEQ_LENGTH_ALIGNMENT)
        : AbstractSequenceBuilder(nested_tag_t(), parent, alignment)
    {
    }
 
public:
    ElementOffset add_next()
    {
        return AbstractListBuilder::add_next<ElementOffset>();
    }
 
    FinalSequenceBuilder& add_n(unsigned int count)
    {
        AbstractListBuilder::add_n<ElementOffset>(count);
        return *this;
    }
 
    Offset finish()
    {
        return finish_impl<Offset>();
    }
 
    RTI_FLAT_BUILDER_DEFINE_MOVE_OPERATIONS_IMPL(\
            FinalSequenceBuilder, AbstractSequenceBuilder, AbstractListBuilderMoveProxy)
};
 
template <typename T>
class PrimitiveSequenceBuilder
        : public AbstractSequenceBuilder<
                  typename detail::primitive_sequence_dheader_gen<T>::type> {
public:
    typedef PrimitiveSequenceOffset<T> Offset;
    typedef AbstractSequenceBuilder<
            typename detail::primitive_sequence_dheader_gen<T>::type>
            Base;
    using Base::is_valid;
    using Base::stream;
    using typename Base::nested_tag_t;
#if !defined(RTI_FLAT_DATA_CXX11_RVALUE_REFERENCES)
    using typename Base::AbstractListBuilderMoveProxy;
#endif
 
    PrimitiveSequenceBuilder()
    {
    }
 
protected:
    friend class AbstractBuilder;  // to allow access to the constructor
 
    PrimitiveSequenceBuilder(
            nested_tag_t,
            AbstractBuilder& parent,
            unsigned int alignment = RTI_XCDR_SEQ_LENGTH_ALIGNMENT)
            : Base(nested_tag_t(), parent, alignment)
    {
    }
 
public:
    PrimitiveSequenceBuilder& add_next(T value)
    {
        RTI_FLAT_BUILDER_CHECK_VALID(return *this);
 
        if (!stream().template serialize<T>(value)) {
            RTI_FLAT_BUILDER_OUT_OF_RESOURCES_ERROR(return *this);
        }
        
        Base::element_count_++;
        return *this;
    }
 
    PrimitiveSequenceBuilder& add_n(const T *array, unsigned int count)
    {
        RTI_FLAT_BUILDER_CHECK_VALID(return *this);
        RTI_FLAT_ASSERT(array != NULL, return *this);
 
        if (RTIXCdrUnsignedLong_MAX / static_cast<unsigned int>(sizeof(T))
                < count) {
            RTI_FLAT_BUILDER_OUT_OF_RESOURCES_ERROR(return *this);
        }
 
        if (!stream().check_size(static_cast<unsigned int>(sizeof(T)) * count)) {
            RTI_FLAT_BUILDER_OUT_OF_RESOURCES_ERROR(return *this);
        }
 
        if (stream().needs_byte_swap() && sizeof(T) > 1) {
            for (unsigned int i = 0; i < count; i++) {
                stream().template serialize_fast<T>(array[i]);
            }
        } else {
            stream().serialize_fast((void *) array, count * static_cast<unsigned int>(sizeof(T)));
        }
 
        Base::element_count_ += count;
        return *this;
    }
 
    PrimitiveSequenceBuilder& add_n(unsigned int count, T value)
    {
        RTI_FLAT_BUILDER_CHECK_VALID(return *this);
 
        if (RTIXCdrUnsignedLong_MAX / static_cast<unsigned int>(sizeof(T))
                < count) {
            RTI_FLAT_BUILDER_OUT_OF_RESOURCES_ERROR(return *this);
        }
 
        if (!stream().check_size(static_cast<unsigned int>(sizeof(T)) * count)) {
            RTI_FLAT_BUILDER_OUT_OF_RESOURCES_ERROR(return *this);
        }
 
        for (unsigned int i = 0; i < count; i++) {
            stream().template serialize_fast<T>(value);
        }
        Base::element_count_ += count;
        return *this;
    }
 
    PrimitiveSequenceBuilder& add_n(unsigned int count)
    {
        RTI_FLAT_BUILDER_CHECK_VALID(return *this);
 
        if (RTIXCdrUnsignedLong_MAX / static_cast<unsigned int>(sizeof(T))
                < count) {
            RTI_FLAT_BUILDER_OUT_OF_RESOURCES_ERROR(return *this);
        }
 
        if (!stream().skip(static_cast<unsigned int>(sizeof(T)) * count)) {
            RTI_FLAT_BUILDER_OUT_OF_RESOURCES_ERROR(return *this);
        }
 
        Base::element_count_ += count;
        return *this;
    }
 
 
    Offset finish()
    {
        this->finish_dheader();
        return Base::template finish_impl<Offset>();
    }
 
private:
    RTI_FLAT_BUILDER_DEFINE_MOVE_OPERATIONS_IMPL(\
            PrimitiveSequenceBuilder, Base, AbstractListBuilderMoveProxy)
};
 
class StringBuilder : public PrimitiveSequenceBuilder<char> {
public:
    typedef StringOffset Offset;
    typedef PrimitiveSequenceBuilder<char> Base;
    using Base::is_valid;
    using Base::stream;
    using typename Base::nested_tag_t;
 
    StringBuilder()
    {
    }
    
private:
    friend class AbstractBuilder; // to allow access to the constructor
 
    StringBuilder(
            nested_tag_t,
            AbstractBuilder& parent,
            unsigned int alignment = RTI_XCDR_SEQ_LENGTH_ALIGNMENT)
            : Base(nested_tag_t(), parent, alignment)
    {
    }
 
public:
    StringBuilder& set_string(const char *value)
    {
        RTI_FLAT_BUILDER_CHECK_VALID(return *this);
        RTI_FLAT_ASSERT(value != NULL, return *this);
 
        // if set_string is called more than once we override the string
        // that was set before
        if (Base::element_count_ != 0) {
            stream().current_position(begin_position());
            stream().serialize_fast<rti::xcdr::length_t>(0);
            Base::element_count_ = 0;
        }
 
        unsigned int length =
                static_cast<unsigned int>(RTIXCdrString_getLength(value)) + 1;
        add_n(value, length);  // if this fail, error has been reported
        return *this;
    }
 
    Offset finish()
    {
        RTI_FLAT_BUILDER_CHECK_VALID(return Offset());
 
        if (element_count_ == 0) {
            add_next('\0'); // build empty string if no string was built
        }
 
        Base::finish_dheader();
        return finish_impl<Offset>();
    }
 
    RTI_FLAT_BUILDER_DEFINE_MOVE_OPERATIONS_IMPL(\
            StringBuilder, Base, AbstractListBuilderMoveProxy)
};
 
// Wide strings are treated as a sequence of octets
typedef PrimitiveSequenceBuilder<unsigned char> WStringBuilder;
 
} }
 
#endif // RTI_DDS_FLAT_SEQUENCEBUILDERS_HPP_