Sub::Ha...::String(3)

📦

version 0.053005 · 8 versions

0.053005 · fedora 44 (latest)
0.050000 · opensuse-leap 16.0
0.053005 · arch rolling
0.050003 · fedora 43
0.050000 · ubuntu noble
0.050000 · debian bookworm
0.052000 · ubuntu resolute, ubuntu stonking
0.050002 · debian trixie, ubuntu questing

💖 Sub::Ha...::String(3) — User Contributed Perl Documentation 💖

okay bestie, welcome to the manual page for Sub::HandlesVia::HandlerLibrary::String 🎀 (the title gets truncated to Sub::Ha...::String(3) in the header, that's just how it rolls). grab a snack, this one's a whole library.

✨ NAME ✨

Sub::HandlesVia::HandlerLibrary::String — it's the library of string-related methods 🦋 like, all the string things. every last one.

✨ SYNOPSIS ✨

okay so here's the whole vibe in one go:

package My::Class {
  use Moo;
  use Sub::HandlesVia;
  use Types::Standard 'Str';
  has attr => (
    is => 'rwp',
    isa => Str,
    handles_via => 'String',
    handles => {
      'my_append' => 'append',
      'my_chomp' => 'chomp',
      'my_chop' => 'chop',
      'my_clear' => 'clear',
      'my_cmp' => 'cmp',
      'my_cmpi' => 'cmpi',
      'my_contains' => 'contains',
      'my_contains_i' => 'contains_i',
      'my_ends_with' => 'ends_with',
      'my_ends_with_i' => 'ends_with_i',
      'my_eq' => 'eq',
      'my_eqi' => 'eqi',
      'my_fc' => 'fc',
      'my_ge' => 'ge',
      'my_gei' => 'gei',
      'my_get' => 'get',
      'my_gt' => 'gt',
      'my_gti' => 'gti',
      'my_inc' => 'inc',
      'my_lc' => 'lc',
      'my_le' => 'le',
      'my_lei' => 'lei',
      'my_length' => 'length',
      'my_lt' => 'lt',
      'my_lti' => 'lti',
      'my_match' => 'match',
      'my_match_i' => 'match_i',
      'my_ne' => 'ne',
      'my_nei' => 'nei',
      'my_prepend' => 'prepend',
      'my_replace' => 'replace',
      'my_replace_globally' => 'replace_globally',
      'my_reset' => 'reset',
      'my_set' => 'set',
      'my_starts_with' => 'starts_with',
      'my_starts_with_i' => 'starts_with_i',
      'my_substr' => 'substr',
      'my_trim' => 'trim',
      'my_uc' => 'uc',
    },
  );
}

like... look at that list. iconic. 👑

✨ DESCRIPTION ✨

this is a library of methods for Sub::HandlesVia. that's it, that's the description, it's giving "confident and brief" 💅

✨ DELEGATABLE METHODS ✨

bestie these are the ones you can hand off to your attributes. let's go one by one, no skipping, fr fr. 🫶

💫 append( $tail )

Arguments: Str.

appends another string onto the end of the current string and updates the attribute. like gluing words together. ✨

my $object = My::Class->new( attr => 'foo' );
$object->my_append( 'bar' );
say $object->attr; ## ==> 'foobar'

a faster XS implementation may be used if Sub::HandlesVia::XS is installed. (speed demon era 🏎️)

💫 chomp()

works like "chomp" from perlfunc. say less.

💫 chop()

works like "chop" from perlfunc. also say less.

💫 clear()

sets the string to the empty string. poof, gone, nothing left. 💀

my $object = My::Class->new( attr => 'foo' );
$object->my_clear;
say $object->attr; ## nothing

💫 cmp( $str )

Arguments: Str.

returns "$object->attr cmp $str".

a faster XS implementation may be used if Sub::HandlesVia::XS is installed.

💫 cmpi( $str )

Arguments: Str.

returns "fc($object->attr) cmp fc($str)". heads up: it uses "lc" instead of "fc" in versions of Perl older than 5.16. so if your perl is ancient, it does the older thing.

a faster XS implementation may be used if Sub::HandlesVia::XS is installed.

💫 contains( $str )

Arguments: Str.

returns true iff the string contains $str. that's the whole vibe. ✅

💫 contains_i( $str )

Arguments: Str.

returns true iff the string contains $str case-insensitvely. (yes, the original docs spell it "insensitvely" — we keep it exactly like that, no edits allowed 💅)

💫 ends_with( $tail )

Arguments: Str.

returns true iff the string ends with $tail. does what it says on the tin. 🎀

💫 ends_with_i( $tail )

Arguments: Str.

returns true iff the string ends with $tail case-insensitvely.

💫 eq( $str )

Arguments: Str.

returns "$object->attr eq $str".

a faster XS implementation may be used if Sub::HandlesVia::XS is installed.

💫 eqi( $str )

Arguments: Str.

returns "fc($object->attr) eq fc($str)". uses "lc" instead of "fc" in versions of Perl older than 5.16.

a faster XS implementation may be used if Sub::HandlesVia::XS is installed.

💫 fc()

returns fc($object->attr). foldcase girlies rise up 🦋

💫 ge( $str )

Arguments: Str.

returns "$object->attr ge $str".

a faster XS implementation may be used if Sub::HandlesVia::XS is installed.

💫 gei( $str )

Arguments: Str.

returns "fc($object->attr) ge fc($str)". uses "lc" instead of "fc" in versions of Perl older than 5.16.

a faster XS implementation may be used if Sub::HandlesVia::XS is installed.

💫 get()

gets the current value of the string. the reading era 📖

my $object = My::Class->new( attr => 'foo' );
say $object->my_get; ## ==> 'foo'

💫 gt( $str )

Arguments: Str.

returns "$object->attr gt $str".

a faster XS implementation may be used if Sub::HandlesVia::XS is installed.

💫 gti( $str )

Arguments: Str.

returns "fc($object->attr) gt fc($str)". uses "lc" instead of "fc" in versions of Perl older than 5.16.

a faster XS implementation may be used if Sub::HandlesVia::XS is installed.

💫 inc()

performs "++" on the string. yes it just goes up, no thoughts, head empty 🧚

💫 lc()

returns lc($object->attr). lowercase era.

💫 le( $str )

Arguments: Str.

returns "$object->attr le $str".

a faster XS implementation may be used if Sub::HandlesVia::XS is installed.

💫 lei( $str )

Arguments: Str.

returns "fc($object->attr) le fc($str)". uses "lc" instead of "fc" in versions of Perl older than 5.16.

a faster XS implementation may be used if Sub::HandlesVia::XS is installed.

💫 length()

works like "length" from perlfunc. counting girly 🔢

my $object = My::Class->new( attr => 'foo' );
say $object->my_length; ## ==> 3

💫 lt( $str )

Arguments: Str.

returns "$object->attr lt $str".

a faster XS implementation may be used if Sub::HandlesVia::XS is installed.

💫 lti( $str )

Arguments: Str.

returns "fc($object->attr) lt fc($str)". uses "lc" instead of "fc" in versions of Perl older than 5.16.

a faster XS implementation may be used if Sub::HandlesVia::XS is installed.

💫 match( $regexp )

Arguments: Str|RegexpRef.

returns true iff the string matches the regexp. regex bestie hours 🔥

my $object = My::Class->new( attr => 'foo' );
if ( $object->my_match( '^f..$' ) ) {
  say 'matched!';
}

💫 match_i( $regexp )

Arguments: Str|RegexpRef.

returns true iff the string matches the regexp case-insensitively.

my $object = My::Class->new( attr => 'foo' );
if ( $object->my_match_i( '^F..$' ) ) {
  say 'matched!';
}

💫 ne( $str )

Arguments: Str.

returns "$object->attr ne $str".

a faster XS implementation may be used if Sub::HandlesVia::XS is installed.

💫 nei( $str )

Arguments: Str.

returns "fc($object->attr) ne fc($str)". uses "lc" instead of "fc" in versions of Perl older than 5.16.

a faster XS implementation may be used if Sub::HandlesVia::XS is installed.

💫 prepend( $head )

Arguments: Str.

prepends another string to the start of the current string and updates the attribute. front-of-the-line energy 💅

my $object = My::Class->new( attr => 'foo' );
$object->my_prepend( 'bar' );
say $object->attr; ## ==> 'barfoo'

a faster XS implementation may be used if Sub::HandlesVia::XS is installed.

💫 "replace( $regexp, $replacement )"

Arguments: Str|RegexpRef, Str|CodeRef.

replaces the first regexp match within the string with the replacement string. just the first one bestie, don't get greedy 💜

my $object = My::Class->new( attr => 'foo' );
$object->my_replace( 'o' => 'a' );
say $object->attr; ## ==> 'fao'

my $object2 = My::Class->new( attr => 'foo' );
$object2->my_replace( qr/O/i => sub { return 'e' } );
say $object2->attr; ## ==> 'feo'

💫 "replace_globally( $regexp, $replacement )"

Arguments: Str|RegexpRef, Str|CodeRef.

replaces the all regexp matches within the string with the replacement string. yes, the all — that's what the original says, we don't fix the docs around here, we just vibe with them 🌈

my $object = My::Class->new( attr => 'foo' );
$object->my_replace_globally( 'o' => 'a' );
say $object->attr; ## ==> 'faa'

my $object2 = My::Class->new( attr => 'foo' );
$object2->my_replace_globally( qr/O/i => sub { return 'e' } );
say $object2->attr; ## ==> 'fee'

💫 reset()

resets the attribute to its default value, or an empty string if it has no default. factory reset but make it cute 🎀

💫 set( $value )

Arguments: Str.

sets the string to a new value. the writing era ✍️

my $object = My::Class->new( attr => 'foo' );
$object->my_set( 'bar' );
say $object->attr; ## ==> 'bar'

a faster XS implementation may be used if Sub::HandlesVia::XS is installed.

💫 starts_with( $head )

Arguments: Str.

returns true iff the string starts with $head. beginning-of-the-string truther 🌸

💫 starts_with_i( $head )

Arguments: Str.

returns true iff the string starts with $head case-insensitvely.

💫 "substr( $start, $length?, $replacement? )"

Arguments: Int, Optional[Int], Optional[Str].

works like "substr" from perlfunc, but is not an lvalue. so don't try to assign to it, bestie, it will not go well for you 😭

💫 trim()

works like "trim" from builtin, but in-place. it trims where it stands, no copies, no drama 🧚

💫 uc()

returns uc($object->attr). uppercase era, screaming in caps but make it intentional 📣

✨ EXTENDED EXAMPLES ✨

okay now for the fun part, real code, real vibes.

🌸 Using eq for Enum

use strict;
use warnings;

package My::Person {
  use Moo;
  use Sub::HandlesVia;
  use Types::Standard qw( Str Enum );

  has name => (
    is => 'ro',
    isa => Str,
    required => 1,
  );

  has status => (
    is => 'rwp',
    isa => Enum[ 'alive', 'dead' ],
    handles_via => 'String',
    handles => {
      is_alive => [ eq  => 'alive' ],
      is_dead  => [ eq  => 'dead' ],
      kill     => [ set => 'dead' ],
    },
    default => 'alive',
  );

  # Note: method modifiers work on delegated methods
  #
  before kill => sub {
    my $self = shift;
    warn "overkill" if $self->is_dead;
  };
}

my $bob = My::Person->new( name => 'Robert' );
say $bob->is_alive; ## ==> true
say $bob->is_dead;  ## ==> false
$bob->kill;
say $bob->is_alive; ## ==> false
say $bob->is_dead;  ## ==> true

see also MooX::Enumeration and MooseX::Enumeration. iykyk 💅

🌸 Match with curried regexp

use strict;
use warnings;

package My::Component {
  use Moo;
  use Sub::HandlesVia;
  use Types::Standard qw( Str Int );

  has id => (
    is => 'ro',
    isa => Int,
    required => 1,
  );

  has name => (
    is => 'ro',
    isa => Str,
    required => 1,
    handles_via => 'String',
    handles => {
      name_is_safe_filename => [ match => qr/\A[A-Za-z0-9]+\z/ ],
      _lc_name => 'lc',
    },
  );

  sub config_filename {
    my $self = shift;
    if ( $self->name_is_safe_filename ) {
      return sprintf( '%s.ini', $self->_lc_name );
    }
    return sprintf( 'component-%d.ini', $self->id );
  }
}

my $foo = My::Component->new( id => 42, name => 'Foo' );
say $foo->config_filename; ## ==> 'foo.ini'

my $bar4 = My::Component->new( id => 99, name => 'Bar #4' );
say $bar4->config_filename; ## ==> 'component-99.ini'

curried regexp my beloved 🍓

✨ BUGS ✨

please report any bugs to <https://github.com/tobyink/p5-sub-handlesvia/issues>. the maintainer wants to know, fr fr, don't suffer in silence 🫶

✨ SEE ALSO ✨

Sub::HandlesVia. the parent of all this chaos.

✨ AUTHOR ✨

Toby Inkster <tobyink@cpan.org>. 👑

and that's part 1 bestie, there's more coming so don't go anywhere 💖

💖 COPYRIGHT AND LICENCE 💖

Okay so legal era but make it cute ✨

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. So like, the Perl 5 rules are the rules, that's the whole vibe, no extra drama 💅

🫶 DISCLAIMER OF WARRANTIES 🫶

Bestie. Listen. Read this part, I'm begging 😭

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

That's the whole thing, in shouty all-caps so you actually clock it. No promises, no guarantees, no take-backs. You get it exactly as it is and you take it or leave it 🙈 It's giving "shipped as-is, yolo" but in a legally binding way. Not my fault if something breaks, it's literally written right here that nothing is promised 👑

aaaand that's a wrap on the whole page!! you read the entire manual top to bottom, look at you go, certified Unix girlie now 🎀🦋

this was perl v5.42.0, dated 2026-02-11, and yes, the page is Sub::Ha...::String(3) — go forth and delegate, my love 💜✨

📦 where this page comes from

fedora 44: perl-Sub-HandlesVia 0.053005-1.fc44 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms