COP_CableStructure.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 */

#pragma once

#include "COP_API.h"

#include "COP_Signature.h"

#include <UT/UT_Array.h>
#include <UT/UT_StringHolder.h>

/// This class holds the structure of what flows through a cable. It's an
/// ordered collection of fields, each one having a name and a type.
class COP_API COP_CableStructure
{
public:
    /// Each field has a name and a type.
    struct CableField
    {
        UT_StringHolder         name;
        COP_Type                type;

        /// Required by COP_CableStructure::operator==().
        bool operator==(const CableField& other) const
        {
            return name == other.name && type == other.type;
        }
    };

public:
    COP_CableStructure() {}
    
    /// Number of fields in this cable.
    int getNumberOfFields() const;
    /// Name of the index-th field in this cable.
    const UT_StringHolder& getFieldName(int index) const;
    /// Changes the name of an already-existing field; if the field does not
    /// exist, returns false without making modifications.
    bool setFieldName(const UT_StringHolder& name, int index);

    /// Copies fields names from the other cable.
    void copyFieldNames(const COP_CableStructure& other);

    /// All existing fields of this cable structure will be renamed.
    void renameAllFields(const UT_StringHolder& name);

    /// Type of the index-th field in this cable.
    COP_Type getFieldType(int index) const;
    /// Type of the first field in this cable of the specified name.
    COP_Type getFieldType(const UT_StringHolder& name) const;
    /// Changes the type of an already-existing field; if the field does not
    /// exist, returns false without making modifications.
    bool setFieldType(COP_Type type, int index);

    /// Index of the field that has the given name.
    int getFieldIndex(const UT_StringHolder& name, int appearance = 0) const;
    /// Returns index of the first field that starts with the given name. If
    /// name of this field is an exact match, full_match is set to true.
    /// Otherwise, full_match is set to false. If a non-negative index (K) is
    /// returned and full_match is false, then the field at index K is the first
    /// one whose name starts with {name}{delimiter}. Returns -1 if no matches
    /// were found.
    int getFieldIndexFromPrefix(const UT_StringHolder& name, bool& full_match,
                                char delimiter = '.') const;
    /// Appearance index fo the field at the given index (this is the 0-based
    /// index of that field among all fields of the same name).
    int getFieldAppearance(int index) const;

    /// Adds a new field to this cable, of the given name and type. The new
    /// field is added to the end of the current list of fields.
    void addField(const UT_StringHolder& name, COP_Type type);
    /// Concatenates this structure with other; fields of other go after all
    /// current fields of this structure.
    /// If prefix is not null, every newly-added field's name will be
    /// prefix.name, where name is name of the original field.
    void addFields(const COP_CableStructure& other, const char* prefix);

    /// Removes all fields from this cable structure.
    void reset();

    /// Compares with another cable structure; two cable structures are equal if
    /// all fields have the same name and type.
    bool operator==(const COP_CableStructure& other) const
    {
        return myFields == other.myFields;
    }
    bool operator!=(const COP_CableStructure& other) const
    {
        return !(myFields == other.myFields);
    }

    int64       getMemoryUsage(bool inclusive=false) const
    {
        return (inclusive ? sizeof(*this) : 0) + myFields.getMemoryUsage(false);
    }

protected:
    /// Array of all fields in the cable.
    UT_Array<CableField>        myFields;
};

COP_API size_t
UTformatBuffer(char* buffer, size_t buffer_size, const COP_CableStructure& v);