<commit_before>=encoding utf8

=head1 NAME

Inline::CPP - Write Perl subroutines and classes in C++.

=head1 SYNOPSIS

    use Inline CPP;

    print "9 + 16 = ", add(9, 16), "\n";
    print "9 - 16 = ", subtract(9, 16), "\n";

    __END__
    __CPP__

    int add(int x, int y) {
      return x + y;
    }

    int subtract(int x, int y) {
      return x - y;
    }

=head1 DESCRIPTION

The L<Inline::CPP> module allows you to put C++ source code directly
"inline" in a Perl script or module. You code classes or functions in
C++, and you can use them as if they were written in Perl.

=head1 RATIONALE

"I<We should forget about small efficiencies, say about 97% of the time:
premature optimization is the root of all evil. Yet we should not pass up our
opportunities in that critical 3%. A good programmer will not be lulled into
complacency by such reasoning, he will be wise to look carefully at the
critical code; but only after that code has been identified>" -- <NAME>

L<Inline::CPP> is about that critical 3%.

Tom "Duff's Device" Duff once wrote the following: "I<The alternative to
genuflecting before the god of code-bumming is finding a better algorithm...
...If your code is too slow, you must make it faster.  If no better algorithm
is available, you must trim cycles.>"

Often, well written Perl is fast enough.  But when one comes across a situation
where performance isn't fast enough, and no better algorithm exists, getting
closer to the metal is one way to trim cycles, assuming it's done well.
L<Inline::CPP> minimizes the pain in binding C++ code to Perl via XS.

Performance can also be evaluated in terms of memory requirements.  Perlish
datastructures are beautifully simple to use, and quite powerful.  But this
beauty and power comes at the cost of memory and speed.  If you are finding that
it is too memory-expensive to hold your data in a Perl array, and a
disk-based solution is, for whatever reason, not an option, the memory burden
can be aleviated to some degree by holding the data in a C++ data type.

This can only go so far.  But the common saying is that if you consider a
reasonable amount of memory to hold a data structure, double it, and then
multiply by ten, you'll have a pretty good feel for how much memory Perl needs
to hold it.  Inline::CPP can facilitate a leaner alternative.

"I<The standard library saves programmers from having to reinvent the wheel.>"
-- <NAME>

L<Inline::CPP> is also about not reinventing the wheel.

There are many C and C++ libraries already in existence that provide
functionality that is well tested, well debuged, and well understood.  There is
often no great benefit aside from portability in rewriting such libraries in
pure Perl.  Even re-writing them in XS is cumbersome and prone to bugs.
Inline::CPP can be used to quickly develop Perl bindings to existing C++
libraries.

"I<<NAME> got fed up with writing XS and ended up writing
a very clever Perl module called L<Inline> to do it for him.>"

Face it, XS has a big fat learning curve, lots of boilerplate, and is easy to
botch it up in difficult to find ways.  Inline::CPP exists to make that process
easier.  By lightening the cognative load and boilerplate drudgery associated
with pure XS, Inline::CPP can aid the developer in producing less buggy
extension code.  It won't shield you entirely from C<perlguts>, but it will
take the edge off of it.

=head1 Choosing a C++ Compiler

Inline::CPP just parses the subroutine and class signatures within your C++
code and creates bindings to them. Like Inline::C, you will need a suitable
compiler the first time you run the script.

If you're one of the fortunate majority, you will accept the defaults as you
install Inline::CPP; the correct C++ compiler and standard libraries will be
configured for you.  If you're one of the unfortunate (and shrinking) minority,
read on.

Here's the rule: use a C++ compiler that's compatible with the compiler
which built C<perl>. For instance, if C<perl> was built with C<gcc>,
use C<g++>.  If you're on a Sun or an IRIX box and the system C compiler
C<cc> built C<perl>, then use the system C++ compiler, C<CC>.

Some compilers actually compile both C and C++ with the same compiler.
Microsoft's C<cl.exe> is one such compiler -- you pass it the <-TP> flag
to convince it that you want C++ mode.  Hopefully this will be deduced
by default at install time.

If you're using the GNU C++ compiler, make sure that you have the g++ front
end installed (some Linux distros don't install it by default, but provide
it via their package management utilities).

=head1 Using Inline::CPP

Inline::CPP is very similar to Inline::C, and in most cases can be used in
place of Inline::C without changing a single line of Perl or C code. If you
haven't done so already, you should stop reading right now and read the
documentation for L<Inline::C>, including the L<Inline::C-Cookbook>.

This module uses a  grammar to parse your C++ code, and binds to functions or
classes which are recognized. If a function is recognized, it will be available
from Perl space. If the function's signature is not recognized, it will not
be available from Perl, but will be available from other functions or classes
within the C++ code.

For more information about the grammar used to parse C++ code, see the
section called "Grammar".

The following example shows how C++ snippets map to Perl:

Example 1:

    use Inline CPP => <<'END';

    using namespace std;

    int doodle() { }

    class Foo {
     public:
       Foo();
       ~Foo();

       int get_data() { return data; }<commit_msg>doc tweak - fix #46<commit_after>=encoding utf8

=head1 NAME

Inline::CPP - Write Perl subroutines and classes in C++.

=head1 SYNOPSIS

    use Inline CPP;

    print "9 + 16 = ", add(9, 16), "\n";
    print "9 - 16 = ", subtract(9, 16), "\n";

    __END__
    __CPP__

    int add(int x, int y) {
      return x + y;
    }

    int subtract(int x, int y) {
      return x - y;
    }

=head1 DESCRIPTION

The L<Inline::CPP> module allows you to put C++ source code directly
"inline" in a Perl script or module. You code classes or functions in
C++, and you can use them as if they were written in Perl.

=head1 RATIONALE

"I<We should forget about small efficiencies, say about 97% of the time:
premature optimization is the root of all evil. Yet we should not pass up our
opportunities in that critical 3%. A good programmer will not be lulled into
complacency by such reasoning, he will be wise to look carefully at the
critical code; but only after that code has been identified>" -- <NAME>

L<Inline::CPP> is about that critical 3%.

Tom "Duff's Device" Duff once wrote the following: "I<The alternative to
genuflecting before the god of code-bumming is finding a better algorithm...
...If your code is too slow, you must make it faster.  If no better algorithm
is available, you must trim cycles.>"

Often, well written Perl is fast enough.  But when one comes across a situation
where performance isn't fast enough, and no better algorithm exists, getting
closer to the metal is one way to trim cycles, assuming it's done well.
L<Inline::CPP> minimizes the pain in binding C++ code to Perl via XS.

Performance can also be evaluated in terms of memory requirements.  Perlish
datastructures are beautifully simple to use, and quite powerful.  But this
beauty and power comes at the cost of memory and speed.  If you are finding that
it is too memory-expensive to hold your data in a Perl array, and a
disk-based solution is, for whatever reason, not an option, the memory burden
can be aleviated to some degree by holding the data in a C++ data type.

This can only go so far.  But the common saying is that if you consider a
reasonable amount of memory to hold a data structure, double it, and then
multiply by ten, you'll have a pretty good feel for how much memory Perl needs
to hold it.  Inline::CPP can facilitate a leaner alternative.

"I<The standard library saves programmers from having to reinvent the wheel.>"
-- <NAME>

L<Inline::CPP> is also about not reinventing the wheel.

There are many C and C++ libraries already in existence that provide
functionality that is well tested, well debuged, and well understood.  There is
often no great benefit aside from portability in rewriting such libraries in
pure Perl.  Even re-writing them in XS is cumbersome and prone to bugs.
Inline::CPP can be used to quickly develop Perl bindings to existing C++
libraries.

"I<<NAME> got fed up with writing XS and ended up writing
a very clever Perl module called L<Inline> to do it for him.>"

Face it, XS has a big fat learning curve, lots of boilerplate, and is easy to
botch it up in difficult to find ways.  Inline::CPP exists to make that process
easier.  By lightening the cognative load and boilerplate drudgery associated
with pure XS, Inline::CPP can aid the developer in producing less buggy
extension code.  It won't shield you entirely from C<perlguts>, but it will
take the edge off of it.

=head1 Choosing a C++ Compiler

Inline::CPP just parses the subroutine and class signatures within your C++
code and creates bindings to them. Like Inline::C, you will need a suitable
compiler the first time you run the script.

If you're one of the fortunate majority, you will accept the defaults as you
install Inline::CPP; the correct C++ compiler and standard libraries will be
configured for you.  If you're one of the unfortunate (and shrinking) minority,
read on.

Here's the rule: use a C++ compiler that's compatible with the compiler
which built C<perl>. For instance, if C<perl> was built with C<gcc>,
use C<g++>.  If you're on a Sun or an IRIX box and the system C compiler
C<cc> built C<perl>, then use the system C++ compiler, C<CC>.

Some compilers actually compile both C and C++ with the same compiler.
Microsoft's C<cl.exe> is one such compiler -- you pass it the <-TP> flag
to convince it that you want C++ mode.  Hopefully this will be deduced
by default at install time.

If you're using the GNU C++ compiler, make sure that you have the g++ front
end installed (some Linux distros don't install it by default, but provide
it via their package management utilities).

=head1 Using Inline::CPP

Inline::CPP is very similar to Inline::C, and in most cases can be used in
place of Inline::C without changing a single line of Perl or C code. If you
haven't done so already, you should stop reading right now and read the
documentation for L<Inline::C>, including the L<Inline::C-Cookbook>.

This module uses a  grammar to parse your C++ code, and binds to functions or
classes which are recognized. If a function is recognized, it will be available
from Perl space. If the function's signature is not recognized, it will not
be available from Perl, but will be available from other functions or classes
within the C++ code.

The following example shows how C++ snippets map to Perl:

Example 1:

    use Inline CPP => <<'END';

    using namespace std;

    int doodle() { }

    class Foo {
     public:
       Foo();
       ~Foo();

       int get_data() { return data; }
{'fraction_non_alphanumeric': 0.06327744726879395, 'fraction_numerical': 0.0045069406886605375, 'mean_word_length': 3.8492132867132867, 'pattern_counts': {'":': 0, '<': 55, '<?xml version=': 0, '>': 53, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1156787', 'n_tokens_mistral': 3186, 'n_tokens_neox': 3000, 'n_words': 1815}