NAME

XS::Framework::Manual::SVAPI::Ref - XS::Framework Ref C++ class reference

Ref

Overview

The Ref class purpose is to hold a reference to any other Perl object.

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.

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.

Construction

    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):

    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)

assignment operators

    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.

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.

value()

It is possble to deref the held SV* via NULL-safe value() method:

    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:

    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.

SEE ALSO

XS::Framework

XS::Framework::Manual::SVAPI

XS::Framework::Manual::SVAPI::Sv

XS::Framework::Manual::SVAPI::Scalar

cpanm XS::Framework

perl -MCPAN -e shell
install XS::Framework