NAME

Data::Object::Role::String - String Object Role for Perl 5

VERSION

version 0.59

SYNOPSIS

    use Data::Object::Class;

    with 'Data::Object::Role::String';

DESCRIPTION

Data::Object::Role::String provides routines for operating on Perl 5 string data.

METHODS

append

    # given 'firstname'

    $string->append('lastname'); # firstname lastname

The append method modifies and returns the string with the argument list appended to it separated using spaces. This method returns a string object.

camelcase

    # given 'hello world'

    $string->camelcase; # HelloWorld

The camelcase method modifies the string such that it will no longer have any non-alphanumeric characters and each word (group of alphanumeric characters separated by 1 or more non-alphanumeric characters) is capitalized. Note, this method modifies the string. This method returns a Data::Object::String object.

chomp

    # given "name, age, dob, email\n"

    $string->chomp; # name, age, dob, email

The chomp method is a safer version of the chop method, it's used to remove the newline (or the current value of $/) from the end of the string. Note, this method modifies and returns the string. This method returns a string object.

chop

    # given "this is just a test."

    $string->chop; # this is just a test

The chop method removes the last character of a string and returns the character chopped. It is much more efficient than "s/.$//s" because it neither scans nor copies the string. Note, this method modifies and returns the string. This method returns a string value.

concat

    # given 'ABC'

    $string->concat('DEF', 'GHI'); # ABCDEFGHI

The concat method modifies and returns the string with the argument list appended to it. This method returns a string value.

contains

    # given 'Nullam ultrices placerat nibh vel malesuada.'

    $string->contains('trices'); # 1; true
    $string->contains('itrices'); # 0; false

    $string->contains(qr/trices/); # 1; true
    $string->contains(qr/itrices/); # 0; false

The contains method searches the string for the string specified in the argument and returns true if found, otherwise returns false. If the argument is a string, the search will be performed using the core index function. If the argument is a regular expression reference, the search will be performed using the regular expression engine. This method returns a Data::Object::Number object.

data

    # given $string

    $string->data; # original value

The data method returns the original and underlying value contained by the object. This method is an alias to the detract method.

defined

    # given $string

    $string->defined; # 1

The defined method returns true if the object represents a value that meets the criteria for being defined, otherwise it returns false. This method returns a number object.

detract

    # given $string

    $string->detract; # original value

The detract method returns the original and underlying value contained by the object.

dump

    # given 'exciting'

    $string->dump; # 'exciting'

The dump method returns returns a string representation of the object. This method returns a string value.

eq

    # given 'exciting'

    $string->eq('Exciting'); # 0

The eq method returns true if the argument provided is equal to the value represented by the object. This method returns a number value.

ge

    # given 'exciting'

    $string->ge('Exciting'); # 1

The ge method returns true if the argument provided is greater-than or equal-to the value represented by the object. This method returns a Data::Object::Number object.

gt

    # given 'exciting'

    $string->gt('Exciting'); # 1

The gt method returns true if the argument provided is greater-than the value represented by the object. This method returns a number value.

hex

    # given '0xaf'

    string->hex; # 175

The hex method returns the value resulting from interpreting the string as a hex string. This method returns a data type object to be determined after execution.

index

    # given 'unexplainable'

    $string->index('explain'); # 2
    $string->index('explain', 0); # 2
    $string->index('explain', 1); # 2
    $string->index('explain', 2); # 2
    $string->index('explain', 3); # -1
    $string->index('explained'); # -1

The index method searches for the argument within the string and returns the position of the first occurrence of the argument. This method optionally takes a second argument which would be the position within the string to start searching from (also known as the base). By default, starts searching from the beginning of the string. This method returns a data type object to be determined after execution.

lc

    # given 'EXCITING'

    $string->lc; # exciting

The lc method returns a lowercased version of the string. This method returns a string object. This method is an alias to the lowercase method.

lcfirst

    # given 'EXCITING'

    $string->lcfirst; # eXCITING

The lcfirst method returns a the string with the first character lowercased. This method returns a string value.

le

    # given 'exciting'

    $string->le('Exciting'); # 0

The le method returns true if the argument provided is less-than or equal-to the value represented by the object. This method returns a Data::Object::Number object.

length

    # given 'longggggg'

    $string->length; # 9

The length method returns the number of characters within the string. This method returns a number value.

lines

    # given "who am i?\nwhere am i?\nhow did I get here"

    $string->lines; # ['who am i?','where am i?','how did i get here']

The lines method breaks the string into pieces, split on 1 or more newline characters, and returns an array reference consisting of the pieces. This method returns an array value.

lowercase

    # given 'EXCITING'

    $string->lowercase; # exciting

The lowercase method is an alias to the lc method. This method returns a string object.

lt

    # given 'exciting'

    $string->lt('Exciting'); # 0

The lt method returns true if the argument provided is less-than the value represented by the object. This method returns a number value.

methods

    # given $string

    $string->methods;

The methods method returns the list of methods attached to object. This method returns an array value.

ne

    # given 'exciting'

    $string->ne('Exciting'); # 1

The ne method returns true if the argument provided is not equal to the value represented by the object. This method returns a number value.

new

    # given abcedfghi

    my $string = Data::Object::String->new('abcedfghi');

The new method expects a string and returns a new class instance.

print

    # given 'exciting'

    $string->print; # 'exciting'

The print method outputs the value represented by the object to STDOUT and returns true. This method returns a number value.

replace

    # given 'Hello World'

    $string->replace('World', 'Universe'); # Hello Universe
    $string->replace('world', 'Universe', 'i'); # Hello Universe
    $string->replace(qr/world/i, 'Universe'); # Hello Universe
    $string->replace(qr/.*/, 'Nada'); # Nada

The replace method performs a smart search and replace operation and returns the modified string (if any modification occurred). This method optionally takes a replacement modifier as it's final argument. Note, this operation expects the 2nd argument to be a replacement String. This method returns a string object.

reverse

    # given 'dlrow ,olleH'

    $string->reverse; # Hello, world

The reverse method returns a string where the characters in the string are in the opposite order. This method returns a string value.

rindex

    # given 'explain the unexplainable'

    $string->rindex('explain'); # 14
    $string->rindex('explain', 0); # 0
    $string->rindex('explain', 21); # 14
    $string->rindex('explain', 22); # 14
    $string->rindex('explain', 23); # 14
    $string->rindex('explain', 20); # 14
    $string->rindex('explain', 14); # 0
    $string->rindex('explain', 13); # 0
    $string->rindex('explain', 0); # 0
    $string->rindex('explained'); # -1

The rindex method searches for the argument within the string and returns the position of the last occurrence of the argument. This method optionally takes a second argument which would be the position within the string to start searching from (beginning at or before the position). By default, starts searching from the end of the string. This method returns a data type object to be determined after execution.

roles

    # given $string

    $string->roles;

The roles method returns the list of roles attached to object. This method returns an array value.

say

    # given 'exciting'

    $string->say; # 'exciting\n'

The say method outputs the value represented by the object appended with a newline to STDOUT and returns true. This method returns a Data::Object::Number object.

snakecase

    # given 'hello world'

    $string->snakecase; # helloWorld

The snakecase method modifies the string such that it will no longer have any non-alphanumeric characters and each word (group of alphanumeric characters separated by 1 or more non-alphanumeric characters) is capitalized. The only difference between this method and the camelcase method is that this method ensures that the first character will always be lowercased. Note, this method modifies the string. This method returns a string value.

split

    # given 'name, age, dob, email'

    $string->split(', '); # ['name', 'age', 'dob', 'email']
    $string->split(', ', 2); # ['name', 'age, dob, email']
    $string->split(qr/\,\s*/); # ['name', 'age', 'dob', 'email']
    $string->split(qr/\,\s*/, 2); # ['name', 'age, dob, email']

The split method splits the string into a list of strings, separating each chunk by the argument (string or regexp object), and returns that list as an array reference. This method optionally takes a second argument which would be the limit (number of matches to capture). Note, this operation expects the 1st argument to be a Regexp object or a String. This method returns a array object.

strip

    # given 'one,  two,  three'

    $string->strip; # one, two, three

The strip method returns the string replacing occurences of 2 or more whitespaces with a single whitespace. This method returns a string object.

throw

    # given $string

    $string->throw;

The throw method terminates the program using the core die keyword, passing the object to the Data::Object::Exception class as the named parameter object. If captured this method returns an exception value.

titlecase

    # given 'mr. john doe'

    $string->titlecase; # Mr. John Doe

The titlecase method returns the string capitalizing the first character of each word (group of alphanumeric characters separated by 1 or more whitespaces). Note, this method modifies the string. This method returns a string object.

trim

    # given ' system is   ready   '

    $string->trim; # system is   ready

The trim method removes 1 or more consecutive leading and/or trailing spaces from the string. This method returns a string value.

type

    # given $string

    $string->type; # STRING

The type method returns a string representing the internal data type object name. This method returns a string value.

uc

    # given 'exciting'

    $string->uc; # EXCITING

The uc method returns an uppercased version of the string. This method returns a string object. This method is an alias to the uppercase method.

ucfirst

    # given 'exciting'

    $string->ucfirst; # Exciting

The ucfirst method returns a the string with the first character uppercased. This method returns a string value.

uppercase

    # given 'exciting'

    $string->uppercase; # EXCITING

The uppercase method is an alias to the uc method. This method returns a string object.

words

    # given "is this a bug we're experiencing"

    $string->words; # ["is","this","a","bug","we're","experiencing"]

The words method splits the string into a list of strings, separating each group of characters by 1 or more consecutive spaces, and returns that list as an array reference. This method returns an array value.

ROLES

This package is comprised of the following roles.

• Data::Object::Role::Alphabetic

• Data::Object::Role::Comparison

• Data::Object::Role::Defined

• Data::Object::Role::Detract

• Data::Object::Role::Dumper

• Data::Object::Role::Item

• Data::Object::Role::Output

• Data::Object::Role::Throwable

• Data::Object::Role::Type

• Data::Object::Role::Value

SEE ALSO

• Data::Object::Array

• Data::Object::Class

• Data::Object::Class::Syntax

• Data::Object::Code

• Data::Object::Float

• Data::Object::Hash

• Data::Object::Integer

• Data::Object::Number

• Data::Object::Role

• Data::Object::Role::Syntax

• Data::Object::Regexp

• Data::Object::Scalar

• Data::Object::String

• Data::Object::Undef

• Data::Object::Universal

• Data::Object::Autobox

• Data::Object::Immutable

• Data::Object::Library

• Data::Object::Prototype

• Data::Object::Signatures

AUTHOR

Al Newkirk <anewkirk@ana.io>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Al Newkirk.

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

cpanm Data::Object

perl -MCPAN -e shell
install Data::Object