The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
XS-Framework-1.5.6
River stage two • 24 direct dependents • 30 total dependents
/ XS::Framework::Manual::SVAPI::Simple

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

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

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

Simple& operator= (const panda::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 (panda::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 panda::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, panda::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 panda::string_view& rhs)
inline bool operator== (const panda::string_view& lhs, const Simple& rhs)
inline bool operator!= (const Simple& lhs, const panda::string_view& rhs)
inline bool operator!= (const panda::string_view& lhs, const Simple& rhs)
inline bool operator>  (const Simple& lhs, const panda::string_view& rhs)
inline bool operator>  (const panda::string_view& lhs, const Simple& rhs)
inline bool operator>= (const Simple& lhs, const panda::string_view& rhs)
inline bool operator>= (const panda::string_view& lhs, const Simple& rhs)
inline bool operator<  (const Simple& lhs, const panda::string_view& rhs)
inline bool operator<  (const panda::string_view& lhs, const Simple& rhs)
inline bool operator<= (const Simple& lhs, const panda::string_view& rhs)
inline bool operator<= (const panda::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