Module::Generic::Scalar - String Manipulation Object Class
my $s = Module::Generic::Scalar->new( "John Doe" ); print( $s->substr( 0, 4 ), "\n" ); # prints: John
v1.0.2
The purpos of this calss/package is to provide an object-oriented approach to string manipulation.
The object is overloaded, so it returns the embedded string when used as a string.
print( "I met with $s\n" );
Would produce: I met with John Doe
Provided with scalar reference, an array or just a regular string and this returns a new object.
If an array reference or an array-based object is provided like Module::Generic::Array, this will concatenate all the array elements
Provided with a string, and this will add it to the end of the string object.
# $s is 'Hello' $s->append( ' world' ); # now this is: Hello world
Returns the current string value as an Module::Generic::Array object.
Returns a Module::Generic::Boolean object with its value set to true or false based on the value of the scalar object.
# $s is 1 $s->as_boolean; # sets to true # $s is 0 $s->as_boolean; # sets to false # $s is hello $s->as_boolean: # sets to true # $s is undefined or empty $s->as_boolean: # sets to false # etc...
Module::Generic::Boolean objects are very useful because they can be used in perl as o or 1 to indicate false or true, but when used in json, they are automatically converted to false or true
false
true
Returns the current string as an L<Module::Generic::Number> object.
Returns the object string as a string.
my $s = Module::Generic::Scalar->new( "Mary Jane" ); print( "Hello $s\n" ); # Hello Mary Jane
Returns a new Module::Generic::Scalar object representing the string with the words capitalised, done in a smart way. That is the special words like and, but, if, on, or, the, to, etc. are not capitalised.
and
but
if
on
or
the
to
This is based on the work done by John Gruber and Aristotle Pagaltzis
Just like "chomp" in perlfunc, this removes the trailing new lines in the string object, if any.
As per the perl documentation for "chomp" in perlfunc, "it returns the total number of characters removed from all its arguments."
Just like "chop" in perlfunc, this removes the trailing character in the string object, no matter what it is, and returns the character chopped.
Returns a copy of the object.
This takes a "salt" and returns an encrypted version of the string. See "crypt" in perlfunc. Note that this does not work well on some BSD systems.
Returns true or false whether the string object contains a defined string, i.e. not undef
undef
Alias for "reset". This empties the scalar object, making it zero-byte in length.
Just like "fc" in perlfunc, provided with a string, this enables comparison with casefolding.
To quote from the manual: "Casefolding is the process of mapping strings to a form where case differences are erased".
lc($this) eq lc($that) # Wrong! # or uc($this) eq uc($that) # Also wrong! # or $this =~ /^\Q$that\E\z/i # Right! # And now my $s = Module::Generic::Scalar( $this ); $s->fc( $that );
Returns the hex value of the string.
Given a sub string and an optional position, and this returns the position at which the sub string was found. as a Module::Generic::Number object.
See "index" in perlfunc
Returns true if the string contains only alphabetic characters, or else it returns false.
This uses perl's [[:alpha:]] to test.
[[:alpha:]]
Returns true if the string contains only alphabetic or numeric characters, or else it returns false.
This uses perl's [[:alnum:]] to test.
[[:alnum:]]
Returns true if the string is zero in length, or else it returns false.
Returns true if the string contains only lower case characters, or else it returns false.
This uses perl's [[:lower:]] to test.
[[:lower:]]
Returns true if the string contains only numeric characters, or else it returns false.
This uses "looks_like_number" in Scalar::Util
Returns true if the string contains only upper case characters, or else it returns false.
This uses perl's [[:upper:]] to test.
[[:upper:]]
Takes a string as the delimiter and one or more elements and this will join the current string object and the other string elements provided using the string delimiter. For example:
my $s = Module::Generic::Scalar->new( 'Jack John Paul Peter' ); # Takes the string, split it by space (now an array), join it by comma (now a scalar) and rejoin it with more strings say $s->split( qr/[[:blank:]]+/ )->join( ', ' )->join( ', ', qw( Gabriel Raphael Emmanuel ) ); # prints: Jack, John, Paul, Peter, Gabriel, Raphael, Emmanuel
Note that if, among the element passed to "join", an aray object is provided, it will not be expanded. Thus, if you do something like this:
my $a = Module::Generic::Array->new( [qw( John Peter )] ); say Module::Generic::Scalar->new( 'Paul' )->join( ', ', $a );
It wil lnot produce Paul, John, Peter, but instead something like: Paul, Module::Generic::Array=ARRAY(0x5646f0116470)
Paul, John, Peter
Paul, Module::Generic::Array=ARRAY(0x5646f0116470)
That's because there is no way to guess if the user wanted to pass on a list or just an object and making that kind of assumption is dangerous.
What you woud want to do instead is:
say Module::Generic::Scalar->new( 'Paul' )->join( ', ', $a->list );
Or maybe
say Module::Generic::Scalar->new( 'Paul' )->join( ', ', @$a );
Of course, passing an overloaded object that has the stringification capability will transform it automatically into a string before being joined. Thus:
my $word1 = Module::Generic::Scalar->new( 'Hello' ); my $word2 = Module::Generic::Scalar->new( 'world' ); say $word1->join( ' ', $word2 );
will yield: Hello world because Module::Generic::Scalar objects have overloaded stringification capability.
Hello world
It returns the newly formed string as a new Module::Generic::Scalar object.
Takes the current string object and returns a new Module::Generic::Scalar object with the string all in lower case.
Takes the current string object and returns a new Module::Generic::Scalar object with the first character of the string in lower case.
Provided with a number and this will get the chunk starting from the left of the string object.
Module::Generic::Scalar->new( "Hello world" )->left( 5 ); # will produce: Hello
See also "right"
This returns the length of the string, as a Module::Generic::Number object.
Provided with a string or a regular express and this return the value of the regular expression evaluation against the object string.
my $s = "I disapprove of what you say, but I will defend to the death your right to say it"; print( "Matches? ", $s->like( qr/\bapprove[[:blank:]\h]+what\b/ ) ? 'yes' : 'no', "\n" ); # print yes
If there is no match, it returns 0, but in object, list or scalar context or when there are matches, it returns a Module::Generic::RegexpCapture object. This object stringifies into the number of matches, so you can do:
if( $s->like( qr/[[:blank:]\h]+/ ) ) { # Do something }
if( my $rv = $s->like( qr/([[:blank:]\h]+)/ )->result ) { my $first_match = $rv->capture->first; # Do something }
See also "match" and "replace"
Alias for "lc"
This removes any new line and space characters, i.e. \r and \n at the begining of the string.
\r
\n
It takes an optional argument that can be an alternative string to remove at the end of the sstring or a regular expression, such as one provided with "perlfunc/qr"
$s->ltrim( qr/[[:blank:]\h]+/ ); # Remove all kind of leading whitespaces
It returns the object itself for chaining.
See also "rtrim"
Provided with a string or a regular expression like the one created with "qr" in perlfunc and this returns true or false whether the string object matched or not.
# $s is "Hello world" $s->match( 'world' ); # pass $s->match( qr/WORLD/i ); # pass $s->match( 'monde' ); # obviously fail
if( $s->match( qr/[[:blank:]\h]+/ ) ) { # Do something }
if( my $rv = $s->match( qr/([[:blank:]\h]+)/ )->result ) { my $first_match = $rv->capture->first; # Do something }
See also "like" and "replace"
Returns the current object. This is useful when chaining to force an object context. For example, with "unpack". In scalar context, "unpack", as per the "unpack" in perlfunc documentation will return the first element:
my $unpack = $unpack_data->unpack( "A10xA28xA8A*" );
But what if we wanted $unpack to not be the first element, but the array object? For that, we would need to call "unpack" in object context:
$unpack
my $unpack = $unpack_data->unpack( "A10xA28xA8A*" )->object;
Opens the scalar in read/write mode and returns an object with same capabilities as regular file handle.
This returns the value of "ord" in perlfunc on the string, as a Module::Generic::Number object.
Like "pack" in perlfunc, this takes a template and convert the string object. "The resulting string is the concatenation of the converted values."
It returns a new Module::Generic::Scalar object.
See also "pack" in Module::Generic::Array
Provided with a number n and a string and this will create n instance of the string. If the number is positive, the string will be placed at the begining and if negative, it will be placed at the end
$s->pad( 3, 'X' ); # XXXHello world $s->padd( -3, 'X' ); # Hello worldXXX
This sets or gets the position inside the string object. See "pos" in perlfunc for detail about this.
Takes some data as its unique argument and prepend it to the scalar object underlying value.
If you want to pass multiple data, you will have to join them first:
$s->prepend( join( '', qw( Cogito ergo sum ) ) );
Given a string, this return a new Module::Generic::Scalar object with the given string characters escapeed with "quotemeta" in perlfunc.
Provided with a string or a regular expression and a replacement string and this will replace all instance of the string or regular expression with the replacement string provided.
# $s is Hello world my $rv = $s->replace( ' ', '_' ); # Hello_world my $rv = $s->replace( qr/[[:blank:]\h]+/, '_' ); # Hello_world
if( $s->replace( qr/[[:blank:]\h]+/, '_' ) ) { # Do something }
if( my $rv = $s->replace( qr/([[:blank:]\h]+)/, '_' )->result ) { my $first_match = $rv->capture->first; # Do something }
See also "like" and "match"
This empty the string inside the object.
Given a string, this return a new Module::Generic::Scalar object with the given string cin reverse order.
Provided with a number and this will get the chunk starting from the right of the string object.
Module::Generic::Scalar->new( "Hello world" )->right( 5 ); # will produce: world
See also "left"
Given a sub string and an optional position, and this returns the position at which the sub string was found, starting from the end.
See "rindex" in perlfunc
This removes any new line and space characters, i.e. \r and \n at the end of the string.
$s->rtrim( qr/[[:blank:]\h]+/ ); # Remove all kind of trailing whitespaces
See also "ltrim"
Returns the string within this scalar object. This calls "as_string"
Provided with a scalar reference or scalar-based object like Module::Generic::Scalar or an array reference and this sets the current string/.
This acts the exact same way as for "new", except it acts on the current object string.
Provided with a string or an expression and this returns the list in list context or, in scalar context, an array reference as an Module::Generic::Array object.
Be careful that you cannot just do like perl's original split such as:
my $a = $s->split( /\n/ );
Because /\n/ is not passed as an argument, i.e. it results in no argument being passed, so you do need to either provide the expression as "\n" or as a regular expression:
/\n/
"\n"
my $a = $s->split( qr/\n/ );
It will warn you if no argument was provided.
Provided with a list of arguments, and this replace the placeholders just like "sprintf" in perlfunc does.
Provided with an offset, an optional length and an optional replacement string, and this return a new Module::Generic::Scalar object.
See "substr" in perlfunc for more information.
Provided with a search list and a replacement list and this will perform just like the perl core "tr" in perlfunc function.
It also accepts options like cdsr and returns the resulting value.
cdsr
Provided with a target string or a regular expression, and this will remove any occurence of them in the string object.
Takes the current string object and returns a new Module::Generic::Scalar object with the string all in upper case.
Takes the current string object and returns a new Module::Generic::Scalar object with the first character of the string in upper case.
Sets the underlying string object to undef.
This would make
print( $s->defined ? 'defined' : 'undefined', "\n" );
return false, but becareful that you cannot do:
print( $s ? 'defined' : 'undefined', "\n" );
Because $s is the object so it would always return true.
If you stringify it like
print( "$s" ? 'defined' : 'undefined', "\n" );
It would still return as defined, because this would be a defined string, albeit empty
my $array = $s->unpack( "W" ); # Returns the ord() value as a Module::Generic::Array object $s->unpack( "W" )->length; # Object context. Ditto my( $date, $desc, $income, $expend ) = $s->unpack( "A10xA27xA7A*" ); # Returns a regular list of values
Does the reverse of "pack". Provided with a template, it takes the string object and expands it out into a list of values.
It returns an Module::Generic::Array object in object or scalar context, and a regular list in list context.
Alias for "uc"
Module::Generic::Number, Module::Generic::Array, Module::Generic::Boolean, Module::Generic::Hash, Module::Generic::Dynamic
Jacques Deguest <jack@deguest.jp>
Copyright (c) 2000-2020 DEGUEST Pte. Ltd.
You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.
To install Module::Generic, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Module::Generic
CPAN shell
perl -MCPAN -e shell install Module::Generic
For more information on module installation, please visit the detailed CPAN module installation guide.