Line data    Source code

       1              : /****************************************************************************/
       2              : // Eclipse SUMO, Simulation of Urban MObility; see https://eclipse.dev/sumo
       3              : // Copyright (C) 2012-2026 German Aerospace Center (DLR) and others.
       4              : // This program and the accompanying materials are made available under the
       5              : // terms of the Eclipse Public License 2.0 which is available at
       6              : // https://www.eclipse.org/legal/epl-2.0/
       7              : // This Source Code may also be made available under the following Secondary
       8              : // Licenses when the conditions for such availability set forth in the Eclipse
       9              : // Public License 2.0 are satisfied: GNU General Public License, version 2
      10              : // or later which is available at
      11              : // https://www.gnu.org/licenses/old-licenses/gpl-2.0-standalone.html
      12              : // SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-or-later
      13              : /****************************************************************************/
      14              : /// @file    ParquetFormatter.h
      15              : /// @author  Michael Behrisch
      16              : /// @date    2025-06-17
      17              : ///
      18              : // Output formatter for Parquet output
      19              : /****************************************************************************/
      20              : #pragma once
      21              : #include <config.h>
      22              : 
      23              : #include <memory>
      24              : #include <ostream>
      25              : #include <utils/common/ToString.h>
      26              : #include "OutputFormatter.h"
      27              : 
      28              : 
      29              : // ===========================================================================
      30              : // class definitions
      31              : // ===========================================================================
      32              : /**
      33              :  * @class ParquetFormatter
      34              :  * @brief Output formatter for Parquet output
      35              :  *
      36              :  * All arrow/parquet types are hidden in the Impl so that callers
      37              :  * (notably OutputDevice.h) do not pay the include cost.
      38              :  */
      39              : class ParquetFormatter : public OutputFormatter {
      40              : public:
      41              :     /// @brief Constructor
      42              :     // for some motivation on the default batch size see https://stackoverflow.com/questions/76782018/what-is-actually-meant-when-referring-to-parquet-row-group-size
      43              :     ParquetFormatter(const std::string& columnNames, const std::string& compression = "", const int batchSize = 1000000);
      44              : 
      45              :     /// @brief Destructor (out-of-line: Impl is incomplete here)
      46              :     ~ParquetFormatter() override;
      47              : 
      48              :     void openTag(std::ostream& into, const std::string& xmlElement) override;
      49              :     void openTag(std::ostream& into, const SumoXMLTag& xmlElement) override;
      50              :     bool closeTag(std::ostream& into, const std::string& comment = "") override;
      51              : 
      52              :     /** @brief writes a named attribute
      53              :      *
      54              :      * Generic template: stringifies the value (only when not null, preserving the
      55              :      * original lazy evaluation) and forwards to the typed non-template
      56              :      * helpers defined in the .cpp.
      57              :      */
      58              :     template <class T>
      59         7838 :     void writeAttr(std::ostream& /* into */, const SumoXMLAttr attr, const T& val, const bool isNull) {
      60         7838 :         if (isNull) {
      61          948 :             writeNullAttr(attr);
      62              :         } else {
      63        13780 :             writeStringAttr(attr, toString(val));
      64              :         }
      65         7838 :     }
      66              : 
      67              :     template <class T>
      68        22963 :     void writeAttr(std::ostream& /* into */, const std::string& attr, const T& val, const bool isNull) {
      69        22963 :         if (isNull) {
      70          432 :             writeNullAttr(attr);
      71              :         } else {
      72        45062 :             writeStringAttr(attr, toString(val));
      73              :         }
      74        22963 :     }
      75              : 
      76              :     /// @brief typed overloads (non-template) -- picked by overload resolution over the template
      77              :     void writeAttr(std::ostream& into, const SumoXMLAttr attr, const double& val, const bool isNull);
      78              :     void writeAttr(std::ostream& into, const SumoXMLAttr attr, const int& val, const bool isNull);
      79              :     void writeAttr(std::ostream& into, const std::string& attr, const double& val, const bool isNull);
      80              :     void writeAttr(std::ostream& into, const std::string& attr, const int& val, const bool isNull);
      81              : 
      82              :     void writeTime(std::ostream& into, const SumoXMLAttr attr, const SUMOTime val) override;
      83              : 
      84              :     bool wroteHeader() const override;
      85              : 
      86              :     void setExpectedAttributes(const SumoXMLAttrMask& expected, const int depth = 2) override;
      87              : 
      88              : private:
      89              :     /// @brief non-template helpers; defined in the .cpp where arrow/parquet are available
      90              :     void writeStringAttr(const SumoXMLAttr attr, const std::string& val);
      91              :     void writeStringAttr(const std::string& attr, const std::string& val);
      92              :     void writeNullAttr(const SumoXMLAttr attr);
      93              :     void writeNullAttr(const std::string& attr);
      94              : 
      95              :     /// @brief opaque arrow/parquet state
      96              :     struct Impl;
      97              :     std::unique_ptr<Impl> myImpl;
      98              : };