^Status|Draft|
^Todo|Proof read|

====== Text Helper ======

Provides methods for working with Text.

===== Methods =====

==== limit_words() ====

''text::limit_words()'' accepts multiple parameters. Only the input **string** is required.
The default end character is the ellipsis.

<code php>
$long_description = 'The rain in Spain falls mainly in the plain';
$limit = 4;
$end_char = '&nbsp;';

$short_description = text::limit_words($long_description, $limit, $end_char);
</code>

Generates:

  The rain in Spain


==== limit_chars() ====

''text::limit_chars()'' accepts multiple parameters. Only the input **string** is required.
The default end character is the ellipsis.

<code php>
$long_description = 'The rain in Spain falls mainly in the plain';
$limit = 4;
$end_char = '&amp;nbsp;';
$preserve_words = FALSE;

$short_description = text::limit_chars($long_description, $limit, $end_char, $preserve_words);
</code>

Generates:

  The r


==== alternate() ====

''text::alternate()'' accepts multiple parameters. The number of parameters determines the alternation. This is handy if you loop through something and you for example want to alternate the color of a table row. 

<code php>
for($i=0:$i<5:$i++)
{
    echo text::alternate('1','2','boom'); 
}
//returns 12boom12

</code>


==== random() ====

''text::random()'' accepts multiple optional parameters.
Returns a random text string of specified length.

Possible values for $type are:
  * ''alnum'' - 0-9, a-z and A-Z
  * ''alpha'' - a-z, A-Z
  * ''numeric'' - 0-9
  * ''nozero'' - 1-9
  * ''distinct'' - Only distinct characters that can't be mistaken for others.
  * For values that don't match any of the above, the characters passed in will be used.

<code php>
echo text::random($type = 'alnum', $length = 10);
</code>


==== reduce_slashes() ====

''text::reduce_slashes()'' reduces multiple slashes in a string to single slashes.
<code php>
<?php
$str = "path/to//something";
echo reduce_slashes($str); // Outputs: path/to/something
?>
</code>


==== censor() ====

''text::censor()'' accepts multiple optional parameters. The input string and an array of marker
words is required.
Returns a string with the marker words censored by the specified replacement character.

<code php>
$str = 'The income tax is a three letter word, but telemarketers are scum.';
$replacement = '*';
$badwords = array('tax', 'scum');

echo text::censor($str, $badwords, $replacement, $replace_partial_words = FALSE);
</code>

Generates:

  The income *** is a three letter word, but telemarketers are ****.


==== similar() ====

Finds the text that is similar between a set of words.


==== auto_link() ====

Converts text email addresses and anchors into links.


==== auto_link_urls() ====

Converts text anchors into links.


==== auto_link_emails() ====

Converts text email addresses into links.


==== bytes() ====

''text::bytes($bytes,$force_unit,$format,$si)'' Returns a human readable size.
  * $bytes - Supply the number of bites
  * $force_unit - defaults to NULL when supplied the function will return in those units.
  * $format - format of the return string
  * $si - Defaults to TRUE, when FALSE function will return IEC prefixes (KiB, MiB etc.) else will return SI prefixes (kB, MB, GB etc)


<code php>
echo text::bytes('2048'); //returns 2.05 kB
echo text::bytes('4194304','kB'); //returns 4194.30 kB
echo text::bytes('4194304','GiB'); //returns 0.00 GiB
echo text::bytes('4194304',NULL, NULL, FALSE); //returns 4.00 MiB
</code>


==== widont() ====

''text::widont()'' Returns a string without widow words by inserting a non-breaking space between the last two words. A widow word is a single word at the end of a paragraph on a new line. It's considered bad style.
  * $string - String with potential widow words

<code php>
$paragraph='Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Cras id dolor. Donec ...';

$paragraph=text::widont($paragraph);
</code>

==== auto_p() ====
Automatically applies <p> and <br /> markup to text. Basically nl2br() on steroids.