=head1 NAME
XS::Framework::Manual::SVAPI::Hash - XS::Framework Hash C++ class reference
=head1 Hash
=head2 Overview
The C<Hash> class is the wrapper around Perls C<HV*> type, which is a variant
of C<SV*>. As with C<Sv>, it might hold an underlying Perl hash C<HV*> or might
not.
=head2 Construction
static Hash noinc (SV* val)
static Hash noinc (HV* val)
Hash (std::nullptr_t = nullptr)
Hash (SV* sv, bool policy = INCREMENT)
Hash (HV* sv, bool policy = INCREMENT)
The new C<Hash> is created, and it either takes ownership on the underlying
C<SV*>/C<HV*> with corresponding refcounting policy, or just empty wrapper
is created, which holds no value. On invalid C<SV*>, e.g. pointer to Arrray,
an exception will be thrown. The valid C<SV*> should be either C<HV*> or
reference to C<HV*> or C<undef>.
Please, note, that empty C<Hash> means that it holds no value (aka NULL),
it is not the same, when it holds underlying empty HV* with zero items.
static Hash create()
static Hash create (size_t cap)
It is possible to create new C<Hash> with empty underlying C<HV*>, optionally
reserving space for C<cap> items (SV*).
It is possible to create Hash object in-place via itializer list, which should
contain name (C<string>) / value (C<Scalar>) pairs, i.e.:
static Hash create (std::initializer_list<std::tuple<panda::string_view, Scalar>> l)
Hash (std::initializer_list<std::tuple<panda::string_view, Scalar>>)
For example,
auto h = Hash::create({
{"key-int", Simple(1)},
{"key-string", Simple("val2")},
});
The copy and move constructors are also available:
Hash (const Hash& oth)
Hash (Hash&& oth)
Hash (const Sv& oth)
Hash (Sv&& oth)
=head2 assignment operators
Hash& operator= (SV* val)
Hash& operator= (HV* val)
Hash& operator= (const Hash& oth)
Hash& operator= (Hash&& oth)
Hash& operator= (const Sv& oth)
Hash& operator= (Sv&& oth)
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.
The last operator performs proxy call in B<scalar> context, the same as in
appropriate constructor above.
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
There are zero-cost NULL-safe getters:
operator HV* () const
HV* operator-> () const
template <typename T = SV> one_of_t<T,SV,HV>* get ()
For example,
Hash hash = ...;
HV* hv = hash.get<HV>();
=head2 element access
Scalar fetch (const panda::string_view& key) const
Scalar at (const panda::string_view& key) const
Scalar operator[] (const panda::string_view& key) const
KeyProxy operator[] (const panda::string_view& key)
The first three methods return C<Scalar> type. C<fetch> provides bounary-safe
access to the elements, if the index is out of bounds, then empty C<Scalar>
is returned and underlying C<HV*> is kept untouched. The C<at> method also
checks key existance, and if it is not found, then an exception will
be thrown (similar to C<std::map::at()>). The C<operator[]> is an alias
for C<fetch>. The non-const acccessor is needed to allow
in-place fast modification and lazy creation of underlying element, i.e.
Hash hash = ...;
hash["key"] = Simple(10);
C<fetch>, C<at> and C<operator[] const> are NULL-safe; while mofifying
C<operator[]> is NULL-unsafe.
void store (const panda::string_view& key, const Scalar& val, U32 hash = 0)
void store (const panda::string_view& key, std::nullptr_t, U32 hash = 0)
void store (const panda::string_view& key, SV* v, U32 hash = 0)
void store (const panda::string_view& key, const Sv& v, U32 hash = 0)
The C<store> method is used store item in the hash. If underlyging Perl
array HV* is NULL, then C<store> will throw exception.
The C<hash> parameter is the precomputed hash value; if it is
zero then Perl will compute it.
To check element existance, the NULL-safe C<exist> method (or it's alias
C<contains>) can be used:
bool exists (const panda::string_view& key) const
bool contains (const panda::string_view& key) const
To delete arbitrary element by key the NULL-unsafe C<erase> method can be
used (the previous value, if existed, is returned; empty C<Scalar> is
returned otherwise).
Scalar erase (const panda::string_view& key)
=head2 clear()
void clear ()
Frees all items in the underlying C<HV*> array. This is NULL-safe method.
=head2 undef()
void undef()
Frees all items in the underlying C<HV*> hash; the hash container C<HV*>
itself remains alive. This is NULL-safe method.
=head2 push_on_stack()
U32 push_on_stack (SV** sp) const
This method copies all hash items into perl stack C<SV**>.
It returns the count of copied items. The method takes care of all needed
mechanis, e.g. C<sv_2mortal> and increasing refcounter of the items.
This is NULL-unsafe method.
=head2 size()
size_t size () const
Returns size of underlying hash, i.e. number of used keys. If it is NULL,
then C<0> is returned. In other words, this method is NULL-safe.
=head2 capacity()
size_t capacity () const
Returns capacity of underlying hash. If it is NULL, then C<0> is returned. In
other words, this method is NULL-safe.
=head2 reserve()
void reserve (size_t newsz)
Increases the capacity of the container. This is NULL-unsafe method.
=head2 itearators
C<Hash> provides iterator and const-iterator random-access accessors for it's content:
const_iterator cbegin () const
const_iterator cend () const
const_iterator begin () const
const_iterator end () const
iterator begin ()
iterator end ()
This methods are NULL-safe. As usually, when underlying array is modified, the
used iterators become invalid, and should not used any longer.
Usage example:
Hash hash = ...;
for (auto it = hash.begin(); it != hash.end(); ++it) {
panda::string_view key = it->key();
Scalar value = it->value();
U32 key_hash = it->hash();
}
=head1 SEE ALSO
L<XS::Framework>
L<XS::Framework::Manual::SVAPI>
L<XS::Framework::Manual::SVAPI::Sv>
L<XS::Framework::Manual::SVAPI::Stash>
=cut