/ 
Object-String-0.08
River stage zero No dependents
/ Object::String

NAME

Object::String - A string object for Perl 5

VERSION

version 0.08

DESCRIPTION

A string object for Perl 5.

Object::String have a lot of "modern" features and supports method chaining. A helper is also provided to help to build a string object.

Object::String is heavily inspired by stringjs a Ruby string object.

# Normal way to build a string object
my $string = Object::String->new(string => 'test');

# With the helper
my $string = str('test');

# Display the string
say $string->string;

# Method chaining 
say $string->chomp_right->to_upper->string;
say str('testZ')->chop_right->to_upper->string; # TEST

METHODS

string

Converts the object into a string scalar. Aliases: to_string

to_string

An alias to string

to_lower

Converts the string to lower case.

say str('TEST')->to_lower->string; # test

to_lower_first

Lower case the first letter of a string.

say str('TEST')->to_lower_first->string; # tEST

to_upper

Converts the string to upper case.

say str('test')->to_upper->string; # TEST

to_upper_first

Upper case the first letter of a string.

say str('test')->to_upper_first->string; # Test

capitalize

Capitalizes a string.

say str('TEST')->capitalize->string; # Test

length

Returns the length of a string.

say str('test')->length; # 4

ensure_left($prefix)

Ensures the string is beginning with $prefix.

say str('dir')->ensure_left('/')->string;   # /dir
say str('/dir')->ensure_left('/')->string;  # /dir

ensure_right($suffix)

Ensures the string is ending with $suffix.

say str('/dir')->ensure_right('/')->string;     # /dir/
say str('/dir/')->ensure_right('/')->string;    # /dir/

trim_left

Trim string from left.

say str("  \t test")->trim_left->string; # test

trim_right

Trim string from right.

say str("test \t   \t")->trim_right->string; # test

trim

Trim string from left and from right.

say str("\t  \ttest \t\t")->trim->string; # test

clean

Deletes unuseful whitespaces.

say str("This\t   \tis  \t a     \t test")->clean->string; # This is a test

Aliases: collapse_whitespace

collapse_whitespace

An alias to clean.

repeat($n)

Repeats a string n times. Aliases: times

say str('test')->repeat(3)->string; # testtesttest

times($n)

An alias to repeat.

starts_with($str)

Tests if the string starts with $str.

str('test')->starts_with('te');     # true
str('test')->starts_with('z');      # false

ends_with($str)

Tests if the string ends with $str.

str('test')->ends_with('st');   # true
str('test')->ends_with('z');    # false

contains($str)

Tests if the string contains $str. Aliases: include

str('test')->contains('es');    # true
str('test')->contains('z');     # false

include($str)

An alias to contains.

chomp_left

Chomp left the string. If the string begins by a space or a tab, it is removed.

chomp_right

Chomp right the string. Same as the Perl's chomp function.

chop_left

Deletes the first character of the string.

say str('test')->chop_left->string; # est

chop_right

Deletes the last character of the string. Same function as Perl's chop function.

say str('test')->chop_right->string; # tes

is_numeric

Tests if the string is composed by numbers.

str('123')->is_numeric;     # true
str('1.23')->is_numeric;    # false
str('ab1')->is_numeric;     # false

is_alpha

Tests if the string is composed by alphabetic characters.

str('abc')->is_alpha;       # true
str('a1b2c3')->is_alpha;    # false

is_alpha_numeric

Tests if the string is composed only by letters and numbers.

str('abc')->is_alpha_numeric;       # true
str('a1b2c3')->is_alpha_numeric;    # true
str('1.3e10')->is_alpha_numeric;    # false

is_lower

Tests if a string is lower case.

str('TEST')->is_lower; # false
str('test')->is_lower; # true

is_upper

Tests if the string is upper case.

str('TEST')->is_upper; # true
str('test')->is_upper; # false

to_boolean

Returns a boolean if the string is ON|OFF, YES|NO, TRUE|FALSE upper or lower case. Aliases: to_bool

str('on')->to_boolean;      # true
str('off')->to_boolean;     # false
str('yes')->to_boolean;     # true
str('no')->to_boolean;      # false
str('true')->to_boolean;    # true
str('false')->to_boolean;   # false
str('test')->to_boolean;    # undef

to_bool

An alias to to_boolean.

is_empty

Tests if a string is empty.

str('')->is_empty;          # true
str('   ')->is_emtpy;       # true
str("  \t\t  ")->is_empty;  # true
str("aaa")->is_empty;       # false

count($str)

Counts the occurrences of $str in the string.

say str('This is a test')->count('is'); # 2

left($count)

Returns a substring of $count characters from the left.

say str('This is a test')->left(3)->string;     # Thi
say str('This is a test')->left(-3)->string;    # est

right($count)

Returns a substring of $count characters from the right

say str('This is a test')->right(3)->string;    # est
say str('This is a test')->right(-3)->string;   # Thi

underscore

Converts the string to snake case. Aliases: underscored

say str('thisIsATest')->underscore->string;     # this_is_a_test
say str('ThisIsATest')->underscore->string;     # _this_is_a_test
say str('This::IsATest')->underscore->string;   # _this/is_a_test
say str('This Is A Test')->underscore->string;  # this_is_a_test

underscored

An alias to underscore.

dasherize

Converts the string to a dasherized one.

say str('thisIsATest')->dasherize->string;      # thisr-is-a-test
say str('ThisIsATest')->dasherize->string;      # -this-is-a-test
say str('This::IsATest')->dasherize->string;    # -this/is-a-test
say str('This Is A Test')->dasherize->string;   # this-is-a-test

camelize

Converts the string to a camelized one.

say str('this-is-a-test')->camelize->string;    # thisIsATest
say str('_this_is_a_test')->camelize->string;   # ThisIsATest
say str('_this/is/a-test')->camelize->string;   # This::Is::ATest
say str('this is a test')->camelize->string;    # thisIsATest

latinise

Removes accents from Latin characters.

say str('où es-tu en été ?')->latinise->string; # ou es-tu en ete ?

escape_html

Escapes some HTML entities : &"'<>

# &lt;h1&gt;l&#39;été sera beau &amp; chaud&lt;/h1&gt;
say str("<h1>l'été sera beau & chaud</h1>")->escape_html->string;

#&lt;h1&gt;entre &quot;guillemets&quot;&lt;/h1&gt;
say str('<h1>entre "guillemets"</h1>')->escape_html->string

unescape_html

Unescapes some HTML entities : &"'<>

index_left($substr, $position)

Searches for a substring within another from a position. If $position is not specified, it begins from 0.

say str('this is a test')->index_left('is');        # 2
say str('this is a test')->index_right('is', 3);    # 5

index_right($substr, $position)

Searches from right for a substring within another from a position. If $position is not specified, it begins from 0.

say str('this is a test')->index_right('is');       # 5
say str('this is a test')->index_right('is', 5);    # 2

replace_all($substr1, $substr2)

Replaces all occurrences of a substring within the string.

say str('This is a test')->replace_all(' ', '_'); # this_is_a_test

humanize

Transforms the input into a human friendly form.

say str('-this_is a test')->humanize->string; # This is a test

pad_left($count, $char)

Pad left the string with $count $char.

say str('hello')->pad_left(3)->string;          # hello
say str('hello')->pad_left(5)->string;          # hello
say str('hello')->pad_left(10)->string;         #      hello
say str('hello')->pad_left(10, '.')->string;    # .....hello

pad_right($count, $char)

Pad right the string with $count $char.

say str('hello')->pad_right(3)->string;         # hello
say str('hello')->pad_right(5)->string;         # hello
say str('hello')->pad_right(10)->string;        # "hello     "
say str('hello')->pad_left(10, '.')->string;    # hello.....

pad($count, $char)

Pad the string with $count $char.

say str('hello')->pad(3)->string;       # hello
say str('hello')->pad(5)->string;       # hello
say str('hello')->pad(10)->string;      # "   hello  "
say str('hello')->pad(10, '.')->string; # ...hello..

next

Increments the string.

say str('a')->next->string; # b
say str('z')->next->string; # aa

slugify

Transfoms the input into an url slug.

say str('En été, il fera chaud')->slugify->string; # en-ete-il-fera-chaud

strip_punctuation

Strips punctuation from the string.

say str('this. is, %a (test)'); # this is a test

swapcase

Swaps the case of the string.

say str('TeSt')->swapcase->string; # tEsT

concat($str1, ...)

Concats multiple strings. Aliases: suffix

say str('test')->concat('test')->string;            # testtest
say str('test')->concat('test', 'test')->string;    # testtesttest

suffix($str1, ...)

An alias to concat.

prefix($str1, ...)

Prefix the string with $str1, ...

say str('test')->prefix('hello')->string;   # hellotest
say str('test')->prefix('hello', 'world');  # helloworldtest

reverse

Reverses a string.

say str('test')->reverse->string; # tset

count_words

Counts the words in a string.

say str("this\tis a \t test")->count_words; # 4

quote_meta

Quotes meta characters.

# hello\ world\.\ \(can\ you\ hear\ me\?\)
say str('hello world. (can you hear me?)')->quote_meta->string;

rot13

ROT13 transformation on the string.

say str('this is a test')->rot13->string;           # guvf vf n grfg
say str('this is a test')->rot13->rot13->string;    # this is a test

say

Says the string.

str('this is a test')->say; # displays "this is a test\n"

titleize

Strips punctuation and capitalizes each word. Aliases: titlecase

say str('this is a test')->titleize->string; # This Is A Test

titlecase

An alias to titleize.

str

Creates and returns a string object.

str("test")->string                     # test
str("test")->to_upper->string           # TEST
str('this', 'is', 'a', 'test')->string; # this is a test

AUTHOR

Vincent BERZIN <berzinv@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Vincent BERZIN.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.