I have been writing POD for some of my modules, and one of the harder aspects of writing POD is coming up with good examples in the synopsis. I came up with, what I think is, a good example for numerical use; but I am stuck on coming up with a good example for the alpha use of the following sub.

The sub splits the values of the list into two parts, sorting by the first part, then sorting by the second part.

Please note, I do not know why I wrote this, since I am not using it anywhere in my code. I even searched my history here to see if I brought it up before and can not find anything, which is strange because most of what I write ends up here at some point.

sub split_sort {
  my ($in_a, $in_b, $split, $sort_type) = @_;
  $split = qr($split);

  my ($numa1, $numa2) = split(/$split/, $in_a);
  my ($numb1, $numb2) = split(/$split/, $in_b);

  if ($sort_type =~ /^num/) {
    $numa1 <=> $numb1 || $numa2 <=> $numb2
  }
  elsif ($sort_type =~ /^(alpha|letter)/) {
    $numa1 cmp $numb1 || $numa2 cmp $numb2
  }
}
[download]

  my @numbers = qw(1:2 1:02 3:4 5:78 50:89 10:5);

  my @sorted = sort @numbers;
  # The list as it is written can not be sorted as numbers.
  # returns
  # [
  #   '10:5',
  #   '1:02',
  #   '1:2',
  #   '3:4',
  #   '50:89',
  #   '5:78'
  # ]

  my @split_sorted = sort { split_sort($a, $b, ':', 'number') } @numbe
+rs;
  # returns
  # [
  #   '1:2',
  #   '1:02',
  #   '3:4',
  #   '5:78',
  #   '10:5',
  #   '50:89'
  # ];
[download]

I just can not come up with a list where this might be needed on alphabetical strings.

Comments on the code are always welcome.

Edit: I have a feeling I added the usage for alphabetical strings for completeness, nothing more. I have tried coming up with lists of alphabetical strings that would change if this is used and have not found any. I am now thinking that I should just put a note in saying that the alphabetical usage is redundant.