<?php
// IString.php
// Created: 2021-06-20
// Updated: 2022-02-27

namespace Index;

use ArrayAccess;
use Countable;
use IteratorAggregate;
use JsonSerializable;
use Stringable;
use Index\Serialisation\IBencodeSerialisable;

interface IString extends ArrayAccess, Countable, IteratorAggregate, JsonSerializable, Stringable, IComparable, ICloneable, IEquatable, IBencodeSerialisable {
    /**
     * Default trim characters.
     *
     * @var string
     */
    const TRIM_CHARS = " \n\r\t\v\0";

    /**
     * Gets the length of the string.
     *
     * @return int Length of the string.
     */
    function getLength(): int;

    /**
     * Returns whether the string is empty.
     *
     * @return bool true if the string is empty, false if not.
     */
    function isEmpty(): bool;

    /**
     * Returns the index of a substring.
     *
     * @see https://www.php.net/manual/en/function.strpos
     * @param IString|string $text Substring to look for.
     * @param int $offset Offset from which to start looking.
     * @return int Offset at which the substring can be found, -1 if the substring can't be found.
     */
    function indexOf(IString|string $text, int $offset = 0): int;

    /**
     * Checks whether the string contains a substring.
     *
     * @see https://www.php.net/manual/en/function.str-contains
     * @param IString|string $text Substring to look for.
     * @return bool true if it could be found, false if not.
     */
    function contains(IString|string $text): bool;

    /**
     * Returns a ranged substring.
     *
     * @see https://www.php.net/manual/en/function.substr
     * @param int $offset Offset from which to start.
     * @param int|null $length Amount of character to copy, null for the remainder of the string.
     * @return IString An instance of IString containing the substring.
     */
    function substring(int $offset, int|null $length = null): IString;

    /**
     * Checks if a string starts with a given substring.
     *
     * @see https://www.php.net/manual/en/function.str-starts-with
     * @param IString|string $text The substring to check for.
     * @return bool true if the substring was found, false if not.
     */
    function startsWith(IString|string $text): bool;

    /**
     * Checks if a string ends with a given substring.
     *
     * @see https://www.php.net/manual/en/function.str-ends-with
     * @param IString|string $text The substring to check for.
     * @return bool true if the substring was found, false if not.
     */
    function endsWith(IString|string $text): bool;

    /**
     * Replace a substring with another substring.
     *
     * @see https://www.php.net/manual/en/function.str-replace
     * @param IString|string $search Substring that should be replaced.
     * @param IString|string $replace Replacement values for what was found with search.
     * @return IString A new IString instance with the replaced values.
     */
    function replace(IString|string $search, IString|string $replace): IString;

    /**
     * Concatenates two strings with this one in the first position.
     *
     * @param IString|string $string String that should be appended.
     * @return IString A new IString instance with the combined value.
     */
    function append(IString|string $string): IString;

    /**
     * Concatenates two strings with this one in the last position.
     *
     * @param IString|string $string String that should be prepended.
     * @return IString A new IString instance with the combined value.
     */
    function prepend(IString|string $string): IString;

    /**
     * Split a string by a separator string into an array.
     *
     * Calling split with an empty string will not work, use ->chunk(1) instead.
     *
     * @see https://www.php.net/manual/en/function.explode
     * @param IString|string $separator The boundary string.
     * @param int $limit Maximum number of elements expected in the array.
     * @return array The resulting array of substrings.
     */
    function split(IString|string $separator, int $limit = PHP_INT_MAX): array;

    /**
     * Splits a string in substring chunks of a given length.
     *
     * @see https://www.php.net/manual/en/function.str-split.php
     * @param int $chunkSize Maximum length of a chunk.
     * @return array The resulting array of substrings.
     */
    function chunk(int $chunkSize): array;

    /**
     * Strip whitespace or other characters from the beginning and end of a string.
     *
     * @see https://www.php.net/manual/en/function.trim
     * @param IString|string $characters Characters to strip.
     * @return IString A new instance of IString with the characters removed.
     */
    function trim(IString|string $characters = self::TRIM_CHARS): IString;

    /**
     * Strip whitespace or other characters from the beginning of a string.
     *
     * @see https://www.php.net/manual/en/function.ltrim.php
     * @param IString|string $characters Characters to strip.
     * @return IString A new instance of IString with the characters removed.
     */
    function trimStart(IString|string $characters = self::TRIM_CHARS): IString;

    /**
     * Strip whitespace or other characters from the end of a string.
     *
     * @see https://www.php.net/manual/en/function.rtrim.php
     * @param IString|string $characters Characters to strip.
     * @return IString A new instance of IString with the characters removed.
     */
    function trimEnd(IString|string $characters = self::TRIM_CHARS): IString;

    /**
     * Convert string to lowercase.
     *
     * @see https://www.php.net/manual/en/function.strtolower.php
     * @return IString A new IString instance with all lowercase characters.
     */
    function toLower(): IString;

    /**
     * Convert string to uppercase.
     *
     * @see https://www.php.net/manual/en/function.strtoupper.php
     * @return IString A new IString instance with all uppercase characters.
     */
    function toUpper(): IString;

    /**
     * Reverses a string.
     *
     * @see https://www.php.net/manual/en/function.strrev
     * @return IString A new IString instance containing the reversed string.
     */
    function reverse(): IString;

    /**
     * Returns a copy of the standard PHP string.
     *
     * @return string PHP string.
     */
    function __toString(): string;
}