/* =====================================
 * Generated by Mod-c 0.26.5
 * HEADER utils MODULE
 * ===================================== */

#ifndef MODC_MODULE_utils_H
#define MODC_MODULE_utils_H

#include <stdint.h>
#include <stdbool.h>
#include <assert.h>

#define nil ((void *)0)
#define NIL nil
typedef uint8_t byte;
typedef const char* string;
typedef int integer;
typedef unsigned int cardinal;
typedef float real;

/**
 * Mod-c
 * By M. Scott Reynolds
 * Date 20 February 2026
 *
 * utils.c - Portable helper functions and safe arithmetic utilities.
 */

/* === IMPORT === */
#include "stddef.h"

/* === IMPORT === */
#include "stdlib.h"

/* === IMPORT === */
#include "string.h"

/* === IMPORT === */
#include "limits.h"

/* === IMPORT === */
#include "stdio.h"

/* === IMPORT === */
#include "ctype.h"

/* === TYPE EXPORT === */
typedef long long LONG;

/* === TYPE EXPORT === */
typedef long long long_long;

/* === TYPE EXPORT === */
typedef unsigned int uint;

/* === TYPE EXPORT === */
typedef unsigned char uchar;

/* === TYPE EXPORT === */
typedef char* pchar;

/**
 * Portable replacement for strnlen (not in C89/C95, but very useful).
 * Returns the length of the string or maxlen if no null terminator found.
 */

/* === PROC/FUNC EXPORT === */
size_t utils_strnlen(string s, size_t maxlen);

/**
 * Portable replacement for strndup.
 * Allocates and returns a new null-terminated copy of the first n chars of s.
 * Returns NULL on allocation failure (caller must check).
 */

/* === PROC/FUNC EXPORT === */
pchar utils_strndup(string s, size_t n);

/**
 * Integer power using exponentiation by squaring (positive exponents only) 
 * Checks for overflow before each multiplication.
 * Exits program on detected overflow.
 *
 * @param base  Base value (may be negative)
 * @param exp   Non-negative exponent
 * @return      base^exp if representable in long long
 */

/* === PROC/FUNC EXPORT === */
LONG utils_power(LONG base, cardinal exponent);

/**
 * @brief   Safely multiplies two signed long long integers.
 * @details Checks for overflow before performing the multiplication.
 *          Uses the standard method of testing against LLONG_MAX / LLONG_MIN
 *          to detect cases where the result would exceed the representable range.
 *
 * @param   a        First operand
 * @param   b        Second operand
 * @return  The product a * b if it can be represented in long long.
 *          Exits the program with an error message on overflow.
 *
 * @note    Assumes two's complement (guaranteed in C11 for signed integers).
 *          Corectly handles the edge case LLONG_MIN * -1.
 */

/* === PROC/FUNC EXPORT === */
long long utils_safe_multiply(long_long a, long_long b);

/**
 * Parse integer literal that may contain:
 *  - _ digit separators (ignored)
 *  - 0x / 0X   hexadecimal
 *  - 0o / 0O   octal
 *  - 0b / 0B   binary
 * Exits on overflow or invalid characters.
 */

/* === PROC/FUNC EXPORT === */
long_long utils_parse_integer_literal(string literal, size_t length);

void utils(void);

#endif /* MODC_MODULE_utils_H */
