XS::Framework::Manual::SVAPI::Ref - XS::Framework Ref C++ class reference
The Ref class purpose is to hold a reference to any other Perl object.
Ref
The Ref class is the wrapper around Perls RV* type, which is a variant of SV*. As with Sv, it might hold an underlying Perl SV* or might not.
RV*
SV*
Sv
The Ref object does not holds undef; if undef is assigned or supplied in constructor, the object is considered empty. In other words the undef and NULL have the same meaning for the class.
undef
NULL
Ref (std::nullptr_t = nullptr) Ref (SV* sv, bool policy = INCREMENT)
The new Ref is created, and it either takes ownership on the underlying SV* with corresponding refcounting policy, or just empty wrapper is created, which holds no value. It is expected that the supplied SV* be RV* type; otherwise an exception will be thrown.
The create methods below create an reference to the supplied argument (in opposite to the constructor above):
create
static Ref create (SV* sv = nullptr, bool policy = INCREMENT) static Ref create (AV* sv, bool policy = INCREMENT) static Ref create (HV* sv, bool policy = INCREMENT) static Ref create (CV* sv, bool policy = INCREMENT) static Ref create (GV* sv, bool policy = INCREMENT) static Ref create (const Sv& o)
In the last case for const Sv& the INCREMENT policy is applied.
const Sv&
INCREMENT
Copy and move-constructore are also available:
Ref (const Ref& oth) Ref (Ref&& oth) Ref (const Scalar& oth) Ref (Scalar&& oth) Ref (const Sv& oth) Ref (Sv&& oth)
Ref& operator= (SV* val) Ref& operator= (const Ref& oth) Ref& operator= (Ref&& oth) Ref& operator= (const Scalar& oth) Ref& operator= (Scalar&& oth) Ref& operator= (const Sv& oth) Ref& operator= (Sv&& oth)
The assignment operators are complementaty to the constructors above. They inherit behaviour from Scalar, including NULL-safety. The previously held SV* will be dec-remented.
Scalar
dec
The last operator performs proxy call in scalar context, the same as in appropriate constructor above.
void set (SV* val)
The set method directly assigns the value to the underlying SV*, bypassing all checks. Use the method with caution.
set
It is possble to deref the held SV* via NULL-safe value() method:
value()
template <class T = Sv> one_of_t<T,Sv,Scalar,Simple,Array,Hash,Sub,Stash,Glob,Ref,Object> value () const
for example:
Ref r = ...; Simple s = r.value<Simple>();
Please note, if the dereferenced value is incompatible with the destination, the exception will be thrown.
To assing the new value, to which the current ref object will point to, the following NULL-safe methods can be used:
ref
void value (SV* val, bool policy = INCREMENT) void value (AV* val, bool policy = INCREMENT) void value (HV* val, bool policy = INCREMENT) void value (CV* val, bool policy = INCREMENT) void value (GV* val, bool policy = INCREMENT) void value (const Sv& val) void value (std::nullptr_t)
Please note, this is different from the assignment operator above: the assignment operator expects that the suplied SV* be already a reference, while value() method expects referenced value to be provided.
XS::Framework
XS::Framework::Manual::SVAPI
XS::Framework::Manual::SVAPI::Sv
XS::Framework::Manual::SVAPI::Scalar
To install XS::Framework, copy and paste the appropriate command in to your terminal.
cpanm
cpanm XS::Framework
CPAN shell
perl -MCPAN -e shell install XS::Framework
For more information on module installation, please visit the detailed CPAN module installation guide.