.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Class::XSAccessor::Array 3pm"
.TH Class::XSAccessor::Array 3pm "2021-02-02" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Class::XSAccessor::Array \- Generate fast XS accessors without runtime compilation
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\&  package MyClassUsingArraysAsInternalStorage;
\&  use Class::XSAccessor::Array
\&    constructor => \*(Aqnew\*(Aq,
\&    getters => {
\&      get_foo => 0, # 0 is the array index to access
\&      get_bar => 1,
\&    },
\&    setters => {
\&      set_foo => 0,
\&      set_bar => 1,
\&    },
\&    accessors => { # a mutator
\&      buz => 2,
\&    },
\&    predicates => { # test for definedness
\&      has_buz => 2,
\&    },
\&    lvalue_accessors => { # see below
\&      baz => 3,
\&    },
\&    true => [ \*(Aqis_token\*(Aq, \*(Aqis_whitespace\*(Aq ],
\&    false => [ \*(Aqsignificant\*(Aq ];
\&  
\&  # The imported methods are implemented in fast XS.
\&  
\&  # normal class code here.
.Ve
.PP
As of version 1.05, some alternative syntax forms are available:
.PP
.Vb 1
\&  package MyClass;
\&  
\&  # Options can be passed as a HASH reference if you prefer it,
\&  # which can also help PerlTidy to flow the statement correctly.
\&  use Class::XSAccessor {
\&    getters => {
\&      get_foo => 0,
\&      get_bar => 1,
\&    },
\&  };
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The module implements fast \s-1XS\s0 accessors both for getting at and
setting an object attribute. Additionally, the module supports
mutators and simple predicates (\f(CW\*(C`has_foo()\*(C'\fR like tests for definedness
of an attributes).
The module works only with objects
that are implemented as \fBarrays\fR. Using it on hash-based objects is
bound to make your life miserable. Refer to Class::XSAccessor for
an implementation that works with hash-based objects.
.PP
A simple benchmark showed a significant performance
advantage over writing accessors in Perl.
.PP
Since version 0.10, the module can also generate simple constructors
(implemented in \s-1XS\s0) for you. Simply supply the
\&\f(CW\*(C`constructor => \*(Aqconstructor_name\*(Aq\*(C'\fR option or the
\&\f(CW\*(C`constructors => [\*(Aqnew\*(Aq, \*(Aqcreate\*(Aq, \*(Aqspawn\*(Aq]\*(C'\fR option.
These constructors do the equivalent of the following Perl code:
.PP
.Vb 4
\&  sub new {
\&    my $class = shift;
\&    return bless [], ref($class)||$class;
\&  }
.Ve
.PP
That means they can be called on objects and classes but will not
clone objects entirely. Note that any parameters to \fBnew()\fR will be
discarded! If there is a better idiom for array-based objects, let
me know.
.PP
While generally more obscure than hash-based objects,
objects using blessed arrays as internal representation
are a bit faster as its somewhat faster to access arrays than hashes.
Accordingly, this module is slightly faster (~10\-15%) than
Class::XSAccessor, which works on hash-based objects.
.PP
The method names may be fully qualified. In the example of the
synopsis, you could have written \f(CW\*(C`MyClass::get_foo\*(C'\fR instead
of \f(CW\*(C`get_foo\*(C'\fR. This way, you can install methods in classes other
than the current class. See also: The \f(CW\*(C`class\*(C'\fR option below.
.PP
Since version 1.01, you can generate extremely simple methods which
just return true or false (and always do so). If that seems like a
really superfluous thing to you, then think of a large class hierarchy
with interfaces such as \s-1PPI.\s0 This is implemented as the \f(CW\*(C`true\*(C'\fR
and \f(CW\*(C`false\*(C'\fR options, see synopsis.
.SH "OPTIONS"
.IX Header "OPTIONS"
In addition to specifying the types and names of accessors, you can add options
which modify behaviour. The options are specified as key/value pairs just as the
accessor declaration. Example:
.PP
.Vb 5
\&  use Class::XSAccessor::Array
\&    getters => {
\&      get_foo => 0,
\&    },
\&    replace => 1;
.Ve
.PP
The list of available options is:
.SS "replace"
.IX Subsection "replace"
Set this to a true value to prevent \f(CW\*(C`Class::XSAccessor::Array\*(C'\fR from
complaining about replacing existing subroutines.
.SS "chained"
.IX Subsection "chained"
Set this to a true value to change the return value of setters
and mutators (when called with an argument).
If \f(CW\*(C`chained\*(C'\fR is enabled, the setters and accessors/mutators will
return the object. Mutators called without an argument still
return the value of the associated attribute.
.PP
As with the other options, \f(CW\*(C`chained\*(C'\fR affects all methods generated
in the same \f(CW\*(C`use Class::XSAccessor::Array ...\*(C'\fR statement.
.SS "class"
.IX Subsection "class"
By default, the accessors are generated in the calling class. Using
the \f(CW\*(C`class\*(C'\fR option, you can explicitly specify where the methods
are to be generated.
.SH "LVALUES"
.IX Header "LVALUES"
Support for lvalue accessors via the keyword \f(CW\*(C`lvalue_accessors\*(C'\fR
was added in version 1.08. At this point, \fB\s-1THEY ARE CONSIDERED HIGHLY
EXPERIMENTAL\s0\fR. Furthermore, their performance hasn't been benchmarked
yet.
.PP
The following example demonstrates an lvalue accessor:
.PP
.Vb 4
\&  package Address;
\&  use Class::XSAccessor
\&    constructor => \*(Aqnew\*(Aq,
\&    lvalue_accessors => { zip_code => 0 };
\&  
\&  package main;
\&  my $address = Address\->new(2);
\&  print $address\->zip_code, "\en"; # prints 2
\&  $address\->zip_code = 76135; # <\-\-\- This is it!
\&  print $address\->zip_code, "\en"; # prints 76135
.Ve
.SH "CAVEATS"
.IX Header "CAVEATS"
Probably wouldn't work if your objects are \fItied\fR. But that's a strange thing to do anyway.
.PP
Scary code exploiting strange \s-1XS\s0 features.
.PP
If you think writing an accessor in \s-1XS\s0 should be a laughably simple exercise, then
please contemplate how you could instantiate a new \s-1XS\s0 accessor for a new hash key
or array index that's only known at run-time. Note that compiling C code at run-time
a la Inline::C is a no go.
.PP
Threading. With version 1.00, a memory leak has been \fBfixed\fR that would leak a small amount of
memory if you loaded \f(CW\*(C`Class::XSAccessor\*(C'\fR\-based classes in a subthread that hadn't been loaded
in the \*(L"main\*(R" thread before. If the subthread then terminated, a hash key and an int per
associated method used to be lost. Note that this mattered only if classes were \fBonly\fR loaded
in a sort of throw-away thread.
.PP
In the new implementation as of 1.00, the memory will not be released again either in the above
situation. But it will be recycled when the same class or a similar class is loaded
again in \fBany\fR thread.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Class::XSAccessor
.PP
AutoXS
.SH "AUTHOR"
.IX Header "AUTHOR"
Steffen Mueller <smueller@cpan.org>
.PP
chocolateboy <chocolate@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2008, 2009, 2010, 2011, 2012, 2013 by Steffen Mueller
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8 or,
at your option, any later version of Perl 5 you may have available.