The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Object-String-0.11
River stage zero No dependents
4 ++
/ Object::String

NAME

Object::String - A string object for Perl 5

VERSION

version 0.11

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. If $char is not specified, a space is used.

    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. If $char is not specified, a space is used.

    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. If $char is not specified, a space is used.

    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')->string;  # 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.

squeeze([$keep])

Deletes all consecutive same characters with exceptions.

    say str('woooaaaah, balls')->squeeze->string;         # woah, bals

    # keep consecutive 'a' characters
    say str('woooaaaah, balls')->squeeze->string;         # woaaaah, balls

    # keep characters from 'l' to 'o'
    say str('woooaaaah, balls')->squeze('l-o')->string;   # woooah, balls

shuffle

Shuffles a string.

    say str('this is a test')->shuffle->string; # tsi  ssati the

transliterate

Transliterates a string into an another one. It wraps the tr() Perl function.

    say str('test')->transliterate('a-z', 'A-Z')->string; # TEST

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.