NAME

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

Glob

Overview

The Glob class is the wrapper around Perls GV* type, which is a variant of SV*. As with Scalar, it might hold an underlying Perl SV* or might not.

The Glob 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.

A GV is a structure which corresponds to a Perl typeglob, ie *foo. It is a structure that holds a pointer to a scalar, an array, a hash etc, corresponding to $foo, @foo, %foo.

GVs are usually found as values in stashes (symbol table hashes) where Perl stores its global variables.

Construction

To create a new GV* in Perl, the Stash object and the name should be provided:

static Glob create (const Stash& stash, panda::string_view name, U32 flags = 0);

For the flags description please refer gv_init_pvn in perlapi.

To create an wrapper around existing GV* the following constructors can be used:

Glob (std::nullptr_t = nullptr)
Glob (SV* sv, bool policy = INCREMENT)
Glob (GV* sv, bool policy = INCREMENT)

If SV* or <GV*> are undef or NULL, the returned Glob object will be empty. Otherwise, if unappropriate SV* is supplied, then exception will be thrown.

Copy and move-constructore are also available:

Glob (const Glob&   oth)
Glob (Glob&&        oth)
Glob (const Scalar& oth)
Glob (Scalar&&      oth)
Glob (const Sv&     oth)
Glob (Sv&&          oth)

assignment operators

Glob& operator= (SV* val)
Glob& operator= (GV* val)
Glob& operator= (const Glob& oth)
Glob& operator= (Glob&& oth)
Glob& operator= (const Scalar& oth)
Glob& operator= (Scalar&& oth)
Glob& operator= (const Sv& oth)
Glob& 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)
void set (GV* val)

The set method directly assigns the value to the underlying SV*, bypassing all checks. Use the method with caution.

getters

Theere are zero-cost NULL-safe getters:

operator GV* () const
GV* operator->() const
template <typename T = SV> one_of_t<T,SV,GV>* get () const

This are NULL-safe methods. The returned value, however, might be NULL.

slot ()

template <typename T> one_of_t<T,Scalar,Array,Hash,Sub> slot () const
void slot (SV*)
void slot (AV*)
void slot (HV*)
void slot (CV*)
void slot (IO*)
void slot (const Scalar&)
void slot (const Sv&     v)
void slot (const Array&  v)
void slot (const Hash&   v)
void slot (const Sub&    v)
void slot (const Io&     v)

This are read/write accessors for appropriate slot type in the Glob instance. For example:

Stash s = ...;
Glob o = s["some_name"];
Sub sub = o.slot<Sub>();

The slot methods are NULL-unsafe.

scalar()

array()

hash()

sub()

io()

Scalar scalar () const
Array  array  () const
Hash   hash   () const
Sub    sub    () const
Io     io     () const

void scalar (const Scalar& val)
void array  (const Array&  val)
void hash   (const Hash&   val)
void sub    (const Sub&    val)
void io     (const Io&     val)

This group of methods provide convenient access to scalar/array/hash/sub/io slot of the Glob. The read accessors are NULL-safe, while write-accessors are NULL-unsafe.

get_const()

Sv get_const () const

If Sub-slot is eligible for inlining it returns the valuer returned by the Sub wrapped into Sv. Otherwise emptu Sv is returned.

This is NULL-unsafe method.

stash()

effective_stash

Stash stash           () const
Stash effective_stash () const

Returns the current or effective Stash associated with the Glob instance.

This are NULL-unsafe methods.

name()

effective_name ()

panda::string_view name           () const
panda::string_view effective_name () const

Returns the name of the current or effective Stash associated with the Glob instance.