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";
          $str    eq "Hello";

        You can still keep using Perl's built-in concatination operator, "."
        (dot):

          $str = new String("Hello");
          $str .= " World";
          $str eq "Hello World";

        Notice the differences between the above two examples; the first one
        returns a $newStr - a new string object and doesn't modify the
        original $str. The second example doesn't return/create any
        additional objects, but modifies the original $str.

        You can also use "+" (plus) operator for concatinating string
        objects with another string, just like in C++ and Java:

          $str = new String("Hello");
          $str += " World"
          $str eq "Hello World";

        If you don't want to change the original $str:

          $str = new String("Hello");
          $newStr = $str + " World";
          $newStr eq "Hello World";
          $str    eq "Hello";

    append(LIST)
        Same as "concat()"

    prepend(LIST)
        Similar to "concat()", but concatinates the string(s) to the front
        of the original string as returns an appropriate String object.
        Original string is not modified.

    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 the Storable
        manpage 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
    the String::Approx manpage.

