=head1 Heap allocation

Within Ermyth, most larger structures are allocated by a custom
L<block allocator|balloc.html> but sometimes, you don't want that. This is
the case for char arrays for instance. The block allocator doesn't work
for char arrays and it makes little sense to use it for that. Just using
the bare system malloc is error prone as you have to take care of segment
sizes and things like that. C++ provides templates, so why not use them?

=head2 Allocation functions

Ermyth provides several allocation functions with different semantics. All
allocation routines may throw std::bad_alloc. The deallocation routine sfree
does not throw any exceptions.

=over

=item template<typename T> T *alloc (int n = 1)

Example: C<< char *str = alloc<char> (20) >> allocates a char array of size
20 * sizeof (char).

=item template<typename T> T *alloc (unsigned n, T *src)

Example: C<< char *newstr = alloc (strlen (str), str) >> basically emulates
strdup ().

=item template<typename T> T *alloc (unsigned n, T *src, size_t len)

Safe and slow version of above: never tries to copy more than len from src.

=item template<typename T> T *alloc (unsigned n, char c)

Example: C<< char *newstr = alloc<char> (20, 0) >> allocates a char array of
size 20 * sizeof (char) and initialises that memory to zero.

=item template<typename T> void sfree (T *ptr)

Frees memory used by ptr. Works just like free ().

=back

Furthermore, Ermyth provides two convenience functions that use the above
memory functions and therefore require the use of sfree ().

=over

=item char *sstrdup (char const * const s)

Returns a duplicate of the passed string. Emulates standard C strdup.

=item char *sstrndup (char const * const s, int len)

The same as strndup but with the above memory functions.

=item template<size_t N> char *sstrndup (char const (&s)[N])

Takes away the need of counting characters if you want to duplicate
a string literal.

=back


=head2 Other allocators

Ermyth provides other allocators aside from the L<block allocator|balloc.html>.
One of these is the C<zero_initialised> allocator. It is used just like the
block allocator.

   struct mystruct : zero_initialised
   {
     char mystring[30];
   };

Makes sure that all objects instantiated from this class are initialised to
zero. B<Important>: Do not combine allocators.