rosavox/lib/alveolata/string/functions.php

<?php

namespace alveolata\string;

// require_once(DIR_ALVEOLATA . '/definitions.php');


/**
 * @author Christian Fraß <frass@greenscale.de>
 */
class _state {
    
    /**
     * @var int
     */
    public static $generateCounters = [];
    
    
    /**
     * @var string
     */
    public static $generatePattern = '{{context}}-{{number}}';
    
}


/**
 * splits a string into pieces according to a given delimiter
 * 
 * @param string $subject
 * @param string $delimiter
 * @param int $limit
 * @return array {list<string>}
 * @author Christian Fraß <frass@greenscale.de>
 */
function split(
	string $subject,
	string $delimiter,
	int $limit = UNSET_INTEGER
) : array
{
	if (empty($subject)) {
		return [];
	}
	else {
		if ($limit === UNSET_INTEGER) {
			return \explode($delimiter, $subject);
		}
		else {
			return \explode($delimiter, $subject, $limit);
		}
	}
}


/**
 * connects string pieces together according to a given delimiter
 * 
 * @param array $parts {list<string>}
 * @param string $delimiter
 * @return string
 * @author Christian Fraß <frass@greenscale.de>
 */
function join(
	array $parts,
	string $delimiter
) : string
{
	return implode($delimiter, $parts);
}


/**
 */
function starts_with(
	string $subject,
	string $part
) : bool
{
	if (empty($part)) {
		return true;
	}
	else {
		return (strpos($subject, $part) === 0);
	}
}


/**
 */
function ends_with(
	string $subject,
	string $part
) : bool
{
	if (empty($part)) {
		return true;
	}
	else {
		return (strrpos($subject, $part) === (strlen($subject) - strlen($part)));
	}
}


/**
 * @see https://www.php.net/manual/en/function.str-contains.php
 */
function contains(
	string $subject,
	string $part
) : bool
{
	return \str_contains($subject, $part);
}


/**
 * @param array $replacments {map<string,string>}
 * @author Christian Fraß <frass@greenscale.de>
 */
function replace(
	string $string,
	array $replacements
) : string
{
	$result = $string;
	foreach ($replacements as $from => $to) {
		str_replace($result, $from, $to);
	}
	return $result;
}


/**
 * @param string $template
 * @param map<string,any> [$arguments]
 * @param string $open left delimiter for placeholder
 * @param string $close right delimiter for placeholder
 * @return string
 * @author Christian Fraß <frass@greenscale.de>
 */
function coin(
	string $template,
	array $arguments = [],
	string $open = '{{',
	string $close = '}}'
) : string
{
	$result = $template;
	foreach ($arguments as $key => $value) {
		$pattern = ($open . $key . $close);
		$replacement = strval($value);
		$result = str_replace($pattern, $replacement, $result);
	}
	return $result;
}


/**
 * @param string $core
 * @param int $length
 * @param string $filler
 * @return string
 * @author Christian Fraß <frass@greenscale.de>
 */
function pad_right(
	string $core,
	int $length,
	string $filler
) : string
{
	return str_pad($core, $length, $filler, STR_PAD_RIGHT);
}


/**
 * @param string $string
 * @return string
 * @author Christian Fraß <frass@greenscale.de>
 */
function case_upper(
	string $string
) : string
{
	return strtoupper($string);
}


/**
 * @param string $string
 * @param int $length the maximum length
 * @param string $ellipsis how to finish a too long string
 * @return string
 * @author Christian Fraß <frass@greenscale.de>
 */
function limit(
	string $string,
	int $length,
	string $ellipsis = ' …'
) : string
{
	$use_mb = (function_exists('mb_strlen') && function_exists('mb_substr'));
	$length_string = ($use_mb ? \mb_strlen($string) : \strlen($string));
	$length_ellipsis = ($use_mb ? \mb_strlen($ellipsis) : \strlen($ellipsis));
	return (
		($length_string <= $length)
		? $string
		: (
			$use_mb
			? (\mb_substr($string, 0, $length - $length_ellipsis) . $ellipsis)
			: (\substr($string, 0, $length - $length_ellipsis) . $ellipsis)
		)
	);
}


/**
 * @return string
 * @author Christian Fraß <frass@greenscale.de>
 */
function generate(
    string $context = 'common'
) : string
{
    if (! array_key_exists($context, _state::$generateCounters)) {
        _state::$generateCounters[$context] = 0;
    }
    $string = _state::coin(
        _state::$generatePattern,
        [
            'context' => $context,
            'number' => sprintf('%d', _state::$generateCounters[$context]),
        ]
    );
    _state::$generateCounters[$context] += 1;
    return $string;
}


/**
 * removes the UTF-8 byte order mark from a string
 */
function remove_bom(
	string $input
) : string
{
	return \preg_replace('/x{EF}x{BB}x{BF}/', '', $input);
}

 ?>