Foundation

Table of Contents

• Features
  • Classes
  • Macros
  • Type Traits
  • Utilities
• Status
• Description
  • Function
  • Deferred
  • OpaqueObject
  • UniqueHandle
• Blog
• Roadmap

🟩 Primitive types, asserts, limits, Function, Span, Result

Foundation library provides many fundamental type definitions and types widely used by other libraries.
As this is included and needed by almost every other library, it tries to keep bloat to the bare minimum.
Detailed documentation is in the Foundation topic.

Features

Classes

Class	Description
SC::Span	View over a contiguous sequence of items (pointer + size in elements).
SC::StringViewData	An read-only view over a string (to avoid including Strings library when parsing is not needed).
SC::Result	An ascii string used as boolean result. SC_TRY macro forwards errors to caller.
SC::Function	Wraps function pointers, member functions and lambdas without ever allocating.
SC::Deferred	Executes a function at end of current scope (in the spirit of Zig defer keyword).
SC::OpaqueObject	Hides implementation details from public headers (static PIMPL).
SC::UniqueHandle	Move only handle that has a special tag value flagging its invalid state.

Macros

• Compiler Macros:

Compiler Macros Preprocessor macros to detect compiler and platform features.

Type Traits

• Type Traits:

Type Traits (EnableIf, AddPointer, RemovePointer, etc.)

Utilities

Class	Description
SC::Assert	Functions and macros to assert, exit() or abort() and capture backtraces.
SC::AlignedStorage	A buffer of bytes with given alignment.
SC::MaxValue	An object that can be converted to any primitive type providing its max value.

Status

🟩 Usable
The library is very simple it it has what is needed so far by the other libraries.

Description

There is an hard rule in the library Principles not to include system and compiler headers in public headers.
Foundation provides all primitive types to be used in headers and classes like SC::UniqueHandle, SC::OpaqueObject, SC::AlignedStorage to encourage static PIMPL in order to hide platform specific implementation details everywhere.

Function

Wraps function pointers, member functions and lambdas without ever allocating.

Template Parameters

FuncType

Type of function to be wrapped (Lambda, free function or pointer to member function)

Note

Size of lambdas or less than LAMBDA_SIZE (currently 2 * sizeof(void*)).
If lambda is bigger than LAMBDA_SIZE the constructor will static assert.

Example:

// A regular class with a member function
struct SomeClass
{
    float memberValue = 2.0;
    int   memberFunc(float a) { return static_cast<int>(a + memberValue); }
};
 
// A Functor with operator ()
struct SomeFunctor
{
    float memberValue = 2.0;
    int   operator()(float a) { return static_cast<int>(a + memberValue); }
};
 
// Free function
int someFunc(float a) { return static_cast<int>(a * 2); }
 
// Class too big to be grabbed by copy
struct BigClass
{
    SC::uint64_t values[4];
};
 
void SC::FunctionTest::functionDocumentationSnippet()
{
    SomeClass someClass;
 
    Function<int(float)> func;
 
    func = &someFunc;                                                // Bind free func
    func.bind<SomeClass, &SomeClass::memberFunc>(someClass);         // Bind member func
    func = [](float a) -> int { return static_cast<int>(a + 1.5); }; // Bind lambda func
    func = SomeFunctor{2.5};                                         // Bind a functor
 
    // If you feel brave enough you can retrieve the bound functor by knowing its type
    SC_ASSERT_RELEASE(func.dynamicCastTo<SomeFunctor>()->memberValue == 2.5f);
 
    // This will static_assert because sizeof(BigClass) is bigger than LAMBDA_SIZE
    // BigClass bigClass;
    // func = [bigClass](float a) -> int { return static_cast<int>(a);};
}

Deferred

Executes a function at end of current scope (in the spirit of Zig defer keyword).

Template Parameters

F	The lambda / function to execute

Example:

HANDLE processHandle = OpenProcess(PROCESS_QUERY_INFORMATION |
                                    PROCESS_DUP_HANDLE, FALSE, processId);
if (processHandle == nullptr)
{
    return false;
}
auto deferDeleteProcessHandle = SC::MakeDeferred(
    [&] // Function (or lambda) that will be invoked at the end of scope
    {
        CloseHandle(processHandle);
        processHandle = nullptr;
    });
 
// Use processHandle that will be disposed at end of scope by the Deferred
 
// ...
// Deferred can be disarmed, meaning that the dispose function will not be executed
deferDeleteProcessHandle.disarm()

OpaqueObject

Hides implementation details from public headers (static PIMPL).

Opaque object avoids the heap allocation that often comes with PIMPL, allowing to hide OS specific details from public headers. User declares size in bytes of a struct in the header but the structure can be defined in an implementation .cpp file. Choosing a size that is too small will generate a static_assert that contains in the error message the minimum size to use. Up to 4 functions will need to be defined to avoid linker errors (construct, destruct, moveConstruct, moveAssign). These functions are meant to be defined in a .cpp file that will know how to construct Object, as it can see its definition.

Template Parameters

Definition

Pass in a custom Definition declaring Sizes and alignment on different platforms

Example:

 // ... in the header file
 struct TestObject
 {
    private:
    struct Internal;
 
    // Define maximum sizes and alignment in bytes of Internal object on each platform
    struct InternalDefinition
    {
        static constexpr int Windows = 224;
        static constexpr int Apple   = 144;
        static constexpr int Linux   = sizeof(void*);
        static constexpr int Default = Linux;
 
        static constexpr size_t Alignment = alignof(void*);
 
        using Object = Internal;
    };
 
  public:
    // Must be public to avoid GCC complaining
    using InternalOpaque = OpaqueObject<InternalDefinition>;
 
  private:
    InternalOpaque internal;
};
 
// ... In .cpp file
 
// Declare Internal struct with all platform specific details
struct SC::TestObject::Internal
{
    SC_NtSetInformationFile    pNtSetInformationFile = nullptr;
    LPFN_CONNECTEX             pConnectEx            = nullptr;
    LPFN_ACCEPTEX              pAcceptEx             = nullptr;
    LPFN_DISCONNECTEX          pDisconnectEx         = nullptr;
    // ... additional stuff
};
 
// Declare only two of the four functions to avoid linker errors.
template <>
void SC::TestObject::InternalOpaque::construct(Handle& buffer)
{
    placementNew(buffer.reinterpret_as<Object>());
}
template <>
void SC::TestObject::InternalOpaque::destruct(Object& obj)
{
    obj.~Object();
}

UniqueHandle

Move only handle that has a special tag value flagging its invalid state.

Typically used to wrap Operating System specific handles.

Template Parameters

Definition

A struct declaring handle type, release function and invalid handle value.

Example:

// ... definition in header
struct PosixFileDescriptorDefinition
{
    using Handle = int; // fd
    static Result releaseHandle(Handle& handle);
 
    static constexpr Handle Invalid = -1; // invalid fd
};
 
using PosixFileDescriptor = UniqueHandle<PosixFileDescriptorDefinition>;
 
// ...declaration in .cpp file
 
Result PosixFileDescriptorDefinition::releaseHandle(Handle& handle)
{
    if (::close(handle) != 0)
    {
        return Result::Error("releaseHandle - close failed");
    }
    return Result(true);
}
 
// ... usage
PosixFileDescriptor myDescriptor;
 
const int nativeFd = ::open(filePath.getNullTerminatedNative(), flags, access);
 
// Assign the native handle to UniqueHandle (will release the existing one, if any)
myDescriptor.assign(nativeFd);
 
// UniqueHandle can only be moved, but not copied
PosixFileDescriptor otherDescriptor = move(myDescriptor);
// PosixFileDescriptor otherDescriptor = myDescriptor; // <- Doesn't compile
 
// Explicitly close (or it will be automatically released on scope close / destructor)
otherDescriptor.close()
 
// If detach() is called, the handle will be made invalid without releasing it
otherDescriptor.detach()
 
// Check handle for validity
if(otherDescriptor.isValid())
{
    // ... do something
}

Blog

Some relevant blog posts are:

• January 2025 Update
• June 2025 Update

Roadmap

🟦 Complete Features:

• Things will be added as needed