Why does encode delete the argument?

Question

Why does encode delete the passed argument, if CHECK is set to a true value?

#!/usr/bin/env perl
use warnings;
use strict;
use utf8;
use Encode;

my $decoded = 'h';
if ( eval { encode( 'utf-8', $decoded, 1 ); 1 } ) {
    print "|$decoded|\n";    # prints ||
}

Answer 1

It is for use in the case where you are repeatedly passing chunks of data to encode or decode. The idea is that the function will remove the part of the string that it has translated, and you need only append the next chunk to what is left. It is useful for handling multi-byte encodings that may be split across two chunks.

If you don't want this behaviour then you can OR the Encode::LEAVE_SRC bit into the third parameter. Like this

use utf8;
use strict;
use warnings;

use Encode qw/ encode decode FB_CROAK LEAVE_SRC /;
use Data::Dump;

my $decoded = 'ABC';
dd $decoded;
my $encoded = encode( 'UTF-8', $decoded, FB_CROAK | LEAVE_SRC );
dd $decoded;
dd $encoded;

output

"ABC"
"ABC"
"ABC"