Chapter 56 Namespaces, Types, and Include Paths

Exactly 1,032 public headers are reachable below two roots; five further .hpp files are private implementation headers below module src/ trees. System/ contains the literal .NET namespace tree; SharpRuntime/ contains project-specific aliases and source-porting helpers. There is no catch-all header. Private headers below a module’s src/ directory are not added to consumer include paths.

The transliteration rule is mechanical:

One public type per like-named header is the norm. The rule makes a port review tractable: an include that cannot be derived from the type name deserves inspection, and an accidental include from another module’s private tree cannot be hidden behind a universal umbrella.

The C++ namespace hierarchy describes API identity; the 44 CMake components describe build ownership. Several namespace families split across components to keep link surfaces narrow. Table 56.1 gives representative mappings used by CNA.

The direct component is not the full closure. Its public dependencies carry lower-level requirements, just as a C++ header’s own includes do. This is why CNA names SharpRuntime::IO rather than copying IO’s current dependency list into its own CMake files. Chapter 54 covers the adapter and its legacy monolith fallback.

CNA directly names 54 distinct runtime headers. Fifty-two use the System/ root. The two SharpRuntime/ spellings are SharpRuntimeHelper.hpp, which defines the C#-fidelity primitives and limits, and Prop.hpp, which exports property-declaration macros for downstream code. Counting only the latter prefix and concluding that CNA consumes two runtime headers mistakes a namespace prefix for a repository boundary.

SharpRuntimeHelper.hpp is unusually load-bearing: hundreds of public runtime headers include it, and CNA uses aliases such as intcs, bytecs, and Single throughout its public surface. It also exports two unnamespaced macros, CONTAINS and INTERNAL; consumers must treat those as global preprocessor names, not members protected by the SharpRuntime namespace.

Prop.hpp is the opposite kind of seam. The runtime’s own property methods are hand-written, and its modules do not include this macro header. CNA does. The file is therefore an exported downstream facility even though a search limited to the library’s implementation would misleadingly classify it as unused.

System::String is deliberately not a wrapper class at all — its default constructor and destructor are both explicitly deleted, making it a pure static-method utility operating on ordinary std::string values (IsNullOrEmpty, Compare, the IndexOf / LastIndexOf family, Split, Substring, Trim*, PadLeft / PadRight). Text::StringBuilder, by contrast, is a real, stateful, mutable buffer type — the many-overloaded Append (string, char, int, double, float, bool, and the longcs alias from Chapter 3), AppendLine, Insert, Remove, Replace, and a nested ChunkEnumerator class mirroring real .NET’s own chunked-buffer enumeration shape — real .NET’s own StringBuilder is internally a linked list of separate character chunks, and ChunkEnumerator walks that list without copying; this port’s StringBuilder is backed by a single std::string instead, so its own ChunkEnumerator always yields exactly one chunk holding the entire current buffer — the enumeration shape is preserved faithfully even though the simpler single-buffer implementation underneath never actually produces more than one chunk to walk.

IO::Stream’s own class comment states its scope plainly: “lightweight subset of the .NET Stream API.” Read(buffer, offset, count), Close(), and getLengthProperty() are pure virtual; Write / WriteByte default to throwing NotSupportedException unless a writable stream subclass overrides them — the same shape real .NET’s own read-only stream implementations follow, rather than forcing every stream subclass to implement a full read/write/seek contract regardless of whether it actually supports all three. getCanWriteProperty() defaults to false and getCanReadProperty() defaults to true, matching a read-only stream’s honest self-report without requiring every subclass to override both just to state the obvious.

Text::UTF8Encoding’s own class comment states a real, specific guarantee that is easy to assume any UTF-8 encoder provides and that this port genuinely earns rather than skips: GetBytes() / GetString() validate that input is well-formed UTF-8 — not merely pass bytes through as opaque char values — and route any ill-formed byte at each invalid position through the configured fallback before resuming. Reading UTF8Encoding.cpp’s own local wellFormedUtf8Length() helper directly shows this is real conformance checking, not a length-only byte count: a leading byte is walked against the real UTF-8 grammar (1/2/3/4-byte forms, each continuation byte checked for the 10xxxxxx pattern), and even a structurally well-formed sequence is rejected if the code point it decodes to is an overlong encoding (a multi-byte sequence encoding a code point that a shorter form could already represent — a real, historically security-relevant UTF-8 attack shape, since a naive decoder that accepts overlong encodings lets an attacker smuggle a byte value like 0x2F (’/’) past a filter checking only the raw byte stream) or a UTF-16 surrogate code point (U+D800–U+DFFF, which UTF-8 must never directly encode, since surrogates exist only as a UTF-16 encoding artifact).

The constructor also earns a real, specific correction over the naive default: real .NET’s own UTF8Encoding.SetDefaultFallbacks() substitutes the Unicode replacement character U+FFFD for invalid input, not the generic Encoding base class’s plain "?" default (correct only for single-byte code pages, where every valid character already has an unambiguous byte representation to fall back to). This port’s constructor reproduces that distinction precisely:

A worked example makes the whole mechanism concrete — three real byte sequences, one well-formed and two deliberately malformed in different ways, through the same GetString() call:

The overlong and lone-continuation cases each substitute one U+FFFD per invalid byte, not per attempted sequence — overlongSlash’s two bytes both fail validation independently (the loop advances one byte at a time through the fallback path, per UTF8Encoding.cpp’s own ++i in the non-well-formed branch), so a 2-byte overlong sequence becomes two replacement characters, not one. This matches real .NET’s own observable behavior for the identical input, confirmed by working through the .NET runtime’s own documented per-byte fallback-and-resynchronize algorithm for UTF-8 decoding rather than assumed by analogy.

This behavior now has direct regression evidence. UTF8EncodingTests covers malformed continuations, overlong input, truncated sequences, directly encoded surrogates and exception fallbacks, including the one-replacement-per-byte resynchronization used above. The separate Utf8Tests family validates overlong sequences, surrogates, code points above U+10FFFF, truncation and lone continuation bytes through the span-oriented validator. The source read explains the algorithm; these two distinct test surfaces pin both the encoding facade’s observable substitutions and the lower-level validity classification.

Both non-generic Task and generic-result TaskT<TResult> have real ContinueWith implementations. Their shared-state shapes each contain a mutex, condition variable, and callback list; registered callbacks execute inline on the thread that completes the antecedent, or synchronously on the caller when it is already complete. TaskT<TResult> provides both an action overload returning Task and a result-producing overload returning TaskT<TNewResult>. The tests cover success, fault, cancellation inspection, filtered options, result chaining, empty callables, and release of captured state. Both implementations capture the antecedent state weakly to avoid a cycle from that state’s own continuation list back to itself.

The narrower missing surface is aggregation over generic tasks. Static WhenAll and WhenAny accept only std::vector<Task>; there is no corresponding overload for std::vector<TaskT<TResult>> that produces a result array or a winning generic task. Thus callers can attach a continuation to one generic result, but cannot express .NET’s generic multi-task combinators through this API. A second minor boundary is that the lightweight antecedent reconstructed for a callback shares terminal status/result/exception state but not the original separately-held cancellation-token object, so its token property reports None.

A reliable dependency review uses three layers in order. First derive the public include from the type’s fully-qualified name. Then locate the module whose public include directory owns the file. Finally inspect that component’s declared public dependencies rather than inferring a closure from nested namespaces. Namespace depth, directory depth, and link depth often align, but the component registry — particularly compatibility umbrellas and the Xml.XPath alias — is the authority when they do not.

The representative types in this chapter also show why include availability is weaker than semantic parity. UTF8Encoding’s malformed-input behavior is implemented and directly tested; TaskT<TResult> has generic continuations but not generic multi-task combinators. A mechanically correct path proves that a type can be named. It does not prove that every .NET behavior behind that name exists.