Field.hpp

//
// Copyright (c) 2004-2023 TIBCO Software Inc. All rights reserved.
//

#ifndef STREAMBASE_FIELD_H_
#define STREAMBASE_FIELD_H_

#include "StreamBase.hpp"

#include <string>
#include <vector>

#include "CompleteDataType.hpp"
#include "Schema.hpp"

SB_INTERNAL_FWD(SchemaUtil);

SB_NAMESPACE_BEGIN;

 /// Information (name, type, and optionally size) about a field in a Schema.
 /// <p>
 /// A field can be looked up within a schema in three ways:
 /// <ol>
 /// <li>By index: By the zero-based ordinal position of the field within the
 /// schema</li>
 /// <li>By simple name: By the name of the field itself (e.g., "myint")</li>
 /// <li>By path name: By a dot-separated list of names that define a path
 /// through a set of nested schemas that arise through the use of fields of
 /// type Tuple (e.g., "mynestedtuple.myint").</li>
 /// </ol>
 /// <p>
 /// A Field object can be used to obtain the value of a field in a tuple.
 /// However, there are rules that must be obeyed in doing so. For example,
 /// one must obtain the Field object from a Schema object that describes the
 /// schema of the tuple (i.e., as opposed to directly from a Field
 /// constructor).
 /// <p>
 /// See the "client" StreamBase sample (<em>streambase-install-dir</em>/sample/client)
 /// for examples of proper use of Field objects.
class Field {
  public:
    /// Constructs a null (invalid) field.
    Field();
    
    // Destroy a field, freeing _schema
    ~Field();

    /// Constructs a field; deprecated.
    /// @deprecated Use Field(std::string&, const CompleteDataType&) instead.
    Field(const std::string &name, DataType type, size_t size = (size_t)-1);

    /// Constructs a field; deprecated.
    /// @deprecated Use Field(std::string&, CompleteDataType::forTuple(const Schema& schema)) instead.
    Field(const std::string &name, DataType type, const Schema& schema);
    
    /// Constructs a field.
    Field(const std::string &name, const CompleteDataType& cdt);
    
    /// Copy constructor
    Field(const Field& f);
    
    /// Assignment operator
    Field& operator=(const Field& f);

#ifndef DOXYGEN_INTERNAL_ONLY
    /// Returns an XML representation of a field.
    std::string as_xml() const;
#endif

    /// Returns a string representation of a field.
    std::string as_string() const;

    /// Returns the field's schema (valid only if the field's type is TUPLE)
    const Schema getSchema() const { return _cdt.getSchema(); }

    /// Returns the name of a field.
    const std::string &getName() const { return _name; }

    /// Returns the type of a field (e.g., DataType::INT).
    const DataType &getType() const { return _cdt.getType(); }

    /// Returns the complete type of a field (e.g., DataType::LIST of DataType::INTs).
    const CompleteDataType &getCompleteType() const { return _cdt; }

    /// Returns the complete type of a field's elements 
    /// (e.g., on a DataType::LIST of DataType::INTs, returns a CompleteDataType of DataType::INT).
    const CompleteDataType &getElementCompleteType() const { return _cdt.getElementCompleteType(); }

    const CompleteDataType& getReturnType() const {
        return _cdt.getReturnType();
    }

    const Schema& getArgumentSchema() const {
        return _cdt.getArgumentSchema();
    }
    
    /// Returns the size of a field if it has a fixed size or -1
    size_t getFixedSize() const {
        return getType().getSize();
    }

    /// Returns the index of the field
    int getIndex() const { return _index; }

    /// Return true if the fields are the same type (including
    /// size information)
    bool sameType(const Field &other) const {
        return _cdt == other._cdt;
    }

    const std::vector<Field> &getFieldPath() const { return _field_path; }

#ifndef DOXYGEN_INTERNAL_ONLY
    /// The size of the header at the beginning of variably-sized data types
    static const int VARLEN_HEADER_SIZE = 4;
    
    /// The size of the header at the beginning of every string.
    static const int STRING_HEADER_SIZE = VARLEN_HEADER_SIZE;

    /// The size of the header at the beginning of every nested tuple.
    static const int NESTED_TUPLE_HEADER_SIZE = VARLEN_HEADER_SIZE;

    /// The size of the header at the beginning of every list.
    static const int LIST_HEADER_SIZE = VARLEN_HEADER_SIZE + 4;
#endif

  private:
    Field(const std::vector<Field>& field_path);

    std::string _name;
    CompleteDataType _cdt;
    size_t _size;
    int _index;
    std::vector<Field> _field_path; // non-empty only for Fields that are paths

    std::string as_xml_helper(const CompleteDataType& cdt, std::string tag, std::string name) const;

    friend class Schema;
    friend class sb_internal::SchemaUtil;
    friend class JavaQBox;
};

SB_NAMESPACE_END;

#endif /*STREAMBASE_FIELD_H_*/