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_*/