The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Module-Generic-v0.13.0
River stage two • 16 direct dependents • 20 total dependents
2 ++
/ Module::Generic::Scalar

NAME

Module::Generic::Scalar - String Manipulation Object Class

SYNOPSIS

    my $s = Module::Generic::Scalar->new( "John Doe" );
    print( $s->substr( 0, 4 ), "\n" );
    # prints: John

VERSION

    v0.2.3

DESCRIPTION

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

METHODS

new

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

as_boolean

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

as_string

Returns the object string as a string.

    my $s = Module::Generic::Scalar->new( "Mary Jane" );
    print( "Hello $s\n" );
    # Hello Mary Jane

append

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

capitalise

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.

This is based on the work done by John Gruber and Aristotle Pagaltzis

chomp

Just like "chomp" in perlfunc, this remove the trailing new lines in the string, if any.

chop

Just like "chop" in perlfunc, this remove the trailing character in the string, no matter what it is.

clone

Returns a copy of the object.

crypt

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.

defined

Returns true or false whether the string object contains a defined string, i.e. not undef

fc

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 );

hex

Returns the hex value of the string.

index

Given a sub string and an optional position, and this returns the position at which the sub string was found.

See "index" in perlfunc

is_alpha

Returns true if the string contains only alphabetic characters, or else it returns false.

This uses perl's [[:alpha:]] to test.

is_alpha_numeric

Returns true if the string contains only alphabetic or numeric characters, or else it returns false.

This uses perl's [[:alnum:]] to test.

is_empty

Returns true if the string is zero in length, or else it returns false.

is_lower

Returns true if the string contains only lower case characters, or else it returns false.

This uses perl's [[:lower:]] to test.

is_numeric

Returns true if the string contains only numeric characters, or else it returns false.

This uses "looks_like_number" in Scalar::Util

is_upper

Returns true if the string contains only upper case characters, or else it returns false.

This uses perl's [[:upper:]] to test.

lc

Given a string, this return a new Module::Generic::Scalar object with the string all in lower case.

lcfirst

Given a string, this return a new Module::Generic::Scalar object with the first character of the string in lower case.

left

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"

length

This returns the length of the string, as a Module::Generic::Number object.

like

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

ltrim

This removes any new line and space characters, i.e. \r and \n at the begining of the string.

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"

match

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

ord

This returns the value of "ord" in perlfunc on the string, as a Module::Generic::Number object.

pad

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

pos

This sets or gets the position inside the string object. See "pos" in perlfunc for detail about this.

quotemeta

Given a string, this return a new Module::Generic::Scalar object with the given string characters escapeed with "quotemeta" in perlfunc.

replace

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
    $s->replace( ' ', '_' ); # Hello_world
    $s->replace( qr/[[:blank:]\h]+/, '_' ); # Hello_world

reset

This empty the string inside the object.

reverse

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"

rindex

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

rtrim

This removes any new line and space characters, i.e. \r and \n at the end of the string.

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->rtrim( qr/[[:blank:]\h]+/ ); # Remove all kind of trailing whitespaces

It returns the object itself for chaining.

See also "ltrim"

scalar

Returns the string within this scalar object. This calls "as_string"

set

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.

split

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:

    my $a = $s->split( qr/\n/ );

It will warn you if no argument was provided.

sprintf

Provided with a list of arguments, and this replace the placeholders just like "sprintf" in perlfunc does.

substr

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.

tr

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.

trim

Provided with a target string or a regular expression, and this will remove any occurence of them in the string object.

uc

Given a string, this return a new Module::Generic::Scalar object with the string all in upper case.

ucfirst

Given a string, this return a new Module::Generic::Scalar object with the first character of the string in upper case.

undef

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

SEE ALSO

Module::Generic::Number, Module::Generic::Array, Module::Generic::Boolean, Module::Generic::Hash, Module::Generic::Dynamic

AUTHOR

Jacques Deguest <jack@deguest.jp>

COPYRIGHT & LICENSE

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.