<commit_before>/*
 * Copyright(c) Sophist Solutions, Inc. 1990-2018.  All rights reserved
 */
#ifndef _Stroika_Foundation_Memory_SmallStackBuffer_h_
#define _Stroika_Foundation_Memory_SmallStackBuffer_h_ 1

#include "../StroikaPreComp.h"

#include "../Configuration/Common.h"
#include "../Configuration/Concepts.h"
#include "../Configuration/TypeHints.h"

#include "Common.h"

/**
 *  \file
 *
 *  \version    <a href="Code-Status.md#Beta">Beta</a>
 */

namespace Stroika::Foundation::Memory {

    /**
     */
    class SmallStackBufferCommon {
    public:
        enum UninitializedConstructorFlag { eUninitialized };
    };

    /**
     *  SmallStackBuffer<> combines the performance of using a stack buffer to store arrays with
     *  the safety and flexability of using the free store (malloc).
     *
     *  Think of it as a hybrid between std::vector<> and std::array - with functionality like
     *  std::vector, but performance more like std::array.
     *
     *  In steps <code>SmallStackBuffer&ltT&gt</code>. Just declare one of these, and it
     *  automaticlly uses the stack for the buffer if it will fit, and silently allocates heap memory
     *  and returns it to the free store on stack based destruction if needed. Use it just like you
     *  would a stack-based array. You don't need to know about this to use any of Led's APIs, but its
     *  a helpful class you may want to use elsewhere in your code.</p>
     *
     *  typically sizeof(SmallStackBuffer<T,BUF_SIZE>) will come to roughly 4K, and always at least something.
     *
     *  \par Example Usage
     *      @see Samples/SimpleService project
     *      \code
     *          Memory::SmallStackBuffer<Byte> useKey{keyLen};  // no need to default initialize cuz done automatically
     *          (void)::memcpy (useKey.begin (), key.begin (), min (keyLen, key.size ()));
     *      \endcode
     * OR
     *      \code
     *          Memory::SmallStackBuffer<Byte> useKey{Memory::SmallStackBuffer::eUninitiialized, keyLen};
     *          (void)::memset (useKey.begin (), 0, keyLen);
     *          (void)::memcpy (useKey.begin (), key.begin (), min (keyLen, key.size ()));
     *      \endcode
     *
     *  \note   \em Thread-Safety   <a href="thread_safety.html#C++-Standard-Thread-Safety">C++-Standard-Thread-Safety</a>
     *
     *  \note   SmallStackBuffer<T> can roughly be used as a replacement for vector<> - behiing similarly, except that its optimized
     *          for the case where its used as an automatic variable with a template specifying the right size on the stack for the buffer.
     *<commit_msg>docs todo<commit_after>/*
 * Copyright(c) Sophist Solutions, Inc. 1990-2018.  All rights reserved
 */
#ifndef _Stroika_Foundation_Memory_SmallStackBuffer_h_
#define _Stroika_Foundation_Memory_SmallStackBuffer_h_ 1

#include "../StroikaPreComp.h"

#include "../Configuration/Common.h"
#include "../Configuration/Concepts.h"
#include "../Configuration/TypeHints.h"

#include "Common.h"

/**
 *  \file
 *
 *  \version    <a href="Code-Status.md#Beta">Beta</a>
 */

namespace Stroika::Foundation::Memory {

    /**
     */
    class SmallStackBufferCommon {
    public:
        enum UninitializedConstructorFlag { eUninitialized };
    };

    /**
     *  SmallStackBuffer<> combines the performance of using a stack buffer to store arrays with
     *  the safety and flexability of using the free store (malloc).
     *
     *  Think of it as a hybrid between std::vector<> and std::array - with functionality like
     *  std::vector, but performance more like std::array.
     *
     *  In steps <code>SmallStackBuffer&ltT&gt</code>. Just declare one of these, and it
     *  automaticlly uses the stack for the buffer if it will fit, and silently allocates heap memory
     *  and returns it to the free store on stack based destruction if needed. Use it just like you
     *  would a stack-based array. You don't need to know about this to use any of Led's APIs, but its
     *  a helpful class you may want to use elsewhere in your code.</p>
     *
     *  typically sizeof(SmallStackBuffer<T,BUF_SIZE>) will come to roughly 4K, and always at least something.
     *
     *  \par Example Usage
     *      @see Samples/SimpleService project
     *      \code
     *          Memory::SmallStackBuffer<Byte> useKey{keyLen};  // no need to default initialize cuz done automatically
     *          (void)::memcpy (useKey.begin (), key.begin (), min (keyLen, key.size ()));
     *      \endcode
     * OR
     *      \code
     *          Memory::SmallStackBuffer<Byte> useKey{Memory::SmallStackBuffer::eUninitiialized, keyLen};
     *          (void)::memset (useKey.begin (), 0, keyLen);
     *          (void)::memcpy (useKey.begin (), key.begin (), min (keyLen, key.size ()));
     *      \endcode
     *
     *  \note   @todo - CONSIDER RENAME to InlineStorage or InlineBuffer
     *
     *  \note   \em Thread-Safety   <a href="thread_safety.html#C++-Standard-Thread-Safety">C++-Standard-Thread-Safety</a>
     *
     *  \note   SmallStackBuffer<T> can roughly be used as a replacement for vector<> - behiing similarly, except that its optimized
     *          for the case where its used as an automatic variable with a template specifying the right size on the stack for the buffer.
     *
{'fraction_non_alphanumeric': 0.10703536493604214, 'fraction_numerical': 0.004138449962377728, 'mean_word_length': 2.7655807365439093, 'pattern_counts': {'":': 0, '<': 31, '<?xml version=': 0, '>': 31, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4151783', 'n_tokens_mistral': 1593, 'n_tokens_neox': 1538, 'n_words': 509}