FieldValue.hpp

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

#ifndef STREAMBASE_FIELDVALUE_HPP
#define STREAMBASE_FIELDVALUE_HPP

#include "StreamBase.hpp"
#include "CompleteDataType.hpp"
#include "Timestamp.hpp"

SB_NAMESPACE_BEGIN;

class Tuple;
class Function;

/** A value a Field may take on.  Also possibly a list element.  
 * Has a type and some information of said type.
 * 
 * FieldValues are immutable.  Calling an inappropriate getter will cause an error.
 * 
 *   <code>
 *   FieldValue fv(5);              // this creates a FieldValue of DataType::INT<br>
 *   cout << fv.getInt() << "\n";<br>
 *   cout << fv.getBool() << "\n";<br>
 *   </code>
 * 
 * The first <code>cout</code> line will succeed; the second will throw an exception.
 */
class FieldValue {
public:
#ifndef DOXYGEN_INTERNAL_ONLY
    /// Create a null FieldValue of DataType::NONE
    FieldValue();
#endif
    
    /// Destructor
    ~FieldValue();
    
#ifndef DOXYGEN_INTERNAL_ONLY
    /// Create a null FieldValue of the given CompleteDataType
    FieldValue(const CompleteDataType& cdt);
#endif
    
    /// DataType::BOOL constructor
    FieldValue(bool value);
    
    /// DataType::INT constructor
    FieldValue(int value);
    
    /// DataType::DOUBLE constructor
    FieldValue(double value);
    
    /// DataType::LONG constructor
    FieldValue(long long value);
    
    /// DataType::TIMESTAMP constructor
    FieldValue(const Timestamp& value);
    
    /// DataType::STRING constructor
    FieldValue(const char* value);
    
    /// DataType::STRING constructor
    FieldValue(const std::string& value);
    
    /// DataType::STRING, DataType::BLOB, and DataType::CAPTURE constructor
    FieldValue(const DataType& type, const std::string& value);
    
    /// DataType::TUPLE constructor
    FieldValue(const Tuple& value);

    /// DataType::FUNCTION constructor
    FieldValue(const Function& value);
    
    /// DataType::LIST constructor
    FieldValue(const std::vector<FieldValue>& value);

    /// Create an empty list of the specified element type
    FieldValue(const DataType& type, const CompleteDataType& elemType);

    /// Copy constructor
    FieldValue(const FieldValue& fv);

    /// Assignment operator
    const FieldValue& operator=(const FieldValue& fv);
    
    bool operator==(const FieldValue& t) const { return compare(t) == 0; }
    bool operator!=(const FieldValue& t) const { return compare(t) != 0; }
    bool operator<(const FieldValue& t) const { return compare(t) < 0; }
    bool operator>(const FieldValue& t) const { return compare(t) > 0; }
    bool operator<=(const FieldValue& t) const { return compare(t) <= 0; }
    bool operator>=(const FieldValue& t) const { return compare(t) >= 0; }
    
    /**
     * Compare the current FieldValue against the provided FieldValue.
     * 
     * Null FieldValues are less than non-null FieldValues.
     * Provides a total ordering over the set of possible FieldValues, so
     * does not check types.  Ordering of FieldValues of heterogeneous types 
     * is not guaranteed but is consistent.
     * 
     * @return -1 if the current FieldValue is less than the provided FieldValue,
     *   0 if the current is equal to the provided FieldValue,
     *   and 1 if the current is greater than the provided FieldValue.
     */
    int compare(const FieldValue& fv) const;
    
    /// Get the CompleteDataType of this FieldValue
    const CompleteDataType& getCompleteType() const;
    
    /// Get the primitive DataType of this FieldValue
    const DataType& getType() const;
    
#ifndef DOXYGEN_INTERNAL_ONLY
    size_t getSize() const;
#endif
    
    /**
     * Returns true if this FieldValue and the provided FieldValue are of the same type
     * 
     * "Of the same type" is defined as their CompleteDataType members being equivalent.
     */
    bool sameType(const FieldValue& fv) const;
    
    /// Return a string representation of this FieldValue.
    std::string as_string() const;
    
#ifndef DOXYGEN_INTERNAL_ONLY
    std::string toDelimitedString(const std::string& delimiter, 
                                              const std::string& null_string,
                                              bool include_names,
                                              bool quote_all_strings) const;
    
    std::string toCSVString(char delim, const std::string& null_string, char quote) const;
#endif

    /// Return true if this FieldValue represents a null value.
    bool isNull() const;
    
    /// Return the value of a boolean FieldValue.  
    /// Will throw an exception if this FieldValue is not of type DataType::BOOL.
    bool getBool() const;
    
    /// Return the value of an integer FieldValue.  
    /// Will throw an exception if this FieldValue is not of type DataType::INT.
    int getInt() const;
    
    /// Return the value of a double FieldValue.  
    /// Will throw an exception if this FieldValue is not of type DataType::DOUBLE.
    double getDouble() const;
    
    /// Return the value of a long FieldValue.  
    /// Will throw an exception if this FieldValue is not of type DataType::LONG.
    long long getLong() const;
    
    /// Return the value of a Timestamp FieldValue as a Timestamp.  
    /// Will throw an exception if this FieldValue is not of type DataType::TIMESTAMP.
    Timestamp getTimestamp() const;
    
    /// Return the value of a string FieldValue.  
    /// Will throw an exception if this FieldValue is not of type DataType::STRING.
    const std::string& getString() const;
    
    /// Return the value of a blob FieldValue as a string.  
    /// Will throw an exception if this FieldValue is not of type DataType::BLOB.
    const std::string& getBlob() const;
    
    /// Return the value of a Tuple FieldValue.  
    /// Will throw an exception if this FieldValue is not of type DataType::TUPLE.
    const Tuple& getTuple() const;

    /// Return the value of a Capture FieldValue, as a string
    /// Will throw an exception if this FieldValue is not of type DataType::CAPTURE.
    const std::string& getCapture() const;

    /// Return the value of a Function FieldValue
    /// Will throw an exception if this FieldValue is not of type DataType::FUNCTION.
    const Function& getFunction() const;
   
    /** Return the value of a Tuple FieldValue as a mutable Tuple.  
     * Will throw an exception if this FieldValue is not of type DataType::TUPLE.
     * 
     *  The caller takes on itself the responsibility of managing all concurrency.
     */
    Tuple& getTuple();
    
    /// Return the value of a List FieldValue.  
    /// Will throw an exception if this FieldValue is not of type DataType::LIST.
    const std::vector<FieldValue>& getList() const;
    
private:
    /// Set this FieldValue to represent a null value of its current type.
    void setNull(bool value = true);
    
    /// Set this FieldValue to be of type DataType::BOOL with the given boolean value.
    void setBool(bool value);

    /// Set this FieldValue to be of type DataType::INT with the given integer value.
    void setInt(int value);

    /// Set this FieldValue to be of type DataType::DOUBLE with the given double value.
    void setDouble(double value);

    /// Set this FieldValue to be of type DataType::LONG with the given long value.
    void setLong(long long value);

    /// Return the value of a Timestamp FieldValue as a long long.  
    /// Will error if this FieldValue is not of type DataType::TIMESTAMP.
    long long getTimestampLong() const;
    /// Set this FieldValue to be of type DataType::TIMESTAMP with the given Timestamp value.
    void setTimestamp(const Timestamp& value);
    /// Set this FieldValue to be of type DataType::TIMESTAMP with the given long long value.
    void setTimestampLong(long long value);

    /// Set this FieldValue to be of type DataType::STRING with the given string value.
    void setString(const std::string& value);

    /// Set this FieldValue to be of type DataType::BLOB with the given string as its blob value.
    void setBlob(const std::string& value);

    void setVarLength(const CompleteDataType& cdt, const std::string& value);
    
    const std::string& getVarLength() const;

    /// Set this FieldValue to be of type DataType::TUPLE with the given Tuple value.
    void setTuple(const Tuple& value);

    /// Set this FieldValue to be of the type DataType::FUNCTION with the given function value.
    void setFunction(const Function& value);

    /// Set this FieldValue to be of type DataType::LIST, with element type elemType, 
    /// with the given vector as its list value.  (Only way to make 0-element lists.)
    void setList(const CompleteDataType& elemType, const std::vector<FieldValue>& value);

    /// Set this FieldValue to be of type DataType::LIST with the given vector as its list value.
    /// Infers the element type from the type of the first FieldValue in the vector.
    void setList(const std::vector<FieldValue>& value);
    
    
    /** Member variables **/
    
    bool _isNull;
    //BOOL, INT, LONG, DOUBLE, TIMESTAMP
    union FieldUnion {
        bool b;
        int i;
        long long l;
        double d;
    };
    FieldUnion u;
    //StreamBase data types not represented by C's built-in types go outside the union 
    
    //default-constructed std::string's are cheap
    //so we don't have to worry about the cost
    //STRING, BLOB
    std::string varlen;

    //default-constructed vectors are also cheap
    //LIST
    std::vector<FieldValue> elems;

    //pointers are very cheap
    //TUPLE  (null otherwise)
    Tuple *nested_tuple;
    //FUNCTION (null otherwise)
    Function* function_value;

    //the complete (ie. fully-qualified) StreamBase type of a LIST's elements;
    //default-constructed otherwise
    CompleteDataType _cdt;

    std::string _captureName;

    void verifyCheck(const DataType& type) const;
    void unsetNull(const CompleteDataType& cdt);
    
    friend class sb_internal::SchemaUtil;
    friend class Tuple;
    friend struct TuplePrivateImpl;

};

SB_NAMESPACE_END;

#endif /* STREAMBASE_FIELDVALUE_HPP */