NAME

String - Perl extension representing string object

SYNOPSIS

use String;

my $str = new String("Perl");

print "The string is '$str'\n";
printf("Length of the string is %d characters\n", $str->length);
printf("The first character of the string is %s\n", $str->charAt(0));

my $pos = $str->indexOf('er');
if (  $pos != -1 ) {
  printf("String '%s' contains 'er' at position %d\n", $str, $pos);
}

my $newStr = $str->concat(" ", "Guru");
printf("Length of the new string('%s') is %d characters\n", $newStr, $newStr->length);

DESCRIPTION

String is a Perl 5 class representing a string object. It provides String methods for manipulating text, such as match(), length(), charAt(), indexOf(), split(), asString() and several more. Since Perl already provides built-in utilities for manipulating strings, each METHOD description also provides how this particular task is implemented internally. This may be useful for comparison.

CONSTRUCTOR

new(STRONG)

takes a STRING as an argument, and returns String object. Argument passed to new() - STRING can be either a string, a variable interpolating into a string or a reference to a string. If it receives anything else, will through an exception. Example:

$str = new String("Perl");

Internally String object is represented as reference to the STRING (passed as the first argument).

Note: examples throughout the manual will be working on this particular String
object unless noted otherwise.

METHODS

length()

returns the length of the string. Internally calls Perl's length() built-in function. Example:

# assuming 'Perl' is a string
$str->length == 4;

charAt(n)

takes a digit as the first argument, and returns the character from that position of the string. Example:

# getting the first character
$str->charAt(0) == 'P';

# getting the last character
$str->charAt( $str->length-1 ) == 'l';

If the argument passed to charAt() is negative, starts the indexing from the end of the string

# getting the last character of the string:
$str->charAt(-1);

This function is internally implemented by substr().

indexOf('substring')

returns the index of 'substring' from within String object. Internally calls Perl's built-in index() function. Example:

$str->indexOf('er') == 1;

This example returns 1, because the first (and the only in our case) occasion of substring "er" starts at the second character of "Perl". Since indexing starts at 0, the second character's index is actually 1. If the match doesn't occur, the return value is -1. Example:

if ( $str->indexOf('ear') == -1 ) {
  print "There is no 'ear' in '$str'\n";
}

match(PATTERN)

Accepts a regular expression pattern, and returns a reference to an array on success, undef otherwise. First element of the returned array is whatever matched. Capturing paranthesis, if any used in the PATTERN, will constitute other elements of the array. Following example is retrieving an e-mail address from a string and capturing username and host parts of the address:

$email = new String('Sherzod Ruzmetov <sherzodr@cpan.org>');
$result = $email->match('([\w.-]+)@([\w-]+\.[\w.-]+)');
if ( $result ) {
  printf("Out of '%s', I could match 's%'\n", $string, $result->[0]);
  printf("Username is '%s'\n", $result->[1]);
  printf("Host address is '%s'\n", $result->[2]);

Note: all the elements of the $result set are also of String type. So the following applies for the above $result:

if ( $result->[2]->match('^cpan\.org$') ) {
  print "Oh, is that a CPAN e-mail account? Neat!\n";
}

asString()

Returns the original string. Due to overloading, whenever you use String object in the context where string is expected, asString() will be called for you automatically. Example:

printf("Original string is '%s'\n", $str->asString );  
print "You could also print it this way: '$str'\n";

eq(STRING)

for comparing the string to another string. The argument STRING can be either a literal string, or String object:

if ( $str->eq('Java') ) {
  print "They are the same\n";
}

Due to overloading, you can also use Perl's built-in eq operator to compare String object to another String, or even String object to another "string":

if ( $str eq 'Java') {
  print "No way!?\n";
}
# or
my $str2 = new String("Perl");
if ( $str eq $str2 ) {
  print "That's more like it.\n";
}

This method is internally implemented with Perl's built-in eq operator.

toLowerCase()

returns a String object by converting all the characters of the original string to their lower cases. Internally implemented with Perl's built-in uc() function:

$str->toLowerCase() eq 'perl';

toUpperCase()

the same as toLowerCase(), but returns String object by upper-casing the its characters. Implemented with Perl's built-in lc() function

concat(LIST)

returns a String object by concatenating all the elements of LIST. String itself is not modified. Example:

$str = new String("Hello");
$newStr = $str->concat(" ", "World");
$newStr eq "Hello World";

split(PATTERN [,LIMIT])

splits a string into substrings at each PATTERN, and returns an array of respective String objects. If LIMIT is defined, it will restrict the length of an array to first LIMIT elements. Example:

$str = new String("one, two, three, four, five");
@array = $str->split(',\s*');
for ( @array ) {
  print "$_\n";
}

serialize()

returns a serialized String object. Internally uses Storable to serialize the object into a string. If the Sorable.pm is not available on your machine, you'll get an exception.

TODO

I do not expect this class to be exhaustive nor comprehensive. I'm open to suggestions, patches and comments.

AUTHOR

Sherzod B. Ruzmetov, <sherzodr@cpan.org>

SEE ALSO

String::Approx.