core/string.lib.php File Reference

String utility functions. More...

Go to the source code of this file.

Functions

str_contains ($str, $substring)

Test if a string contains the specified substring.

str_is_whitespace ($str)

Test if a string consists of whitespace characters only.

str_has_prefix ($str, $prefix)

Test if a string starts with the specified prefix.

str_has_whitespace_prefix ($str)

Test if a string starts with whitespace.

str_has_suffix ($str, $suffix)

Test if a string ends with the specified suffix.

str_has_whitespace_suffix ($str)

Test if a string starts with whitespace.

str_strip_suffix ($str, $suffix)

Strip a suffix from a string.

str_strip_prefix ($str, $prefix)

Strip a prefix from a string.

str_truncate ($str, $length=70, $trail='...', $use_word_boundaries=true)

Truncate a string to a given length, optionally adding a trailing suffix.

str_first_non_white ($list=null)

Return the first non-whitespace value from a list of strings.

str_all_non_white ($list=null)

Return all non-whitespace values from a list of strings.

str_join_wrap ($str, $width=null)

Strip leading whitespace from a multiline string and word wrap the string at the given line length.

str_amputate ($str)

Convert ampersands in a string to the corresponding XML entity.

to_string ($args)

Render various objects to a string.

Detailed Description

String utility functions.

Definition in file core/string.lib.php.

Function Documentation

str_contains	(	$	str,
		$	substring
	)

Test if a string contains the specified substring.

Use strpos or other string functions if you want to know where the substring starts.

Parameters:

	$str	The string to search in.
	$substring	The substring to find in $str.

Returns:: True if $str contains $substring, false otherwise.

Definition at line 31 of file core/string.lib.php.

str_is_whitespace ( $ str )

Test if a string consists of whitespace characters only.

Parameters:

$str

The string to test.

Returns:: True if $str contains only whitespace, false otherwise.

Definition at line 52 of file core/string.lib.php.

str_has_prefix	(	$	str,
		$	prefix
	)

Test if a string starts with the specified prefix.

Parameters:

	$str	The string to search in.
	$prefix	The prefix to match against $str.

Returns:: True if $str starts with $needle, false otherwise.

See also:: str_has_suffix

Definition at line 72 of file core/string.lib.php.

str_has_whitespace_prefix ( $ str )

Test if a string starts with whitespace.

Parameters:

$str

The string to test.

Returns:: True if $str starts with whitespace, false otherwise.

See also:: str_has_prefix

Definition at line 94 of file core/string.lib.php.

str_has_suffix	(	$	str,
		$	suffix
	)

Test if a string ends with the specified suffix.

Parameters:

	$str	The string to search in.
	$suffix	The suffix to match against $str.

Returns:: True if $str ends with $suffix, false otherwise.

See also:: str_has_prefix

Definition at line 118 of file core/string.lib.php.

str_has_whitespace_suffix ( $ str )

Test if a string starts with whitespace.

Parameters:

$str

The string to test.

Returns:: True if $str starts with whitespace, false otherwise.

See also:: str_has_suffix

Definition at line 145 of file core/string.lib.php.

str_strip_suffix	(	$	str,
		$	suffix
	)

Strip a suffix from a string.

If the string didn't end with the given suffix, this function is a no-op: the string is returned unaltered.

Parameters:

	$str	The string to operate on.
	$suffix	The suffix to remove.

Returns:: A string with the suffix removed, if found.

Definition at line 171 of file core/string.lib.php.

str_strip_prefix	(	$	str,
		$	prefix
	)

Strip a prefix from a string.

If the string didn't start with the given prefix, this function is a no-op: the string is returned unaltered.

Parameters:

	$str	The string to operate on.
	$prefix	The prefix to remove.

Returns:: A string with the prefix removed, if found.

Definition at line 203 of file core/string.lib.php.

str_truncate	(	$	str,
		$	length = `70`,
		$	trail = `'...'`,
		$	use_word_boundaries = `true`
	)

Truncate a string to a given length, optionally adding a trailing suffix.

The trail can be used to indicate that the string was truncated (e.g. an ellipsis). The resulting string is guaranteed to be no longer than the $length specified, so even with huge words you can safely use the result in places where you don't have much space, e.g. intro text boxes on websites, text in a textfile and database records.

This function is heavily inspired by the smarty_modifier_truncate() function written by Monte Ohrt <monte@ohrt.com> for the Smarty Template Engine, which is released under the LGPL. This function differs in some ways (e.g. the resulting string is never longer than the specified $length, the $middle parameter is not available and default values are different). In short, this version rocks harder!

Parameters:

	$str	The string to operate on.
	$length	A number indicating the maximum length the resulting string can have. This parameter is optional and defaults to 70. You can provide null if you want to provide additional parameters without specifying an explicit value.
	$trail	A string that is appended at the resulting string, but only if the original needed truncating.
	$use_word_boundaries	If true, strings are truncated only at word boundaries. This parameter is optional and defaults to true. Note that in case no suitable word boundary was found, the string will be truncated without respecting word boundaries!

Returns:: The resulting string after truncating and addition of the trail.

Definition at line 258 of file core/string.lib.php.

str_first_non_white ( $ list = null )

Return the first non-whitespace value from a list of strings.

Parameters:

$list

One ore more string parameters (or a single array).

Returns:: The first non-whitespace string or the empty string if no non-whitespace strings where found.

See also:: str_all_non_white

Definition at line 322 of file core/string.lib.php.

str_all_non_white ( $ list = null )

Return all non-whitespace values from a list of strings.

This function returns a new array; the original array is left untouched.

Parameters:

$list

One ore more string parameters (or a single array).

Returns:: An array containing all non-whitespace values (this can be an empty array).

See also:: str_first_non_white

Definition at line 359 of file core/string.lib.php.

str_join_wrap	(	$	str,
		$	width = `null`
	)

Strip leading whitespace from a multiline string and word wrap the string at the given line length.

Whitespace before and after line breaks is reduced to a single space. This function can be used to fixup indented multiline strings.

Parameters:

	$str	The string to operate on.
	$width	Width of the wrapped text (optional, defaults to 70).

Returns:: The wordwrapped string.

Definition at line 401 of file core/string.lib.php.

str_amputate ( $ str )

Convert ampersands in a string to the corresponding XML entity.

Existing entities in the string are left untouched, so you won't end up with things like &eacute; or other entities. You can use this function to prepare strings for inclusion in HTML or XML documents.

This function uses the regular expression from Amputator (http://bumppo.net/projects/amputator/), written by Nat Irons.

Parameters:

$str

The string to operate on.

Returns:: A string with all standalone &-signs replaced by entities.

Definition at line 429 of file core/string.lib.php.

to_string ( $ args )

Render various objects to a string.

This function creates a string from various types of objects by applying various conversion methods. Supported data types:

Simple values: strings, integers, floats, boolean (0 or 1).
Any object implementing a render(), to_xhtml(), to_string() or toString() method.
Numerical arrays containing any of the supported types are recursively converted to string values, separated by newlines.

An error is thrown if the passed object cannot be handled.

Parameters:

$args

Any value supported by this function. You can also pass multiple parameters.

Returns:: String representation of the renderered object.

Definition at line 459 of file core/string.lib.php.


Functions
	str_contains ($str, $substring)
	Test if a string contains the specified substring.
	str_is_whitespace ($str)
	Test if a string consists of whitespace characters only.
	str_has_prefix ($str, $prefix)
	Test if a string starts with the specified prefix.
	str_has_whitespace_prefix ($str)
	Test if a string starts with whitespace.
	str_has_suffix ($str, $suffix)
	Test if a string ends with the specified suffix.
	str_has_whitespace_suffix ($str)
	Test if a string starts with whitespace.
	str_strip_suffix ($str, $suffix)
	Strip a suffix from a string.
	str_strip_prefix ($str, $prefix)
	Strip a prefix from a string.
	str_truncate ($str, $length=70, $trail='...', $use_word_boundaries=true)
	Truncate a string to a given length, optionally adding a trailing suffix.
	str_first_non_white ($list=null)
	Return the first non-whitespace value from a list of strings.
	str_all_non_white ($list=null)
	Return all non-whitespace values from a list of strings.
	str_join_wrap ($str, $width=null)
	Strip leading whitespace from a multiline string and word wrap the string at the given line length.
	str_amputate ($str)
	Convert ampersands in a string to the corresponding XML entity.
	to_string ($args)
	Render various objects to a string.