ErrorCodes.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_ERROR_CODES_HPP
#define OPENSWMM_ENGINE_ERROR_CODES_HPP
 
#include <string>
#include <string_view>
 
namespace openswmm {
 
// ============================================================================
// Error codes — matching legacy error.h / error.txt numeric values
// ============================================================================
 
enum ErrorCode : int {
    ERR_NONE                    = 0,
 
    // --- System errors (100s) ---
    ERR_MEMORY                  = 101,  
    ERR_KINWAVE                 = 103,  
    ERR_ODE_SOLVER              = 105,  
    ERR_TIMESTEP                = 107,  
 
    // --- Object validation errors (108–145) ---
    ERR_SUBCATCH_OUTLET         = 108,  
    ERR_AQUIFER_PARAMS          = 109,  
    ERR_GROUND_ELEV             = 110,  
    ERR_LENGTH                  = 111,  
    ERR_ELEV_DROP               = 112,  
    ERR_ROUGHNESS               = 113,  
    ERR_BARRELS                 = 114,  
    ERR_SLOPE                   = 115,  
    ERR_NO_XSECT                = 117,  
    ERR_XSECT                   = 119,  
    ERR_NO_CURVE                = 121,  
    ERR_PUMP_LIMITS             = 122,  
    ERR_LOOP                    = 131,  
    ERR_MULTI_OUTLET            = 133,  
    ERR_DUMMY_LINK              = 134,  
    ERR_DIVIDER                 = 135,  
    ERR_DIVIDER_LINK            = 136,  
    ERR_WEIR_DIVIDER            = 137,  
    ERR_NODE_DEPTH              = 138,  
    ERR_REGULATOR               = 139,  
    ERR_STORAGE_VOLUME          = 140,  
    ERR_OUTFALL                 = 141,  
    ERR_REGULATOR_SHAPE         = 143,  
    ERR_NO_OUTLETS              = 145,  
 
    // --- Hydrology errors (151–159) ---
    ERR_UNITHYD_TIMES           = 151,  
    ERR_UNITHYD_RATIOS          = 153,  
    ERR_RDII_AREA               = 155,  
    ERR_RAIN_FILE_CONFLICT      = 156,  
    ERR_RAIN_GAGE_FORMAT        = 157,  
    ERR_RAIN_GAGE_TSERIES       = 158,  
    ERR_RAIN_GAGE_INTERVAL      = 159,  
 
    // --- Treatment ---
    ERR_CYCLIC_TREATMENT        = 161,  
 
    // --- Curves / timeseries (171–173) ---
    ERR_CURVE_SEQUENCE          = 171,  
    ERR_TIMESERIES_SEQUENCE     = 173,  
 
    // --- Snow / LID (181–188) ---
    ERR_SNOWMELT_PARAMS         = 181,  
    ERR_SNOWPACK_PARAMS         = 182,  
    ERR_LID_TYPE                = 183,  
    ERR_LID_LAYER               = 184,  
    ERR_LID_PARAMS              = 185,  
    ERR_LID_AREAS               = 187,  
    ERR_LID_CAPTURE_AREA        = 188,  
 
    // --- Date / reporting (191–195) ---
    ERR_START_DATE              = 191,  
    ERR_REPORT_DATE             = 193,  
    ERR_REPORT_STEP             = 195,  
 
    // --- Input parsing (200–235) ---
    ERR_INPUT                   = 200,  
    ERR_INPUT_LINE              = 201,  
    ERR_ITEMS                   = 203,  
    ERR_KEYWORD                 = 205,  
    ERR_DUP_NAME                = 207,  
    ERR_NAME                    = 209,  
    ERR_NUMBER                  = 211,  
    ERR_DATETIME                = 213,  
    ERR_CONTROL_RULE            = 217,  
    ERR_TRANSECT_UNKNOWN        = 219,  
    ERR_TRANSECT_SEQUENCE       = 221,  
    ERR_TRANSECT_TOO_FEW        = 223,  
    ERR_TRANSECT_TOO_MANY       = 225,  
    ERR_TRANSECT_MANNING        = 227,  
    ERR_TRANSECT_OVERBANK       = 229,  
    ERR_TRANSECT_NO_DEPTH       = 231,  
    ERR_MATH_EXPR               = 233,  
    ERR_INFILTRATION            = 235,  
 
    // --- File I/O (301–363) ---
    ERR_FILE_NAME               = 301,  
    ERR_INP_FILE                = 303,  
    ERR_RPT_FILE                = 305,  
    ERR_OUT_FILE                = 307,  
    ERR_OUT_SIZE                = 308,  
    ERR_OUT_WRITE               = 309,  
    ERR_OUT_READ                = 311,  
    ERR_RAIN_IFACE_SCRATCH      = 313,  
    ERR_RAIN_IFACE              = 315,  
    ERR_RAIN_FILE_OPEN          = 317,  
    ERR_RAIN_FILE_SEQUENCE      = 318,  
    ERR_RAIN_FILE_FORMAT        = 319,  
    ERR_RAIN_IFACE_FORMAT       = 320,  
    ERR_RAIN_IFACE_GAGE         = 321,  
    ERR_RUNOFF_IFACE            = 323,  
    ERR_RUNOFF_IFACE_COMPAT     = 325,  
    ERR_RUNOFF_IFACE_EOF        = 327,  
    ERR_RUNOFF_IFACE_READ       = 329,  
    ERR_HOTSTART_FILE           = 331,  
    ERR_HOTSTART_COMPAT         = 333,  
    ERR_HOTSTART_READ           = 335,  
    ERR_NO_CLIMATE_FILE         = 336,  
    ERR_CLIMATE_FILE_OPEN       = 337,  
    ERR_CLIMATE_FILE_READ       = 338,  
    ERR_CLIMATE_FILE_EOF        = 339,  
    ERR_RDII_IFACE_SCRATCH      = 341,  
    ERR_RDII_IFACE              = 343,  
    ERR_RDII_IFACE_FORMAT       = 345,  
    ERR_ROUTING_IFACE           = 351,  
    ERR_ROUTING_IFACE_FORMAT    = 353,  
    ERR_ROUTING_IFACE_NAMES     = 355,  
    ERR_ROUTING_IFACE_SAME      = 357,  
    ERR_TABLE_FILE_OPEN         = 361,  
    ERR_TABLE_FILE_READ         = 363,  
 
    // --- System / API errors (500–509) — legacy API error keys ---
    ERR_SYSTEM                  = 500,  
    ERR_API_NOT_OPENED          = 501,  
    ERR_API_NOT_STARTED         = 502,  
    ERR_API_NOT_ENDED           = 503,  
    ERR_API_OBJECT_TYPE         = 504,  
    ERR_API_OBJECT_INDEX        = 505,  
    ERR_API_OBJECT_NAME         = 506,  
    ERR_API_PROPERTY_TYPE       = 507,  
    ERR_API_PROPERTY_VALUE      = 508,  
    ERR_API_TIME_PERIOD         = 509,  
 
    // --- New 6.0 errors (600+) ---
    ERR_TIMESERIES_EMPTY        = 601,  
    ERR_TIMESERIES_NAN          = 603,  
    ERR_TABLE_COL_MISMATCH      = 605,  
    ERR_GAGE_TSERIES_NOTFOUND   = 607,  
 
    // --- Virtual junctions (609–621) — refactored engine only ---
    ERR_VJ_LINK_COUNT           = 609,  
    ERR_VJ_XSECT_MISMATCH       = 611,  
    ERR_VJ_OFFSET               = 613,  
    ERR_VJ_INVERT_MISMATCH      = 615,  
    ERR_VJ_LATERAL_INFLOW       = 617,  
    ERR_VJ_ROUTING_MODEL        = 619,  
    ERR_VJ_EXTRA_TOKENS         = 621,  
 
    // --- Inlet junctions (623–635) — refactored engine only ---
    ERR_IJ_NOT_STREET           = 623,  
    ERR_IJ_DESIGN               = 625,  
    ERR_IJ_CAPTURE_NODE         = 627,  
    ERR_IJ_USAGE_ON_PAIR        = 629,  
    ERR_IJ_EXTRA_TOKENS         = 631,  
    ERR_IJ_NO_USAGE             = 633,  
    ERR_INLET_USAGE_SHAPE       = 635,  
};
 
// ============================================================================
// CFFI error codes — categorical codes from the C API
// ============================================================================
// These map to the SWMM_ErrorCode enum in openswmm_engine.h and provide
// broad categories. Use error_get_cffi_template() to get descriptions.
 
enum CffiErrorCode : int {
    CFFI_OK              = 0,
    CFFI_ERR_NOMEM       = 1,   
    CFFI_ERR_INPFILE     = 2,   
    CFFI_ERR_RPTFILE     = 3,   
    CFFI_ERR_OUTFILE     = 4,   
    CFFI_ERR_PARSE       = 5,   
    CFFI_ERR_LIFECYCLE   = 6,   
    CFFI_ERR_BADHANDLE   = 7,   
    CFFI_ERR_BADINDEX    = 8,   
    CFFI_ERR_BADPARAM    = 9,   
    CFFI_ERR_PLUGIN      = 10,  
    CFFI_ERR_IO          = 11,  
    CFFI_ERR_HOTSTART    = 12,  
    CFFI_ERR_CRS         = 13,  
    CFFI_ERR_NUMERICAL   = 14,  
    CFFI_ERR_INTERNAL    = 99,  
};
 
// ============================================================================
// CFFI warning codes
// ============================================================================
 
enum CffiWarnCode : int {
    CFFI_WARN_NONE              = 0,
    CFFI_WARN_HOTSTART_MISSING  = 1,   
    CFFI_WARN_UNKNOWN_SECTION   = 2,   
    CFFI_WARN_UNKNOWN_OPTION    = 3,   
    CFFI_WARN_DEPRECATED_KW     = 4,   
    CFFI_WARN_PLUGIN_INIT       = 5,   
    CFFI_WARN_NUMERICAL         = 6,   
    CFFI_WARN_STABILITY_LIMIT   = 7,   
};
 
// ============================================================================
// Warning codes — matching legacy text.h WARN01–WARN13
// ============================================================================
 
enum WarnCode : int {
    WARN_NONE                   = 0,
    WARN_WET_STEP_REDUCED       = 1,   
    WARN_MAX_DEPTH_INCREASED    = 2,   
    WARN_NEGATIVE_OFFSET        = 3,   
    WARN_MIN_ELEV_DROP          = 4,   
    WARN_MIN_SLOPE              = 5,   
    WARN_DRY_STEP_INCREASED     = 6,   
    WARN_ROUTING_STEP_REDUCED   = 7,   
    WARN_ELEV_DROP_EXCEEDS      = 8,   
    WARN_GAGE_INTERVAL          = 9,   
    WARN_REGULATOR_CREST_LOW    = 10,  
    WARN_CONTROL_RULE_ATTR      = 11,  
    WARN_INLET_REMOVED          = 12,  
    WARN_UH_PARAMS_REPEATED     = 13,  
 
    // --- New 6.0 warnings (100+) ---
    WARN_TIMESERIES_DUPLICATE_X = 101, 
    WARN_BOUNDARY_OVERLAP       = 102, 
    WARN_FILES_SLOT_UNSUPPORTED = 103, 
    WARN_2D_OPTION_RETIRED      = 104, 
    WARN_FV_OPTION_INERT        = 105, 
    WARN_DW_OPTION_UNDER_FV     = 106, 
    WARN_RAIN_CSV_ROWS_SKIPPED  = 107, 
    WARN_FV_SLOT_CAP            = 108, 
};
 
// ============================================================================
// Lookup and formatting
// ============================================================================

std::string_view error_get_template(int code) noexcept;

std::string_view warning_get_template(int code) noexcept;

std::string format_error(int code, std::string_view name = "");

std::string format_error(int code, std::string_view name, std::string_view detail);

std::string format_warning(int code, std::string_view name = "");

std::string format_warning(int code, std::string_view name, std::string_view detail);
 
// ============================================================================
// CFFI / C API code lookup
// ============================================================================

std::string_view cffi_error_get_template(int code) noexcept;

std::string_view cffi_warning_get_template(int code) noexcept;

std::string format_cffi_error(int code, std::string_view name = "");

std::string format_cffi_warning(int code, std::string_view name = "");
 
} /* namespace openswmm */
 
#endif /* OPENSWMM_ENGINE_ERROR_CODES_HPP */