index/src/Data/IDbResult.php

<?php
// IDbResult.php
// Created: 2021-05-02
// Updated: 2024-02-06

namespace Index\Data;

use Index\ICloseable;
use Index\IO\Stream;

/**
 * Represents a database result set.
 */
interface IDbResult extends ICloseable {
    /**
     * Fetches the next result set.
     *
     * @return bool true if the result set was loaded, false if no more results are available.
     */
    function next(): bool;

    /**
     * Checks if a given index has a NULL value.
     *
     * @param int|string $index Target index.
     * @return bool true if the value is null, false if not.
     */
    function isNull(int|string $index): bool;

    /**
     * Gets the value from the target index without any additional casting.
     *
     * @param int|string $index Target index.
     * @return mixed Target value.
     */
    function getValue(int|string $index): mixed;

    /**
     * Gets the value from the target index cast as a native string.
     *
     * @param int|string $index Target index.
     * @return string Returns a string of the value.
     */
    function getString(int|string $index): string;

    /**
     * Checks if the field is null, then gets the value from the target index cast as a native string.
     *
     * @param int|string $index Target index.
     * @return ?string Returns a string of the value or null.
     */
    function getStringOrNull(int|string $index): ?string;

    /**
     * Gets the value from the target index cast as an integer.
     *
     * @param int|string $index Target index.
     * @return int Returns the value cast to an integer.
     */
    function getInteger(int|string $index): int;

    /**
     * Checks if the field is null, then gets the value from the target index cast as an integer.
     *
     * @param int|string $index Target index.
     * @return int Returns the value cast to an integer or null.
     */
    function getIntegerOrNull(int|string $index): ?int;

    /**
     * Gets the value from the target index cast as a floating point number.
     *
     * @param int|string $index Target index.
     * @return float Returns the value cast to a floating point number.
     */
    function getFloat(int|string $index): float;

    /**
     * Checks if the field is null, then gets the value from the target index cast as a floating point number.
     *
     * @param int|string $index Target index.
     * @return float Returns the value cast to a floating point number or null.
     */
    function getFloatOrNull(int|string $index): ?float;

    /**
     * Gets the value from the target index cast as a boolean value.
     *
     * @param int|string $index Target index.
     * @return bool Returns the value cast to a boolean value.
     */
    function getBoolean(int|string $index): bool;

    /**
     * Checks if the field is null, then gets the value from the target index cast as a boolean value.
     *
     * @param int|string $index Target index.
     * @return ?bool Returns the value cast to a boolean value or null.
     */
    function getBooleanOrNull(int|string $index): ?bool;

    /**
     * Gets the value from the target index as a Stream.
     *
     * @param int|string $index Target index.
     * @return ?Stream A Stream if data is available, null if not.
     */
    function getStream(int|string $index): ?Stream;

    /**
     * Creates an iterator for this result.
     *
     * @param callable(IDbResult): object $construct Result info constructor.
     * @return DbResultIterator Result iterator.
     */
    function getIterator(callable $construct): DbResultIterator;
}