Initial Commit

database/perl/vendor/lib/FFI/Raw/MemPtr.pm

@@ -0,0 +1,91 @@
+package FFI::Raw::MemPtr;
+$FFI::Raw::MemPtr::VERSION = '0.32';
+use strict;
+use warnings;
+
+=head1 NAME
+
+FFI::Raw::MemPtr - FFI::Raw memory pointer type
+
+=head1 VERSION
+
+version 0.32
+
+=head1 DESCRIPTION
+
+A B<FFI::Raw::MemPtr> represents a memory pointer which can be passed to
+functions taking a C<FFI::Raw::ptr> argument.
+
+The allocated memory is automatically deallocated once the object is not in use
+anymore.
+
+=head1 METHODS
+
+=head2 new( $length )
+
+Allocate a new C<FFI::Raw::MemPtr> of size C<$length> bytes.
+
+=head2 new_from_buf( $buffer, $length )
+
+Allocate a new C<FFI::Raw::MemPtr> of size C<$length> bytes and copy C<$buffer>
+into it. This can be used, for example, to pass a pointer to a function that
+takes a C struct pointer, by using C<pack()> or the L<Convert::Binary::C> module
+to create the actual struct content.
+
+For example, consider the following C code
+
+    struct some_struct {
+      int some_int;
+      char some_str[];
+    };
+
+    extern void take_one_struct(struct some_struct *arg) {
+      if (arg -> some_int == 42)
+        puts(arg -> some_str);
+    }
+
+It can be called using FFI::Raw as follows:
+
+    use FFI::Raw;
+
+    my $packed = pack('ix![p]p', 42, 'hello');
+    my $arg = FFI::Raw::MemPtr -> new_from_buf($packed, length $packed);
+
+    my $take_one_struct = FFI::Raw -> new(
+      $shared, 'take_one_struct',
+      FFI::Raw::void, FFI::Raw::ptr
+    );
+
+    $take_one_struct -> ($arg);
+
+Which would print C<hello>.
+
+=head2 new_from_ptr( $ptr )
+
+Allocate a new C<FFI::Raw::MemPtr> pointing to the C<$ptr>, which can be either
+a C<FFI::Raw::MemPtr> or a pointer returned by another function.
+
+This is the C<FFI::Raw> equivalent of a pointer to a pointer.
+
+=head2 tostr( [$length] )
+
+Convert a C<FFI::Raw::MemPtr> to a Perl string. If C<$length> is not provided,
+the length of the string will be computed using C<strlen()>.
+
+=head1 AUTHOR
+
+Alessandro Ghedini <alexbio@cpan.org>
+
+=head1 LICENSE AND COPYRIGHT
+
+Copyright 2013 Alessandro Ghedini.
+
+This program is free software; you can redistribute it and/or modify it
+under the terms of either: the GNU General Public License as published
+by the Free Software Foundation; or the Artistic License.
+
+See http://dev.perl.org/licenses/ for more information.
+
+=cut
+
+1; # End of FFI::Raw::MemPtr