donner Namespace Reference

Top-level Donner namespace, which is split into different sub-namespaces such as donner::svg and donner::css. More...

Namespaces
namespace	parser
	Parsers for shared data types such as NumberParser and LengthParser.
namespace	css
	Donner CSS library, a standalone composable CSS parser.
namespace	svg
	Donner SVG library, which can load, manipulate and render SVG files.
namespace	xml
	XML parsing and document model support, top-level objects are donner::xml::XMLParser and donner::xml::XMLDocument.

Classes
struct	Box
	A 2D axis-aligned bounding box. More...
class	ChunkedString
	ChunkedString is a small helper to accumulate multiple RcStringOrRef pieces, either as small appended fragments or single codepoints. More...
struct	CompileTimeMapTables
	Perfect-hash metadata used to resolve keys into storage slots. More...
struct	CompileTimeMapDiagnostics
	Diagnostics describing how a CompileTimeMap was constructed. More...
class	CompileTimeMap
	Compile-time associative container backed by a perfect hash layout. More...
class	ElementTraversalGenerator
	Selectors may need to traverse the tree in different ways to match, and this is abstracted away using C++20 coroutines. More...
class	FakeElement
	A test fake for a type that satisfies the ElementLike concept. More...
class	Decompress
	A utility class for decompressing data. More...
struct	FileOffset
	Error context for a failed parse, such as the error reason, line, and character offset. More...
struct	FileOffsetRange
	Holds a selection range for a region in the source text. More...
struct	Length
	Parses a CSS <length-percentage> type as defined by https://www.w3.org/TR/css-values-3/#typedef-length-percentage. More...
struct	MathConstants
	Contains a set of math constants for the specified type (float or double). More...
struct	MathConstants< float >
	Math constants for float. More...
struct	MathConstants< double >
	Math constants for double. More...
struct	QuadraticSolution
	Holds the solution of a quadratic equation, as returned by SolveQuadratic. More...
class	OptionalRef
	A class that simulates an optional reference to a constant object of type T. More...
struct	ParseError
	Error context for a failed parse, such as the error reason, line, and character offset. More...
class	ParseResult
	A parser result, which may contain a result of type T, or an error, or both. More...
class	RcString
	A reference counted string, that is copy-on-write and implements the small-string optimization. More...
class	RcStringOrRef
	An in-transit type that can hold either an RcString or std::string_view, to enable transferring the RcString reference or also accepting a non-owning std::string_view from API surfaces. More...
struct	FontMetrics
	A container for font information relevant for computing font-relative lengths, per https://www.w3.org/TR/css-values/#font-relative-lengths. More...
struct	AbsoluteLengthMetrics
	A container with ratios for converting absolute lengths, such as "cm" or "in", see https://www.w3.org/TR/css-values/#absolute-lengths. More...
class	SmallVector
	A vector with small-size optimization. More...
struct	CaseInsensitiveCharTraits
	Type traits for case-insensitive string comparison, usable with algorithms that accept an STL std::char_traits. More...
class	StringUtils
	A collection of string utils, such as case-insensitive comparison and StartsWith/EndsWith. More...
class	Runfiles
	Helper class to access bazel runfiles in a test environment. More...
struct	Transform
	A 2D matrix representing an affine transformation. More...
class	Utf8
	Utility class for working with UTF-8 encoded strings. More...
struct	Vector2
	A 2D vector, (x, y). More...

Concepts
concept	ElementLike
	Concept for types that can be matched against a selector, such as a donner::svg::SVGElement.
concept	StringLike
	A concept for types that are string-like, i.e.

Typedefs
using	Boxd = Box<double>
	Shorthand for Box<double>.
using	Entity = entt::entity
	Entity type for the Registry, a std::uint32_t alias.
using	Registry = entt::basic_registry<Entity, std::allocator<Entity>>
	Registry type for the SVG ECS, which is the entry point for storing all data.
using	EntityHandle = entt::basic_handle<Registry>
	Convenience handle for a Entity with an attached Registry.
using	Lengthd = Length<double>
	Shorthand for Length<double>.
Typedefs
using	Transformf = Transform<float>
	Shorthand for Transform<float>.
using	Transformd = Transform<double>
	Shorthand for Transform<double>.
using	Vector2f = Vector2<float>
	Shorthand for Vector2<float>.
using	Vector2d = Vector2<double>
	Shorthand for Vector2<double>.
using	Vector2i = Vector2<int>
	Shorthand for Vector2<int>.

Enumerations
enum class	CompileTimeMapStatus {   kOk ,   kUsingFallbackHash ,   kDuplicateKey ,   kSeedSearchFailed ,   kConstexprHashUnsupported }
	Indicates the result of building a CompileTimeMap. More...
enum class	LengthUnit : uint8_t {   None ,   Percent ,   Cm ,   Mm ,   Q ,   In ,   Pc ,   Pt ,   Px ,   Em ,   Ex ,   Ch ,   Rem ,   Vw ,   Vh ,   Vmin ,   Vmax }
	The unit identifier for a length, corresponding to CSS unit identifiers. More...
enum class	StringComparison : uint8_t {   Default ,   IgnoreCase }
	String comparison options, e.g. case sensitivity. More...

Functions
constexpr std::size_t	mixHash (std::size_t baseHash, std::uint32_t seed)
template<typename Key>
constexpr bool	supportsConstexprHash ()
template<typename Key>
constexpr std::size_t	constexprHashValue (const Key &key)
template<typename Key, std::size_t N, typename KeyEqual>
constexpr bool	hasDuplicateKeys (const std::array< Key, N > &keys, KeyEqual keyEqual)
	Returns true when the provided keys contain duplicates.
auto	operator<=> (Entity lhs, Entity rhs)
	Compare two Entity values.
template<ElementLike T>
ElementTraversalGenerator< T >	singleElementGenerator (T element)
	A generator that yields a single element, if it exists.
template<ElementLike T>
ElementTraversalGenerator< T >	parentsGenerator (T element)
	A generator that yields all parents of an element, repeatedly following parentElement() until reaching the root.
template<ElementLike T>
ElementTraversalGenerator< T >	previousSiblingsGenerator (T element)
	A generator that yields all siblings of an element, in reverse order.
template<ElementLike T>
ElementTraversalGenerator< T >	allChildrenRecursiveGenerator (T element)
	A generator that yields all children of an element recursively with pre-order traversal.
ParseResult< std::vector< uint8_t > >	DecodeBase64Data (std::string_view base64String)
	Decode a base64-encoded string into a byte array.
std::string	EncodeBase64Data (std::span< const uint8_t > data)
	Encode a byte array into a base64-encoded string.
int	LLVMFuzzerTestOneInput (const uint8_t *data, size_t size)
	Fuzzer entry point, see https://llvm.org/docs/LibFuzzer.html.
std::vector< uint8_t >	UrlDecode (std::string_view urlEncodedString)
	Decode a URL-encoded string into a byte array, translating XX sequences into the corresponding byte value.
std::ostream &	operator<< (std::ostream &os, LengthUnit unit)
	OStream output operator, writes the CSS unit identifier to the stream, e.g. % or px.
float	NarrowToFloat (double from)
	Semantically represent a narrowing conversion, such as converting a double to a float, to make the conversion more visible.
template<typename T>
const T &	Min (const T &a, const T &b)
	Returns minimum of the provided values.
template<typename T, typename... Args>
const T &	Min (const T &a, const T &b, Args &&... args)
	Returns minimum of the provided values.
template<typename T>
const T &	Max (const T &a, const T &b)
	Returns maximum of the provided values.
template<typename T, typename... Args>
const T &	Max (const T &a, const T &b, Args &&... args)
	Returns maximum of the provided values.
float	Abs (float a)
	Returns the absolute value of the number.
double	Abs (double a)
	Returns the absolute value of the number.
template<typename T, typename = std::enable_if<std::is_integral<T>::value && std::is_signed<T>::value>>
T	Abs (T a)
	Returns the absolute value of the number.
template<typename T, typename = std::enable_if<std::is_floating_point<T>::value>>
T	Round (T orig)
	Round a floating point value to an integer.
template<typename T>
T	Lerp (T a, T b, const float t)
	Returns linear interpolation of a and b with ratio t.
template<typename T>
const T	Clamp (T value, T low, T high)
	Clamps a value between low and high.
template<typename T>
bool	NearEquals (T a, T b, T tolerance=std::numeric_limits< T >::epsilon())
	Returns if a equals b, taking possible rounding errors into account.
template<typename T>
bool	NearZero (T a, T tolerance=std::numeric_limits< T >::epsilon())
	Returns if a equals zero, taking rounding errors into account.
template<typename T, typename = std::enable_if<std::is_integral<T>::value>>
bool	InRange (T var, T start, T end)
	Test if a variable is in a specific range, using an optimized technique that requires only one branch.
template<typename T>
QuadraticSolution< T >	SolveQuadratic (T a, T b, T c)
	Solve a quadratic equation.
std::ostream &	operator<< (std::ostream &os, const ParseError &error)
	Ostream output operator for ParseError, outputs the error message.
	MATCHER_P (ToStringIs, expected, "")
	Matches the string representation of an object, by calling testing::PrintToString and comparing the results with the expected value.
	MATCHER_P2 (Vector2Eq, xMatcher, yMatcher, "")
	Matches a Vector.
	MATCHER_P2 (Vector2Near, xValue, yValue, "")
	Matches a Vector2 with DoubleNear(0.01).
	MATCHER_P (NormalizedEq, expectedVector, "")
	Matches if two vectors are equal when both are normalized, within an error of 0.01.
	MATCHER_P (TransformEq, other, "transform eq "+testing::PrintToString(other))
	Matches a transform with near-equals comparison.
	MATCHER_P6 (TransformIs, d0, d1, d2, d3, d4, d5, "")
	Matches a transform per-element, with a near-equals comparison using a threshold of 0.0001.
	MATCHER (TransformIsIdentity, "")
	Matches if a transform is identity.
	MATCHER_P2 (BoxEq, topLeftMatcher, bottomRightMatcher, "")
	Matches a Box.
	MATCHER_P2 (LengthIs, valueMatcher, unitMatcher, "")
	Matches a Length.
template<typename T>
void	PrintTo (const ParseResult< T > &result, std::ostream *os)
	Outputs a ParseResult to a stream for debugging purposes.
	MATCHER (NoParseError, "")
	Matches if the result does not contain a ParseError.
	MATCHER_P (ParseErrorIs, errorMessageMatcher, std::string("parse error is (")+testing::PrintToString(errorMessageMatcher)+")")
	Given a ParseResult, matches if it contains an error whose reason matches the given errorMessageMatcher (string or matcher).
	MATCHER_P2 (ParseErrorPos, lineMatcher, offsetMatcher, "")
	Given a ParseResult, matches if it contains an error at the given offset.
	MATCHER (ParseErrorEndOfString, "")
	Matches if a ParseResult contains an error at the end of the string.
	MATCHER_P (ParseResultIs, resultMatcher, "")
	Matches if a ParseResult contains a result that matches the given value, and that it does not contain an error.
	MATCHER_P2 (ParseResultAndError, resultMatcher, errorMessageMatcher, "")
	Matches if a ParseResult contains a result that matches the given value, and that it does not contain an error.

Detailed Description

Top-level Donner namespace, which is split into different sub-namespaces such as donner::svg and donner::css.

---

Class Documentation

donner::CompileTimeMapTables

struct donner::CompileTimeMapTables

template<std::size_t N>
struct donner::CompileTimeMapTables< N >

Perfect-hash metadata used to resolve keys into storage slots.

Collaboration diagram for donner::CompileTimeMapTables< N >:

Class Members
uint32_t	bucketCount = 0	Number of buckets used by the first-level table; zero enables fallback lookup.
array< uint32_t, N >	primary {}	First-level table storing direct indices or bucket seeds.
array< uint32_t, N >	secondary {}	Secondary slot table addressed with the bucket seed and key hash.

donner::CompileTimeMapDiagnostics

struct donner::CompileTimeMapDiagnostics

Diagnostics describing how a CompileTimeMap was constructed.

Class Members
bool	constexprHashSupported = true	Whether constexpr hashing was available for the provided key type.
uint32_t	failedBucket = kEmptySlot	Index of the bucket that failed to place, or kEmptySlot when successful.
uint32_t	maxBucketSize = 0	Largest bucket size observed while building the table.
uint32_t	seedAttempts = 0	Total seed attempts across all buckets.

donner::FileOffsetRange

struct donner::FileOffsetRange

Holds a selection range for a region in the source text.

Collaboration diagram for donner::FileOffsetRange:

Class Members
FileOffset	end	End offset.
FileOffset	start	Start offset.

donner::MathConstants

struct donner::MathConstants

template<typename T>
struct donner::MathConstants< T >

Contains a set of math constants for the specified type (float or double).

Template Parameters

T

donner::QuadraticSolution

struct donner::QuadraticSolution

template<typename T>
struct donner::QuadraticSolution< T >

Holds the solution of a quadratic equation, as returned by SolveQuadratic.

Template Parameters

T

Collaboration diagram for donner::QuadraticSolution< T >:

Class Members
bool	hasSolution = false	True if the equation has solutions.
array< T, 2 >	solution	Solutions to the equation, valid if hasSolution is true.

Typedef Documentation

Entity

using donner::Entity = entt::entity

Entity type for the Registry, a std::uint32_t alias.

This is a core type for the the ECS, and is used to identify entities in the Registry.

See also

Entity Component System (ECS)

Registry

EntityHandle

using donner::EntityHandle = entt::basic_handle<Registry>

Convenience handle for a Entity with an attached Registry.

Allows calling functions typically on Registry without having to pass around two values.

Registry

using donner::Registry = entt::basic_registry<Entity, std::allocator<Entity>>

Registry type for the SVG ECS, which is the entry point for storing all data.

It is used to create new entities:

Registry registry;
const Entity entity = registry.create();

Attach or remove data classes to entities:

registry.emplace<components::TreeComponent>(entity, "unknown");
registry.remove<components::TreeComponent>(entity);

Store global objects (singleton-like):

registry.ctx().emplace<components::RenderingContext>(registry));
const Entity root = registry.ctx().get<components::RenderingContext>().rootEntity;

See also

Entity Component System (ECS)

Enumeration Type Documentation

CompileTimeMapStatus

enum class donner::CompileTimeMapStatus

strong

Indicates the result of building a CompileTimeMap.

Enumerator
kOk	Perfect-hash tables were constructed successfully.
kUsingFallbackHash	Map is available but using the linear fallback path instead of perfect hashing.
kDuplicateKey	Duplicate keys were detected in the input payload.
kSeedSearchFailed	Perfect-hash seed search failed; map is available via fallback lookup.
kConstexprHashUnsupported	Compile-time hashing is unsupported for this key type when evaluated constexpr.

LengthUnit

enum class donner::LengthUnit : uint8_t

strong

The unit identifier for a length, corresponding to CSS unit identifiers.

See https://www.w3.org/TR/css-values-3/#lengths for definitions.

Enumerator
None	Unitless.
Percent	Percentage, using the '%' symbol.
Cm	Centimeters, 1cm = 96px/2.54.
Mm	Millimeters, 1mm = 1/10th of 1cm.
Q	Quarter-millimeters, 1Q = 1/40th of 1cm.
In	Inches, 1in = 2.54cm = 96px.
Pc	Picas, 1pc = 1/6th of 1in.
Pt	Points, 1pt = 1/72nd of 1in.
Px	Pixels, 1px = 1/96th of 1in.
Em	Font size, 1em = current font size.
Ex	x-height of the current font, 1ex = x-height of current font.
Ch	Width of the glyph '0' in the current font, 1ch = width of '0' in current font.
Rem	Root font size, 1rem = font size of the root element.
Vw	Viewport width, 1vw = 1% of viewport width.
Vh	Viewport height, 1vh = 1% of viewport height.
Vmin	Smaller of viewport width and height, 1vmin = 1% of smaller of viewport width and height.
Vmax	Larger of viewport width and height, 1vmax = 1% of larger of viewport width and height.

StringComparison

enum class donner::StringComparison : uint8_t

strong

String comparison options, e.g. case sensitivity.

Enumerator
Default	The default case-sensitive string comparison.
IgnoreCase	Case-insensitive string comparison.

Function Documentation

DecodeBase64Data()

ParseResult< std::vector< uint8_t > > donner::DecodeBase64Data

(

std::string_view

base64String

)

Decode a base64-encoded string into a byte array.

If the string is not valid base64, an error is returned.

Parameters

base64String

The base64-encoded string to decode.

Returns

The decoded byte array, or an error if the input is not valid base64.

EncodeBase64Data()

std::string donner::EncodeBase64Data

(

std::span< const uint8_t >

data

)

Encode a byte array into a base64-encoded string.

Parameters

data	The byte array to encode.

Returns

The base64-encoded string.

InRange()

template<typename T, typename = std::enable_if<std::is_integral<T>::value>>

bool donner::InRange ( T var, T start, T end )

inline

Test if a variable is in a specific range, using an optimized technique that requires only one branch.

Some compilers do this automatically.

Example:

if (InRange(var, 'a', 'z')) // ...

Lerp()

template<typename T>

T donner::Lerp ( T a, T b, const float t )

inline

Returns linear interpolation of a and b with ratio t.

Returns

a if t == 0, b if t == 1, and the linear interpolation else.

MATCHER_P() [1/5]

donner::MATCHER_P	(	NormalizedEq	,
		expectedVector	,
		""	)

Matches if two vectors are equal when both are normalized, within an error of 0.01.

Example:

EXPECT_THAT(Vector2d(1.0, 2.0), NormalizedEq(Vector2d(2.0, 4.0)));

Parameters

expectedVector

Expected value vector, which will be normalized.

MATCHER_P() [2/5]

donner::MATCHER_P	(	ParseErrorIs	,
		errorMessageMatcher	,
		std::string("parse error is (")+testing::PrintToString(errorMessageMatcher)+")"	)

Given a ParseResult, matches if it contains an error whose reason matches the given errorMessageMatcher (string or matcher).

Outputs a readable message on mismatch, e.g.: Expected: parse error is (starts with "Unexpected") Actual: parse error reason is "Failed to parse number: not finite"

Usage:

EXPECT_THAT(error, ParseErrorIs("My message"));
EXPECT_THAT(error, ParseErrorIs(StartsWith("Err")));

Parameters

errorMessageMatcher

Matcher to match the error message against, either a string or gmock matcher.

MATCHER_P() [3/5]

donner::MATCHER_P	(	ParseResultIs	,
		resultMatcher	,
		""	)

Matches if a ParseResult contains a result that matches the given value, and that it does not contain an error.

Parameters

resultMatcher

Value to match with.

MATCHER_P() [4/5]

donner::MATCHER_P	(	ToStringIs	,
		expected	,
		""	)

Matches the string representation of an object, by calling testing::PrintToString and comparing the results with the expected value.

Example:

EXPECT_THAT(myObject, ToStringIs("MyObject(foo)"));

Parameters

expected

Expected string representation.

MATCHER_P() [5/5]

donner::MATCHER_P	(	TransformEq	,
		other	,
		"transform eq "+	testing::PrintToStringother )

Matches a transform with near-equals comparison.

Example:

EXPECT_THAT(result, TransformEq(Transformd::Scale({2.0, 2.0})));

Parameters

other

Transform object to compare.

MATCHER_P2() [1/6]

donner::MATCHER_P2	(	BoxEq	,
		topLeftMatcher	,
		bottomRightMatcher	,
		""	)

Matches a Box.

Parameters

topLeftMatcher	Matcher for topLeft field.
bottomRightMatcher	Matcher for bottomRight field.

MATCHER_P2() [2/6]

donner::MATCHER_P2	(	LengthIs	,
		valueMatcher	,
		unitMatcher	,
		""	)

Matches a Length.

Example:

EXPECT_THAT(Length(10.0, Lengthd::Unit::Cm), LengthIs(10.0, Lengthd::Unit::Cm));

Parameters

valueMatcher	Matcher for value field.
unitMatcher	Matcher for unit field.

MATCHER_P2() [3/6]

donner::MATCHER_P2	(	ParseErrorPos	,
		lineMatcher	,
		offsetMatcher	,
		""	)

Given a ParseResult, matches if it contains an error at the given offset.

Parameters

lineMatcher	Line number of the error.
offsetMatcher	Column offset of the error.

MATCHER_P2() [4/6]

donner::MATCHER_P2	(	ParseResultAndError	,
		resultMatcher	,
		errorMessageMatcher	,
		""	)

Matches if a ParseResult contains a result that matches the given value, and that it does not contain an error.

Parameters

resultMatcher	Result to match with.
errorMessageMatcher	Parse error message to match with, either a string or a gmock matcher.

MATCHER_P2() [5/6]

donner::MATCHER_P2	(	Vector2Eq	,
		xMatcher	,
		yMatcher	,
		""	)

Matches a Vector.

Example:

EXPECT_THAT(Vector2i(1, 2), Vector2Eq(1, 2));

Parameters

xMatcher	X coordinate matcher.
yMatcher	Y coordinate matcher.

MATCHER_P2() [6/6]

donner::MATCHER_P2	(	Vector2Near	,
		xValue	,
		yValue	,
		""	)

Matches a Vector2 with DoubleNear(0.01).

Parameters

xValue	X coordinate, note that this is not a matcher.
yValue	Y coordinate, note that this is not a matcher.

MATCHER_P6()

donner::MATCHER_P6	(	TransformIs	,
		d0	,
		d1	,
		d2	,
		d3	,
		d4	,
		d5	,
		""	)

Matches a transform per-element, with a near-equals comparison using a threshold of 0.0001.

Example:

EXPECT_THAT(result, TransformIs(1.0, 0.0, 0.0, 1.0, 0.0, 0.0));

Parameters

d0	Corresponds to Transform::data[0]
d1	Corresponds to Transform::data[1]
d2	Corresponds to Transform::data[2]
d3	Corresponds to Transform::data[3]
d4	Corresponds to Transform::data[4]
d5	Corresponds to Transform::data[5]

NarrowToFloat()

float donner::NarrowToFloat ( double from )

inline

Semantically represent a narrowing conversion, such as converting a double to a float, to make the conversion more visible.

For example: const float f = NarrowToFloat(1.0);

parentsGenerator()

template<ElementLike T>

ElementTraversalGenerator< T > donner::parentsGenerator

(

T

element

)

A generator that yields all parents of an element, repeatedly following parentElement() until reaching the root.

Parameters

element

The element to start from, which is not yielded.

previousSiblingsGenerator()

template<ElementLike T>

ElementTraversalGenerator< T > donner::previousSiblingsGenerator

(

T

element

)

A generator that yields all siblings of an element, in reverse order.

This repeatedly follows previousSibling().

Parameters

element

The element to start from, which is not yielded.

singleElementGenerator()

template<ElementLike T>

ElementTraversalGenerator< T > donner::singleElementGenerator

(

T

element

)

A generator that yields a single element, if it exists.

Parameters

element

The element to yield. If this is std::nullopt, the generator will yield nothing.

SolveQuadratic()

template<typename T>

QuadraticSolution< T > donner::SolveQuadratic	(	T	a,
		T	b,
		T	c )

Solve a quadratic equation.

\( a x^2 + b x + c = 0 \)

Parameters

a	First coefficient.
b	Second coefficient.
c	Third coefficient.

Returns

QuadraticSolution, containing 0-2 solutions.

UrlDecode()

std::vector< uint8_t > donner::UrlDecode

(

std::string_view

urlEncodedString

)

Decode a URL-encoded string into a byte array, translating XX sequences into the corresponding byte value.

See also

https://url.spec.whatwg.org/#percent-encoded-bytes

Parameters

urlEncodedString

The URL-encoded string to decode.

Returns

A vector of decoded byte values.