<?php
/**
 * String Helper Class
 *
 * @version     1.0.$Revision:$
 * @version     SVN: $Id:$
 * @package     bplan-base/globals
 * @subpackage  Helpers
 * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
 * @copyright   Copyright (C) 2025, 2026 bplan-solutions GmbH & Co. KG <https://www.bplan-solutions.de/>
 * /Δ\
 */

namespace BplanBase\Globals\Helpers;


use BplanBase\Globals\Enums\CaseStyle;
use BplanBase\Globals\Enums\Number;
use BplanBase\Globals\Support\Str;


/**
 * String Helper Class
 *
 * @version     8.1.0 / 2026-05-11
 * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
 */
class StringHelper
{


/* +++ TRAITS +++ +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ */


/* +++ CLASS CONSTANTS +++ ++++++++++++++++++++++++++++++++++++++++++++++++++ */


    /**
     * @deprecated  Use BplanBase\Globals\Support\Str::DISTINCTIVE_LETTERS instead
     * @var     string
     */
    public const DISTINCTIVE_LETTERS = 'ACDEFGHJKMNPQRTUVWXYZ';


/* +++ OBJECT MEMBERS +++ +++++++++++++++++++++++++++++++++++++++++++++++++++ */


/* +++ CLASS MEMBERS +++ ++++++++++++++++++++++++++++++++++++++++++++++++++++ */


/* +++ OBJECT METHODS +++ +++++++++++++++++++++++++++++++++++++++++++++++++++ */


/* +++ CLASS METHODS +++ ++++++++++++++++++++++++++++++++++++++++++++++++++++ */


    /**
     *
     * @deprecated  Use BplanBase\Globals\Support\Str::bytesToHuman() instead
     *
     * @param       integer $bytes
     *
     * @param       integer $precision
     *
     * @return      string
     *
     * @version     1.0.0 / 2026-04-05
     * @author      Emilio Cannarozzo <emilio.cannarozzo@bplan-solutions.de>
     */
    public static function bytesToHuman(int $bytes, int $precision = 2): string
    {
        return Str::bytesToHuman($bytes, $precision);

    } // bytesToHuman()


    /**
     * Extrahiert die Ländervorwahl aus einer Telefonnummer
     *
     * Als Eingabe wird eine normalisierte Telefonnummer mit führendem Pluszeichen (z.B. +491638441315) erwartet.
     *
     * @deprecated  Use BplanBase\Globals\Support\Str::explodePhoneNumber() instead
     *
     * @param       null|string $phoneNumber
     *
     * @param       mixed $returnOnEmpty
     *
     * @return      mixed Liefert im Normalfall einen Array mit den Schlüsseln "country-code" und "phone-number".
     *              Die Werte entsprechen den Einzelteilen der übergebenen Telefonnummer oder NULL.
     *
     * @version     1.0.1 / 2025-04-16
     * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
     */
    public static function explodePhoneNumber(null|string $phoneNumber, mixed $returnOnEmpty = '#Array#'): mixed
    {
        return Str::explodePhoneNumber($phoneNumber, $returnOnEmpty);

    } // explodePhoneNumber()


    /**
     *
     * @deprecated  Use BplanBase\Globals\Support\Str::formatPhoneNumber() instead
     *
     * @param       string $number
     *
     * @param       string $defaultRegion
     *
     * @return      string|null
     *
     * @version     1.0.0 / 2026-03-15
     * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
     */
    public static function formatPhoneNumber(string $number, string $defaultRegion = 'DE'): ?string
    {
        return Str::formatPhoneNumber($number, $defaultRegion);

    } // formatPhoneNumber()


    /**
     *
     * @deprecated  Use BplanBase\Globals\Support\Str::getRandomChars() instead
     *
     * @param       integer $length
     *
     * @param       string $pool
     *
     * @return      string
     *
     * @version     1.0.1 / 2026-05-11
     * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
     */
    public static function getRandomChars(int $length, string $pool = self::DISTINCTIVE_LETTERS): string
    {
        return Str::getRandomChars($length, $pool);

    } // getRandomChars()


    /**
     * Normalisiert die übergebene E-Mail-Adresse
     *
     * @deprecated  Use BplanBase\Globals\Support\Str::normalizeEmail() instead
     *
     * @param       null|string $email
     *
     * @param       mixed $returnOnEmpty
     *
     * @return 	    mixed
     *              Liefert die bereinigte E-Mail-Adresse in Kleinschreibung oder im Fehlerfall NULL
     *              beziehungsweise den übergebenen Return-Wert.
     *
     * @version     1.0.0 / 2025-03-18
     * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
     */
    public static function normalizeEmail(null|string $email, mixed $returnOnEmpty = null): mixed
    {
        return Str::normalizeEmail($email, $returnOnEmpty);

    } // normalizeEmail()


    /**
     * Normalisiert das übergebene KFZ-Kennzeichen
     *
     * Entfernt alle nicht-alphanumerischen Zeichen aus der übergebenen Zeichenkette.
     *
     * @deprecated  Use BplanBase\Globals\Support\Str::normalizeLicensePlate() instead
     *
     * @param       null|string $licensePlate
     *
     * @param       mixed $returnOnEmpty
     *
     * @return 	    mixed
     *              Liefert das bereinigte KFZ-Kennzeichen in Großschreibung oder im Fehlerfall NULL
     *              beziehungsweise den übergebenen Return-Wert.
     *
     * @version     1.0.0 / 2025-03-18
     * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
     */
    public static function normalizeLicensePlate(null|string $licensePlate, mixed $returnOnEmpty = null): mixed
    {
        return Str::normalizeLicensePlate($licensePlate, $returnOnEmpty);

    } // normalizeLicensePlate()


    /**
     * Normalisiert einen gegebenen Pfad
     *
     * Im übergebenen Pfad werden Backslashes (\) durch Forwardslashes (/) ersetzt.
     * Außerdem werden abschließende Forwardslashes entfernt.
     *
     * @deprecated  Use BplanBase\Globals\Support\Str::normalizePath() instead
     *
     * @param       string $path
     *
     * @return      string
     *
     * @version     1.0.0 / 2025-08-16
     * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
     */
    public static function normalizePath(string $path): string
    {
        return Str::normalizePath($path);

    } // normalizePath()


    /**
     * Normalisiert die übergebene Telefonnummer
     *
     * Entfernt alle nicht-numerischen Zeichen außer dem führenden Pluszeichen (+).
     *
     * @deprecated  Use BplanBase\Globals\Support\Str::normalizePhoneNumber() instead
     *
     * @param       null|string $phoneNumber
     *              Erwartet eine vollständige Telefonnummer mit führendem Pluszeichen (+) oder
     *              vorangestellten Doppelnullen (00).
     *
     * @param       mixed $returnOnEmpty
     *
     * @return      mixed
     *              Liefert die bereinigte Telefonnummer mit führendem Pluszeichen oder im Fehlerfall
     *              NULL beziehungsweise den übergebenen Return-Wert.
     *
     * @version     1.0.0 / 2025-03-18
     * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
     */
    public static function normalizePhoneNumber(null|string $phoneNumber, mixed $returnOnEmpty = null): mixed
    {
        return Str::normalizePhoneNumber($phoneNumber, $returnOnEmpty);

    } // normalizePhoneNumber()


    /**
     *
     * @deprecated  Use BplanBase\Globals\Support\Str::reformat() instead
     *
     * @param       string $string
     *
     * @param       CaseStyle|null $CaseStyle
     *              Steuert die Schreibweise des zurückgegebenen Werts.
     *              Beispiele anhand der Zeichenketten "deleted_at", "mainUser", "user-role":
     *
     *                  Parameter       Rückgaben
     *                  camel       >   deletedAt   /   mainUser    /   userRole
     *                  lower       >   deletedat   /   mainuser    /   user-role
     *                  slug        >   deleted-at  /   main-user   /   user-role
     *                  snake       >   deleted_at  /   main_user   /   user_role
     *                  studly      >   DeletedAt   /   MainUser    /   UserRole
     *                  upper       >   DELETED_AT  /   MAINUSER    /   USERROLE
     *
     * @param       Number|null $Number
     *              Der grammatikalische Numerus "plural" oder "singular".
     *
     * @return      string
     *
     * @version     1.0.0 / 2025-05-25
     * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
     */
    public static function reformat(string $string, CaseStyle|null $CaseStyle = null, Number|null $Number = null): string
    {
        return Str::reformat($string, $CaseStyle, $Number);

    } // reformat()


    /**
     * Entfernt einen BOM-Header (Byte Order Mark) vom Anfang der Zeichenkette
     *
     * @deprecated  Use BplanBase\Globals\Support\Str::removeBomHeader() instead
     *
     * @param       string $string
     *
     * @return      string
     *
     * @version     1.0.0 / 2026-03-30
     * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
     */
    public static function removeBomHeader(string $string): string
    {
        return Str::removeBomHeader($string);

    } // removeBomHeader()


    /**
     *
     * @deprecated  Use BplanBase\Globals\Support\Str::unifyLineBreaks() instead
     *
     * @param       string $string
     *
     * @param       string $lineBreak
     *              Der Zeilenumbruch, der verwendet werden soll (Standard: "\n").
     *
     * @param       bool $removeEmptyLines
     *              Standardmäßig werden doppelte Zeilenumbrüche entfernt, so dass
     *              das Ergebnis keine leeren Zeilen enthält. Mit diesem Parameter
     *              kann die Standardarbeitsweise deaktiviert werden.
     *
     * @return      string
     *
     * @version     1.0.0 / 2025-05-11
     * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
     */
    public static function unifyLineBreaks(string $string, string $lineBreak = "\n", bool $removeEmptyLines = true): string
    {
        return Str::unifyLineBreaks($string, $lineBreak, $removeEmptyLines);

    } // unifyLineBreaks()


} // class StringHelper {}
