Phobos Standard Library

Phobos 3 follows a 'split-level' design pattern to minimize memory allocations and exceptions, making the library more usable in performance-critical or @nogc contexts.

Split-Level Design Pattern

1. Low-level functions: These take in a user-provided buffer instead of allocating memory internally and return error codes instead of throwing exceptions.
2. High-level functions: These wrap the low-level functions, providing a simpler API by managing buffers and converting error codes into exceptions.

Key Principles

• Minimize Allocations: Library routines should avoid deciding allocation strategies for the user. For example, std.path returns ranges that allow users to emit results into their own chosen buffers.
• Minimize Exceptions: Exceptions are avoided where possible because they require the GC and prevent nothrow usage. The library prefers returning error codes or using Option/Sum types for error returns.

The Phobos 3 package map outlines a reorganized structure for the standard library. It categorizes modules into several top-level namespaces: core.*, etc.*, std.*, platform, based, phobos.sys, phobos.data, phobos.crypto, phobos.io, phobos.text, and phobos.net.

Key organizational changes include:

• based modules: These contain a mix of wrapped based functions, new functions, and public imports of based symbols. Many common utilities (like math, time, and traits) are being moved or reorganized here.
• phobos.sys: Contains low-level system-oriented modules such as algorithm, array, datetime, exception, random, and range.
• phobos.data: Focuses on data formats like base64, csv, json, toml, sdl, and zip.
• phobos.crypto: Provides cryptographic primitives including digest, hash, kdf, rsa, and symmetric algorithms.
• phobos.io, phobos.text, and phobos.net: Handle I/O, text processing (ASCII, UTF, encoding), and networking (HTTP, sockets, TLS, URI).

Note: This structure is proposed and not final. Modules marked with an asterisk () are new.*

core.*
etc.*
std.*
platform
  | freebsd
  | linux
  | macos
  | stdc
  | win
based
  | bigint
  | bitmanip
  | checkedint (core.checkedint)
  | complex
  | compiler
  | console (std.stdio)
  | demangle (core.demangle)
  | file
  | int128
  | math
    | algebraic
    | constants
    | exponential
    | hardware
    | operations
    | remainder
    | rounding
    | traits
    | trigonometry
    | special
    | numeric
  | meta
  | optional* (std.typecons)
  | stdint
  | sumtype
  | system
  | time (core.time)
  | traits
phobos.sys
  | algorithm
    | comparison
    | iteration
    | mutation
    | searching
    | setops
    | sorting
  | array
  | checkedint
  | conv
  | datetime
    | date
    | interval
    | stopwatch
    | systime
    | timezone
  | demangle
  | exception
  | functional
  | meta
  | outbuffer
  | process
  | random
  | range
  | signals
  | traits
  | uuid
  | variant
phobos.data
  | base64
  | csv
  | json*
  | toml*
  | sdl*
  | zip
phobos.crypto
  | digest
    | crc
    | murmurhash
  | ecc*
  | hash*
    | sha*
    | hmac*
  | kdf*
  | random*
  | rsa*
  | symmetric*
phobos.io
  | console (std.stdio)
  | stream* (iopipe)
  | mmfile
  | path
phobos.text
  | ascii
  | encoding
  | format
  | string
  | uni
  | utf
phobos.net
  | http*
  | socket
  | tls*
  | uri

To add a new entry to the pending changelog, create a new file in the changelog folder with a .dd extension. The file format should resemble a git commit message:

1. Title: The first line is the title of the change. It cannot contain links.
2. Description: After an empty line, provide a long description of the change.
3. Examples: You can include code examples using ------- as a separator.
4. Links: Use Ddoc syntax for internal and external links:
   • $(REF module, function) or $(REF_ALTTEXT alt_text, module, function) for internal references.
   • $(LINK2 path, text) for linking to local files (e.g., $(LINK2 $(ROOT_DIR)spec/module.html, this)).
   • $(LINK2 https://url.com, text) for external resources.

My fancy title of the new feature

A long description of the new feature in `std.range`.
It can be followed by an example:
-------
import std.range : padLeft, padRight;
import std.algorithm.comparison : equal;

assert([1, 2, 3, 4, 5].padLeft(0, 7).equal([0, 0, 1, 2, 3, 4, 5]));

assert("Hello World!".padRight('!', 15).equal("Hello World!!!!"));
-------
and links to the documentation, e.g. $(REF drop, std, range) or
$(REF_ALTTEXT a custom name for the function, drop, std, range).

Links to the spec can look like this $(LINK2 $(ROOT_DIR)spec/module.html, this) 
and of course you can link to other $(LINK2 https://forum.dlang.org/, external resources).