XS::Framework::Manual::SVAPI::Ref - XS::Framework Ref C++ class reference
Ref class purpose is to hold a reference to any other Perl object.
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.
Ref object does not holds
undef is assigned or supplied in constructor, the object is considered empty. In other words the
NULL have the same meaning for the class.
Ref (std::nullptr_t = nullptr) Ref (SV* sv, bool policy = INCREMENT)
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
RV* type; otherwise an exception will be thrown.
create methods below create an reference to the supplied argument (in opposite to the constructor above):
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.
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)
It it possible to create
Ref object from
CallProxy invocation. In that case the
Ref instance will hold the reference to the result (similar to
Ref (const CallProxy& p)
however, please note, that the
CallProxy will be called in scalar context.
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) Ref& operator= (const CallProxy& p)
The assignment operators are complementaty to the constructors above. They inherit behaviour from
Scalar, including NULL-safety. The previously held
SV* will be
The last operator performs proxy call in scalar context, the same as in appropriate constructor above.
void set (SV* val)
set method directly assigns the value to the underlying
SV*, bypassing all checks. Use the method with caution.
It is possble to deref the held
SV* via NULL-safe
template <class T = Sv> one_of_t<T,Sv,Scalar,Simple,Array,Hash,Sub,Stash,Glob,Ref,Object> value () const
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:
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.