arrayEditBuilder.h

Go to the documentation of this file.

//
// Copyright 2025 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//
 
#ifndef PXR_BASE_VT_ARRAY_EDIT_BUILDER_H
#define PXR_BASE_VT_ARRAY_EDIT_BUILDER_H
 
 
#include "pxr/pxr.h"
#include "pxr/base/vt/api.h"
#include "pxr/base/vt/array.h"
#include "pxr/base/vt/arrayEditOps.h"
#include "pxr/base/vt/arrayEdit.h"
#include "pxr/base/vt/hash.h"
#include "pxr/base/vt/streamOut.h"
 
#include "pxr/base/tf/diagnostic.h"
#include "pxr/base/tf/span.h"
 
#include <unordered_map>
 
PXR_NAMESPACE_OPEN_SCOPE
 
// Non-template helper class for VtArrayEditBuilder.
class Vt_ArrayEditOpsBuilder
{
public:
    using Ops = Vt_ArrayEditOps;
 
    VT_API
    void AddOp(Ops::Op op, int64_t a1, int64_t a2);
 
    VT_API
    void AddOp(Ops::Op op, int64_t a1);
    
private:
    template <class ELEM>
    friend class VtArrayEditBuilder;
 
    void _AddOp(Ops::Op op);
 
    static void _IssueArityError(Ops::Op op, int count);
    static void _IssueNegativeSizeError(Ops::Op op, int64_t size);
    
    static inline bool _CheckArity(Ops::Op op, int count);
 
    std::vector<int64_t> _ins;
    int64_t _lastOpIdx = 0;
};
 
template <class ELEM>
class VtArrayEditBuilder
{
public:
    using Ops = Vt_ArrayEditOps;
    using Edit = VtArrayEdit<ELEM>;
    using Array = typename Edit::Array;
    using ElementType = typename Edit::ElementType;
    using Self = VtArrayEditBuilder;
 
    static constexpr auto EndIndex = Vt_ArrayEditOps::EndIndex;
 
    VtArrayEditBuilder() = default;
 
    Self &Write(ElementType const &elem, int64_t index) {
        _opsBuilder.AddOp(Ops::OpWriteLiteral, _FindOrAddLiteral(elem), index);
        return *this;
    }
    
    Self &WriteRef(int64_t srcIndex, int64_t dstIndex) {
        _opsBuilder.AddOp(Ops::OpWriteRef, srcIndex, dstIndex);
        return *this;
    }
 
    Self &Insert(ElementType const &elem, int64_t index) {
        _opsBuilder.AddOp(Ops::OpInsertLiteral, _FindOrAddLiteral(elem), index);
        return *this;
    }
 
    Self &InsertRef(int64_t srcIndex, int64_t dstIndex) {
        _opsBuilder.AddOp(Ops::OpInsertRef, srcIndex, dstIndex);
        return *this;
    }
 
    Self &Prepend(ElementType const &elem) {
        _opsBuilder.AddOp(Ops::OpInsertLiteral, _FindOrAddLiteral(elem), 0);
        return *this;
    }
    
    Self &PrependRef(int64_t srcIndex) {
        _opsBuilder.AddOp(Ops::OpInsertRef, srcIndex, 0);
        return *this;
    }
 
    Self &Append(ElementType const &elem) {
        _opsBuilder.AddOp(
            Ops::OpInsertLiteral, _FindOrAddLiteral(elem), EndIndex);
        return *this;
    }
    
    Self &AppendRef(int64_t srcIndex) {
        _opsBuilder.AddOp(Ops::OpInsertRef, srcIndex, EndIndex);
        return *this;
    }
    
    Self &EraseRef(int64_t index) {
        _opsBuilder.AddOp(Ops::OpEraseRef, index);
        return *this;
    }
 
    Self &MinSize(int64_t size) {
        _opsBuilder.AddOp(Ops::OpMinSize, size);
        return *this;
    }
 
    Self &MinSize(int64_t size, ElementType const &fill) {
        _opsBuilder.AddOp(Ops::OpMinSizeFill, size, _FindOrAddLiteral(fill));
        return *this;
    }
 
    Self &MaxSize(int64_t size) {
        _opsBuilder.AddOp(Ops::OpMaxSize, size);
        return *this;
    }
 
    Self &SetSize(int64_t size) {
        _opsBuilder.AddOp(Ops::OpSetSize, size);
        return *this;
    }
 
    Self &SetSize(int64_t size, ElementType const &fill) {
        _opsBuilder.AddOp(Ops::OpSetSizeFill, size, _FindOrAddLiteral(fill));
        return *this;
    }
 
    VtArrayEdit<ELEM> FinalizeAndReset() {
        VtArrayEdit<ELEM> result;
        result._literals = std::move(_literals);
        result._ops._ins = std::move(_opsBuilder._ins);
        *this = {};
        return result;
    }
 
    static VtArrayEdit<ELEM> Optimize(VtArrayEdit<ELEM> &&in);
 
    // Return data for serializing `edit`, so it can be reconstructed later by
    // CreateFromSerializationData().
    //
    // This API is intended to be called only by storage/transmission
    // implementations.
    static void
    GetSerializationData(VtArrayEdit<ELEM> const &edit,
                         VtArray<ELEM> *valuesOut,
                         std::vector<int64_t> *indexesOut) {
        if (TF_VERIFY(valuesOut) && TF_VERIFY(indexesOut)) {
            *valuesOut = edit._literals;
            *indexesOut = edit._ops._ins;
        }
    }
 
    // Construct an array edit using serialization data previously obtained from
    // GetSerializationData().
    //
    // This API is intended to be called only by storage/transmission
    // implementations.
    static VtArrayEdit<ELEM>
    CreateFromSerializationData(VtArray<ELEM> const &values,
                                TfSpan<int64_t> indexes) {
        VtArrayEdit<ELEM> result;
        result._literals = values;
        result._ops._ins = std::vector<int64_t>(indexes.begin(), indexes.end());
        return result;
    }
    
private:
    int64_t _FindOrAddLiteral(ElementType const &elem) {
        auto iresult = _literalToIndex.emplace(elem, _literals.size());
        if (iresult.second) {
            _literals.push_back(elem);
        }
        return iresult.first->second;
    }
    
    Array _literals;
    Vt_ArrayEditOpsBuilder _opsBuilder;
    std::unordered_map<ElementType, int64_t, TfHash> _literalToIndex;
   
};
 
template <class ELEM>
VtArrayEdit<ELEM>
VtArrayEditBuilder<ELEM>::Optimize(VtArrayEdit<ELEM> &&in)
{
    if (in.IsIdentity()) {
        return std::move(in);
    }
    
    VtArrayEditBuilder builder;
 
    // Walk all the instructions and rebuild.
    const Array literals = std::move(in._literals);
    const auto numLiterals = literals.size();
    Ops ops = std::move(in._ops);
 
    in._literals.clear();
    in._ops = {};
    
    ops.ForEach([&](Ops::Op op, int64_t a1, int64_t a2) {
        switch (op) {
        case Ops::OpWriteLiteral:
            // Ignore out-of-range literal indexes.
            if (a1 >= 0 && static_cast<size_t>(a1) < numLiterals) {
                builder.Write(literals[a1], a2);
            }
            break;
        case Ops::OpInsertLiteral:
            // Ignore out-of-range literal indexes.
            if (a1 >= 0 && static_cast<size_t>(a1) < numLiterals) {
                builder.Insert(literals[a1], a2);
            }
            break;
        case Ops::OpWriteRef:  builder.WriteRef(a1, a2);  break;
        case Ops::OpInsertRef: builder.InsertRef(a1, a2); break;
        case Ops::OpEraseRef:  builder.EraseRef(a1);      break;
        case Ops::OpMinSize:   builder.MinSize(a1);       break;
        case Ops::OpSetSize:   builder.SetSize(a1);       break;
        case Ops::OpMaxSize:   builder.MaxSize(a1);       break;
        case Ops::OpMinSizeFill:
            // Ignore out-of-range literal indexes.
            if (a1 >= 0 && static_cast<size_t>(a1) < numLiterals) {
                builder.MinSize(a1, literals[a2]);
            }
            break;
        case Ops::OpSetSizeFill:
            // Ignore out-of-range literal indexes.
            if (a1 >= 0 && static_cast<size_t>(a1) < numLiterals) {
                builder.SetSize(a1, literals[a2]);
            }
            break;
        };
    });
    
    return builder.FinalizeAndReset();
}
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif // PXR_BASE_VT_ARRAY_EDIT_BUILDER_H