🌎 δΈ­ζ–‡ | English

D2MySTL

Implement a mini STL library from scratch

d2x Online-ebook License

d2x Tool - Docs - Forum

Quick Start

1: d2x automatic code detection

Click to view the xlings installation command

Linux/MacOS

curl -fsSL https://d2learn.org/xlings-install.sh | bash

Windows - PowerShell

irm https://d2learn.org/xlings-install.ps1.txt | iex

tips: xlings -> details

Obtain the project

d2x install d2mystl

Enter practice mode

d2x checker

2: Hands-on Verification

Obtain the project

git clone https://github.com/mcpp-community/d2mystl.git

Run the test code manually

xmake run chapter0_tests

Note: The test name format is chapter[x]_tests

Pre-requisite Tutorials

If you find this tutorial a bit challenging to get started with, you can first learn the following tutorial to understand the basics and core syntax features of modern C++.

ProjectDescriptionNote
mcpp-startModern C++, Go! - import stdBeginner-0
d2mcppIntroduction to Modern C++ Core FeaturesBeginner-1

Other

🌎 δΈ­ζ–‡ | English

Tool installation and environment configuration

This chapter introduces how to install the d2x tool, create a template project, and set up the basic environment.

1. Install d2x tool

xlingsAn open-source package manager that can solve the problem of inconsistent dependencies across different environments

Click to view the installation command for xlings

Linux/MacOS

curl -fsSL https://d2learn.org/xlings-install.sh | bash

Windows - PowerShell

irm https://d2learn.org/xlings-install.ps1.txt | iex

tips: xlings -> details

xlings install d2x

2. Book and Code Inspection

Enter the root directory of the current project and run the command for testing.

View Document Command

After running the following command, the documentation/book of the new project will be opened in the browser

d2x book

Code auto-detection function

By running the checker command below, you can see that the console enters real-time code detection mode. As you modify the file code, the console will automatically update

d2x checker

🌎 δΈ­ζ–‡ | English

Chapter 0 --- Global Module and Meta Information

In this chapter, you will bootstrap the MySTL library by implementing its global module entry point and a meta information module. These components establish the foundation of a modular C++23 library and define the public interface that other modules and user code will rely on.

⚠️ Important: All tasks in this chapter must follow the specified interfaces exactly. Module names, exported symbols, and structure must not be altered. Any deviation may cause module linkage failures or test incompatibilities.

Directory Structure

Organize your files as follows:

mystl/
└── chapter0/
    β”œβ”€β”€ global.cppm
    └── metaInfo/
        └── metaInfo.cppm

1. Global Module

Objective

Implement the global module for MySTL.
This module serves as the primary entry point of the library and aggregates public-facing modules for convenient importing.

After implementation, users should be able to write:

import mySTL;

to access exported functionality.

Requirements

  • Create a C++23 module named: mySTL
  • Re-export the meta information module named: mySTL.metaInfo

Strict Constraints

Do not:

  • Add any additional code
  • Declare types, functions, or variables
  • Modify the module name
  • Change the export behavior
  • Include implementation details

The global module must remain minimal and act purely as a module aggregator.

Example Usage

import mySTL;
import mySTL.metaInfo;

// Meta information is now accessible.

2. Meta Information Module

Objective

Implement the meta information module that describes the library.
Providing structured metadata is a common practice in production-grade libraries and helps users quickly identify the library version and purpose.

Requirements

Create a module named:

mySTL.metaInfo

Follow the reference interface precisely and provide the following metadata.

Library Name

Accessible via:

mySTL::metaInfo::name

Expected value:

MySTL

Version Information

Accessible via:

mySTL::metaInfo::version.major
mySTL::metaInfo::version.minor
mySTL::metaInfo::version.patch

Expected version:

0.1.0

Description

Accessible via:

mySTL::metaInfo::description

Expected value:

My Standard Template Library

Strict Constraints

  • All names, types, and values must match the reference implementation exactly.
  • Do not introduce extra symbols.
  • Do not modify the interface.
  • Avoid unrelated code.

Failure to comply may result in:

  • ABI incompatibility\
  • Linker errors\
  • Automated test failures

Example Usage

import mySTL.metaInfo;
#include <iostream>

int main() {
    std::cout << mySTL::metaInfo::name << "\n";

    std::cout << mySTL::metaInfo::version.major << "."
              << mySTL::metaInfo::version.minor << "."
              << mySTL::metaInfo::version.patch << "\n";

    std::cout << mySTL::metaInfo::description << "\n";

    return 0;
}

Expected Output

MySTL
0.1.0
My Standard Template Library

Run Unit Tests

You can run unit tests on your code using the following command:
xmake f -m release
xmake run chapter0_tests
You can also run unit tests on the reference code to compare it with your implementation:
xmake f -m debug
xmake run chapter0_tests

🌎 δΈ­ζ–‡ | English

Chapter 1 --- Array Module Implementation

In this chapter, you will implement the foundational MySTL.array module, which provides a simplified version of std::array with basic functionality. This module introduces the design patterns and organization used throughout MySTL.

⚠️ Important: All tasks in this chapter must follow the specified interfaces exactly. Module names, exported symbols, and structure must not be altered. Any deviation may cause module linkage failures or test incompatibilities.

Directory Structure

Add the files as follows:

mystl/
└── chapter1/
    └── array/
        └── array.cppm

1. Global Module

Objective

Update the global module to export the new array module alongside the existing meta information module. After implementation, users should be able to write:

import mySTL.array;

to access both meta information and array functionality.

Requirements

Update the existing C++23 module: mySTL

  • Re-export: mySTL.array

Strict Constraints

Do not:

  • Add any additional code
  • Declare types, functions, or variables
  • Modify the module name
  • Change the export behavior
  • Include implementation details

The global module must remain minimal and act purely as a module aggregator.

Example Usage

import mySTL.array;
// Array are now accessible

2. Array Module Implementation

Objective

Implement the array module that provides a simplified fixed-size container similar to std::array.

Requirements

Create a module named:

mySTL.array

Follow the reference interface precisely and provide the following functionality.

API Behavior Requirements

Element Access Methods

operator[](std::size_t index)

  • Returns: Reference to the element at position index
  • No bounds checking: Must not perform any range validation
  • Exception safety: Must not throw exceptions (marked noexcept)
  • Const correctness: Both const and non-const versions required

at(std::size_t index)

  • Returns: Reference to the element at position index
  • Bounds checking: Must validate that index < size()
  • Exception: Must throw std::out_of_range if index >= size()
  • Exception message: Should be "Index out of range"
  • Const correctness: Both const and non-const versions required

Capacity Methods

size()

  • Returns: The template parameter N value
    • For Array<T, 0>: Must return 0
  • Exception safety: Must not throw exceptions (marked noexcept)

capacity()

  • Returns: The actual storage capacity
    • For N > 0: Must return N
    • For N == 0: Must return 1 (to maintain valid storage)
  • Exception safety: Must not throw exceptions (marked noexcept)

empty()

  • Returns: true if size() == 0, otherwise false
    • For Array<T, 0>: Must return true
  • Exception safety: Must not throw exceptions (marked noexcept)

Implementation Notes

  • Storage: The array must use a fixed-size C-style array for storage
  • Zero-size handling: Special handling required for N == 0 case
  • Value initialization: All elements should be value-initialized
  • constexpr support: All methods should be marked constexpr where appropriate
  • Exception safety: Methods should provide basic exception safety guarantees

Strict Constraints

  • All names, types, and values must match the reference implementation exactly.
  • Do not introduce extra symbols.
  • Do not modify the interface.
  • Avoid unrelated code.

Failure to comply may result in:

  • ABI incompatibility\
  • Linker errors\
  • Automated test failures

Example Usage

import mySTL.array;
#include <iostream>

int main() {
    // Basic array usage
    mySTL::Array<int, 5> arr;
    arr[0] = 42;
    arr[1] = 13;
    
    std::cout << "Size: " << arr.size() << "\n";
    std::cout << "Capacity: " << arr.capacity() << "\n";
    std::cout << "Empty: " << std::boolalpha << arr.empty() << "\n";
    
    // Bounds-checked access
    try {
        std::cout << "Element at index 0: " << arr.at(0) << "\n";
        std::cout << "Element at index 10: " << arr.at(10) << "\n"; // Throws
    } catch (const std::out_of_range& e) {
        std::cout << "Caught exception: " << e.what() << "\n";
    }
    
    // Zero-sized array
    mySTL::Array<double, 0> emptyArr;
    std::cout << "Zero-sized array size: " << emptyArr.size() << "\n";
    std::cout << "Zero-sized array capacity: " << emptyArr.capacity() << "\n";
    std::cout << "Zero-sized array empty: " << emptyArr.empty() << "\n";
    
    return 0;
}

Expected Output

Size: 5
Capacity: 5
Empty: false
Element at index 0: 42
Caught exception: Index out of range
Zero-sized array size: 0
Zero-sized array capacity: 1
Zero-sized array empty: true

Run Unit Tests

You can run unit tests on your code using the following command:
xmake f -m release
xmake run chapter1_tests
You can also run unit tests on the reference code to compare it with your implementation:
xmake f -m debug
xmake run chapter1_tests