—

              
HideShow 284 lines of Pod
=head1 NAME
XS::Framework::Manual::SVAPI::Simple - XS::Framework Simple C++ class reference
=head1 Simple
=head2 Overview
The C<Simple> class is the wrapper around Perls C<SV*> object, which helds
primitive value like number (float, double, integer etc.) or string.
As with C<Scalar>, it might held an underlying Perl C<SV*> or might not.
As with C<Scalar>, C<Simple> might held the <undef> the the object is not
considered empty.
=head2 Construction
    static const Simple undef;
    static const Simple yes;
    static const Simple no;
Out of the box C<Simple> offers a few constants for Perl's C<undef> and
C<true> and C<false> values.
    static Simple create (size_t capacity)
The C<create> method return new non-empty C<Simple>, which reserves
C<capacity> bytes for the binary string.
To create C<Simple> object with C<sprintf>-like formatter, the C<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 C<nullptr> is passed as argument:
    Simple (std::nullptr_t = nullptr) {}
The most generic C<Simple> constructor is
    static Simple noinc (SV* val)
    Simple (SV* sv, bool policy = INCREMENT)
it wraps the underlyging Perl C<SV*> if it helds primitive value, including
C<undef>.
It is possible to construct C<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 C<Simple> object from C<HEK*>.
Basically it is the string with precomputed hash number. It is useful for fast
value lookup in the C<Hash> class.
    static Simple shared (HEK* k)
    static Simple shared (const panda::string_view& s, U32 hash = 0)
=head2 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 C<Sv>, including NULL-safety. The previously held
C<SV*> will be C<dec>-remented.
    template <typename T, typename = arithmetic_t<T>>
    void set (T val)
    void set (panda::string_view s)
    void set (SV* val)
The C<set> method directly assigns the value to the underlying C<SV*>,
I<bypassing all checks>. Use the method with caution.
=head2 getters
The C<Simple> object provides type-coersion operators for C<bool> and
number contexts, i.e.:
    using Sv::operator bool;
    template <class T, typename = arithmetic_t<T>> operator T () const
The C<bool> operator returns C<true> if C<Simple> object is non-empty,
i.e. it helds any value, including C<undef>.
In number context it C<Simple> tries to extract number from the underlying
C<SV*>. If the C<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 C<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
=head2 operator[]
    char  operator[] (size_t i) const
    char& operator[] (size_t i)
This operator provides char level access for a string of the underlying
C<SV*>. The boundary-check is not performed, so use the method with caution
This is null-unsafe method.
=head2 at()
    char at (size_t i)
This method returns copy of a char. This method checks string boundary, and
if C<i> is out of bound, then exception is thrown.
This is null-safe method.
=head2 is_string()
    bool   is_string () const
Returns C<true> if the underlying C<SV*> contains character string.
This is null-safe method.
=head2 is_shared ()
    bool   is_shared () const
Returns a boolean indicating whether the underlying C<SV*>
is Copy-On-Write shared hash key scalar.
This is null-safe method.
=head2 length()
=head2 length(STRLEN newlen)
    STRLEN length    () const
    void   length    (STRLEN newlen)
Gets or sets the length of the string of the underlying C<SV*>.
This are null-unsafe methods.
=head2 capacity()
    STRLEN capacity  () const
Returns the size of the string buffer in the underlying C<SV*>.
This is null-unsafe method.
=head2 utf8()
    bool   utf8      () const
    void   utf8      (bool val)
Sets or gets the UTF-8 flag on the underlying C<SV*>.
This is null-unsafe method.
=head2 hash()
    U32 hash () const;
Returns hash number for the underlying C<SV*>.
This is null-unsafe method.
=head2 hek()
    HEK* hek () const
Returns C<HEK*>, i.e. string with precomputed hash number. It is useful
for fast value lookup in C<Hash> classes.
This is null-unsafe method.
=head2 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 C<cmp> operator, but
there is operator overloading, so there are multiple overloads for string
and number variants. All the operations are NULL-safe.
=head1 SEE ALSO
L<XS::Framework>
L<XS::Framework::Manual::SVAPI>
L<XS::Framework::Manual::SVAPI::Sv>
L<XS::Framework::Manual::SVAPI::Scalar>
=cut