UserFlags.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
//
// Copyright 2026 Caleb Buahin
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

 
#ifndef OPENSWMM_ENGINE_USER_FLAGS_HPP
#define OPENSWMM_ENGINE_USER_FLAGS_HPP
 
#include <string>
#include <unordered_map>
#include <vector>
#include <variant>
#include <optional>
#include <stdexcept>
 
#include "StringCase.hpp"
 
namespace openswmm {
 
// ============================================================================
// Type tag
// ============================================================================

enum class UserFlagType : int {
    BOOLEAN = 0,  
    INTEGER = 1,  
    REAL    = 2,  
    STRING  = 3   
};
 
// ============================================================================
// Schema definition
// ============================================================================

struct UserFlagDef {
    std::string  name;         
    UserFlagType type;         
    std::string  description;  
};
 
// ============================================================================
// Per-object value
// ============================================================================

using UserFlagValue = std::variant<bool, int, double, std::string>;

struct UserFlagAssignment {
    std::string    object_type;  
    std::string    object_name;  
    std::string    flag_name;    
    UserFlagValue  value;        
};
 
// ============================================================================
// Container
// ============================================================================

class UserFlags {
public:
 
    // ------------------------------------------------------------------
    // Schema (from [USER_FLAGS])
    // ------------------------------------------------------------------

    void define(UserFlagDef def) {
        const auto it = def_index_.find(def.name);
        if (it != def_index_.end()) {
            defs_[it->second] = std::move(def);
        } else {
            def_index_[def.name] = defs_.size();
            defs_.push_back(std::move(def));
        }
    }

    bool undefine(const std::string& name) {
        const auto it = def_index_.find(name);
        if (it == def_index_.end()) return false;
        const std::size_t idx = it->second;
        defs_.erase(defs_.begin() + static_cast<std::ptrdiff_t>(idx));
        def_index_.erase(it);
        // Reindex definitions that followed the erased slot.
        for (auto& kv : def_index_)
            if (kv.second > idx) --kv.second;
        // Remove orphaned per-object values (key = "TYPE:NAME:FLAG";
        // same left-to-right decomposition as InpWriter).
        for (auto vit = values_.begin(); vit != values_.end(); ) {
            const auto& key = vit->first;
            const auto p1 = key.find(':');
            const auto p2 = (p1 == std::string::npos)
                                ? std::string::npos : key.find(':', p1 + 1);
            if (p2 != std::string::npos && key.compare(p2 + 1, std::string::npos, name) == 0)
                vit = values_.erase(vit);
            else
                ++vit;
        }
        return true;
    }

    bool is_defined(const std::string& name) const {
        return def_index_.count(name) != 0;
    }

    const UserFlagDef& get_def(const std::string& name) const {
        const auto it = def_index_.find(name);
        if (it == def_index_.end())
            throw std::out_of_range("UserFlags: no definition for flag '" + name + "'");
        return defs_[it->second];
    }

    const std::vector<UserFlagDef>& all_defs() const noexcept { return defs_; }

    std::size_t def_count() const noexcept { return defs_.size(); }
 
    // ------------------------------------------------------------------
    // Per-object values (from [USER_FLAG_VALUES])
    // ------------------------------------------------------------------

    void set(const std::string& object_type,
             const std::string& object_name,
             const std::string& flag_name,
             UserFlagValue      value) {
        values_[make_key(object_type, object_name, flag_name)] = std::move(value);
    }

    bool unset(const std::string& object_type,
               const std::string& object_name,
               const std::string& flag_name) {
        return values_.erase(make_key(object_type, object_name, flag_name)) != 0;
    }

    bool has_value(const std::string& object_type,
                   const std::string& object_name,
                   const std::string& flag_name) const {
        return values_.count(make_key(object_type, object_name, flag_name)) != 0;
    }

    const UserFlagValue& get_value(const std::string& object_type,
                                   const std::string& object_name,
                                   const std::string& flag_name) const {
        const auto it = values_.find(make_key(object_type, object_name, flag_name));
        if (it == values_.end())
            throw std::out_of_range(
                "UserFlags: no value for " + object_type + ":" +
                object_name + ":" + flag_name);
        return it->second;
    }

    std::optional<UserFlagValue> try_get_value(const std::string& object_type,
                                               const std::string& object_name,
                                               const std::string& flag_name) const {
        const auto it = values_.find(make_key(object_type, object_name, flag_name));
        if (it == values_.end()) return std::nullopt;
        return it->second;
    }

    using ValueMap =
        std::unordered_map<std::string, UserFlagValue, CiHash, CiEqual>;

    const ValueMap& all_values() const noexcept {
        return values_;
    }

    std::size_t value_count() const noexcept { return values_.size(); }
 
    // ------------------------------------------------------------------
    // Reset
    // ------------------------------------------------------------------

    void clear() noexcept {
        defs_.clear();
        def_index_.clear();
        values_.clear();
    }
 
    // ------------------------------------------------------------------
    // Composite-key helper (public for tests)
    // ------------------------------------------------------------------

    static std::string make_key(const std::string& object_type,
                                const std::string& object_name,
                                const std::string& flag_name) {
        std::string key;
        key.reserve(object_type.size() + 1 + object_name.size() + 1 + flag_name.size());
        key += object_type;
        key += ':';
        key += object_name;
        key += ':';
        key += flag_name;
        return key;
    }
 
private:
    // Schema
    std::vector<UserFlagDef>                  defs_;
    std::unordered_map<std::string, std::size_t> def_index_;  
 
    // Per-object values
    ValueMap values_;   
};
 
} /* namespace openswmm */
 
#endif /* OPENSWMM_ENGINE_USER_FLAGS_HPP */