NAME

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

Scalar

Overview

The Scalar class is the wrapper around Perls SV* object, which helds either primitive value like number or string, or reference to object, array or hash or Glob. So, is base class for Simple, Ref and Glob.

As with Sv, it might hold an underlying Perl SV* or might not.

The notable difference from all other classes is that Scalar might held undef and it is not considered empty.

Construction

    static const Scalar undef;
    static const Scalar yes;
    static const Scalar no;

Out of the box Scalar offers a few constants for Perl's undef and true and false values.

    static Scalar create()

The create method return new non-empty Scalar, which holds zero-length string. It is opposite to the constructor with nullptr below, which creates empty scalar:

    Scalar (std::nullptr_t = nullptr) {}

The other constructors and helper methods just wrap existing Perl scalar SV* or GV* into Scalar object:

    static Scalar noinc (SV* val)
    static Scalar noinc (GV* val)

    Scalar (SV* sv, bool policy = INCREMENT)
    Scalar (GV* sv, bool policy = INCREMENT)

If SV* pointing to undef is porovided, it will be held and Scalar object will not be considered empty.

Copy and move-constructore are also available:

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

It it possible to create Scalar object from CallProxy invocation:

    Scalar (const CallProxy& p)

however, please note, that the CallProxy will be called in scalar context.

assignment operators

    Scalar& operator= (SV* val)
    Scalar& operator= (GV* val)
    Scalar& operator= (const Scalar& oth)
    Scalar& operator= (Scalar&& oth)
    Scalar& operator= (const Sv& oth)
    Scalar& operator= (Sv&& oth)
    Scalar& operator= (const CallProxy& p)

The assignment operators are complementaty to the constructors above. They inherit behaviour from Sv, including NULL-safety. The previously held SV* will be dec-remented.

    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:

    template <class T = SV> one_of_t<T,SV,GV>* get () const

This are NULL-safe methods.

upgrade()

    void upgrade (svtype type)

Tries to upgrade SV* into the specified type. Exception is thrown if the variable is already marked as readonly or upon attempt to upgrade defined scalar (non-undef) into more than SVt_PVMG.

This is NULL-unsafe method.

as_string()

    template <class T = panda::string> T as_string () const

Stringizes the current Scalar object. Valid if the held Scalar can be constructed as Simple object, e.g. as number or string. Otherwise exception is thrown. The <T> parameter can be std::string, std::string_view or panda::string.

This is NULL-unsafe method.

as_number()

    template <class T = int> T as_number () const

Numberifies the current Scalar object. Valid if the held Scalar can be constructed as Simple object, e.g. as number or string. Otherwise exception is thrown. The <T> parameter can be any arithmetic type, conforming

    std::is_arithmetic<T>

concept from C++ library.

SEE ALSO

XS::Framework

XS::Framework::Manual::SVAPI

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

XS::Framework::Manual::SVAPI::Simple

XS::Framework::Manual::SVAPI::Ref

XS::Framework::Manual::SVAPI::Glob

cpanm XS::Framework

perl -MCPAN -e shell
install XS::Framework