The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

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

Simple

Overview

The Simple class is the wrapper around Perls SV* object, which helds primitive value like number (float, double, integer etc.) or string.

As with Scalar, it might held an underlying Perl SV* or might not.

As with Scalar, Simple might held the <undef> the the object is not considered empty.

Construction

    static const Simple undef;
    static const Simple yes;
    static const Simple no;

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

    static Simple create (size_t capacity)

The create method return new non-empty Simple, which reserves capacity bytes for the binary string.

To create Simple object with sprintf-like formatter, the format helper method can be used:

    static Simple format (const char*const pat, ...)

For example,

    Simple obj = Simple::format("pi = %0.2f", 3.14157);

The empty wrapper can be created if nullptr is passed as argument:

    Simple (std::nullptr_t = nullptr) {}

The most generic Simple constructor is

    static Simple noinc (SV* val)
    Simple (SV* sv, bool policy = INCREMENT)

it wraps the underlyging Perl SV* if it helds primitive value, including undef.

It is possible to construct Simple instance from number or string via:

    template <class T, typename = arithmetic_t<T>> explicit Simple (T val)
    Simple (const std::string_view& s)

Copy and move-constructore are also available:

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

It it possible to create Simple object from CallProxy invocation:

    Simple (const CallProxy& p)

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

There is a special method that creates an Simple object from HEK*. Basically it is the string with precomputed hash number. It is useful for fast value lookup in the Hash class.

    static Simple shared (HEK* k)
    static Simple shared (const std::string_view& s, U32 hash = 0)

assignment operators

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

    template <typename T, typename = arithmetic_t<T>>
    Simple& operator= (T val)

    Simple& operator= (const std::string_view& s)

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.

    template <typename T, typename = arithmetic_t<T>>
    void set (T val)

    void set (std::string_view s)
    void set (SV* val)

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

getters

The Simple object provides type-coersion operators for bool and number contexts, i.e.:

    using Sv::operator bool;
    template <class T, typename = arithmetic_t<T>> operator T () const

The bool operator returns true if Simple object is non-empty, i.e. it helds any value, including undef.

In number context it Simple tries to extract number from the underlying SV*. If the Simple instance is empty zero of appropriate type is returned. So, this are NULL-safe methods.

    operator std::string_view () const
    const char* c_str () const
    template <class T = panda::string> T as_string () const

The Simple instance can be coersed to <string> too; in case of empty object, the empty string is returned. So, this are NULL-safe methods.

There are a few NULL-unsafe but fast getters:

    template <typename T>      arithmetic_t<T>               get () const
    template <typename T>      one_of_t<T,char*,const char*> get () const
    template <typename T>      one_of_t<T, std::string_view> get () const
    template <typename T = SV> one_of_t<T,SV>*               get () const

operator[]

    char  operator[] (size_t i) const
    char& operator[] (size_t i)

This operator provides char level access for a string of the underlying SV*. The boundary-check is not performed, so use the method with caution

This is null-unsafe method.

at()

    char at (size_t i)

This method returns copy of a char. This method checks string boundary, and if i is out of bound, then exception is thrown.

This is null-safe method.

is_string()

    bool   is_string () const

Returns true if the underlying SV* contains character string.

This is null-safe method.

is_shared ()

    bool   is_shared () const

Returns a boolean indicating whether the underlying SV* is Copy-On-Write shared hash key scalar.

This is null-safe method.

length()

length(STRLEN newlen)

    STRLEN length    () const
    void   length    (STRLEN newlen)

Gets or sets the length of the string of the underlying SV*.

This are null-unsafe methods.

capacity()

    STRLEN capacity  () const

Returns the size of the string buffer in the underlying SV*.

This is null-unsafe method.

utf8()

    bool   utf8      () const
    void   utf8      (bool val)

Sets or gets the UTF-8 flag on the underlying SV*.

This is null-unsafe method.

hash()

    U32 hash () const;

Returns hash number for the underlying SV*.

This is null-unsafe method.

hek()

    HEK* hek () const

Returns HEK*, i.e. string with precomputed hash number. It is useful for fast value lookup in Hash classes.

This is null-unsafe method.

operators ==(), !=(), >, >=, <, <=

    template <typename T, typename = arithmetic_t<T>> inline bool operator== (const Simple& lhs, T rhs)
    template <typename T, typename = arithmetic_t<T>> inline bool operator== (T lhs, const Simple& rhs)
    template <typename T, typename = arithmetic_t<T>> inline bool operator!= (const Simple& lhs, T rhs)
    template <typename T, typename = arithmetic_t<T>> inline bool operator!= (T lhs, const Simple& rhs)
    template <typename T, typename = arithmetic_t<T>> inline bool operator>  (const Simple& lhs, T rhs)
    template <typename T, typename = arithmetic_t<T>> inline bool operator>  (T lhs, const Simple& rhs)
    template <typename T, typename = arithmetic_t<T>> inline bool operator>= (const Simple& lhs, T rhs)
    template <typename T, typename = arithmetic_t<T>> inline bool operator>= (T lhs, const Simple& rhs)
    template <typename T, typename = arithmetic_t<T>> inline bool operator<  (const Simple& lhs, T rhs)
    template <typename T, typename = arithmetic_t<T>> inline bool operator<  (T lhs, const Simple& rhs)
    template <typename T, typename = arithmetic_t<T>> inline bool operator<= (const Simple& lhs, T rhs)
    template <typename T, typename = arithmetic_t<T>> inline bool operator<= (T lhs, const Simple& rhs)

    inline bool operator== (const Simple& lhs, const std::string_view& rhs)
    inline bool operator== (const std::string_view& lhs, const Simple& rhs)
    inline bool operator!= (const Simple& lhs, const std::string_view& rhs)
    inline bool operator!= (const std::string_view& lhs, const Simple& rhs)
    inline bool operator>  (const Simple& lhs, const std::string_view& rhs)
    inline bool operator>  (const std::string_view& lhs, const Simple& rhs)
    inline bool operator>= (const Simple& lhs, const std::string_view& rhs)
    inline bool operator>= (const std::string_view& lhs, const Simple& rhs)
    inline bool operator<  (const Simple& lhs, const std::string_view& rhs)
    inline bool operator<  (const std::string_view& lhs, const Simple& rhs)
    inline bool operator<= (const Simple& lhs, const std::string_view& rhs)
    inline bool operator<= (const std::string_view& lhs, const Simple& rhs)

    inline bool operator== (const Simple& lhs, const char* rhs)
    inline bool operator== (const char* lhs, const Simple& rhs)
    inline bool operator!= (const Simple& lhs, const char* rhs)
    inline bool operator!= (const char* lhs, const Simple& rhs)
    inline bool operator>  (const Simple& lhs, const char* rhs)
    inline bool operator>  (const char* lhs, const Simple& rhs)
    inline bool operator>= (const Simple& lhs, const char* rhs)
    inline bool operator>= (const char* lhs, const Simple& rhs)
    inline bool operator<  (const Simple& lhs, const char* rhs)
    inline bool operator<  (const char* lhs, const Simple& rhs)
    inline bool operator<= (const Simple& lhs, const char* rhs)
    inline bool operator<= (const char* lhs, const Simple& rhs)

    inline bool operator== (const Simple& lhs, char* rhs)
    inline bool operator== (char* lhs, const Simple& rhs)
    inline bool operator!= (const Simple& lhs, char* rhs)
    inline bool operator!= (char* lhs, const Simple& rhs)
    inline bool operator>  (const Simple& lhs, char* rhs)
    inline bool operator>  (char* lhs, const Simple& rhs)
    inline bool operator>= (const Simple& lhs, char* rhs)
    inline bool operator>= (char* lhs, const Simple& rhs)
    inline bool operator<  (const Simple& lhs, char* rhs)
    inline bool operator<  (char* lhs, const Simple& rhs)
    inline bool operator<= (const Simple& lhs, char* rhs)
    inline bool operator<= (char* lhs, const Simple& rhs)

This is group of comparison operators. C++ does not has cmp operator, but there is operator overloading, so there are multiple overloads for string and number variants. All the operations are NULL-safe.

SEE ALSO

XS::Framework

XS::Framework::Manual::SVAPI

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

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