Type System¶

The dross type system provides dynamic typing with strong value semantics. All types use the Pimpl idiom for ABI stability and provide consistent interfaces.

Core Types¶

value¶

class value¶

Polymorphic value type that can hold any supported dross type.

The value class provides a type-safe polymorphic container that can hold any of the core dross types (number, string, array, dictionary). It uses std::variant internally for type safety and performance, and provides convenient construction and conversion methods.

Key features:

Type-safe polymorphic storage using std::variant
Value semantics (copyable and assignable)
Convenient construction from any supported type
Template-based type checking and casting
Support for initializer list construction
Thread-safe for read operations

Supported types:

boolean: True/false values with logical operations
number: Arbitrary precision arithmetic
string: Unicode-aware strings
array: Dynamic arrays of values
dictionary: Key-value mappings
datetime: Date and time values with timezone support
Arithmetic types (automatically converted to number)
String types (automatically converted to string)

Performance characteristics:

Construction: O(1) for simple types, O(n) for complex types
Type checking: O(1) compile-time and runtime checks
Casting: O(1) with type safety validation
Memory usage: Size of largest possible type plus small overhead

Thread safety:

Const operations are thread-safe
Non-const operations require external synchronization

// Basic usage with different types
value bool_val = boolean{true};
value num = number{42};
value str = string{"hello"};
value arr = array{value{1}, value{2}, value{3}};

// Automatic type conversion
value int_val = 123;      // Creates number
value str_val = "text";   // Creates string

// Type checking and casting
if (num.is<number>()) {
    number n = value_cast<number>(num);
}

// Initializer list construction
value list_val = {value{1}, value{"two"}, value{3.0}};

Public Functions

value()¶: Default constructor creating a null value.

value(const value &other)¶

Copy constructor.

Parameters:: other – The value to copy from

value(const boolean &bool_val)¶

Construct from a boolean.

Parameters:: bool_val – The boolean to store

value(const number &num)¶

Construct from a number.

Parameters:: num – The number to store

value(const string &str)¶

Construct from a string.

Parameters:: str – The string to store

value(const array &arr)¶

Construct from an array.

Parameters:: arr – The array to store

value(const dictionary &dict)¶

Construct from a dictionary.

Parameters:: dict – The dictionary to store

value(const datetime &dt)¶

Construct from a datetime.

Parameters:: dt – The datetime to store

value(const std::initializer_list<value> &values)¶

Construct an array from initializer list.

Creates an array value from the provided initializer list.

Parameters:: values – Initializer list of values to create an array

~value()¶: Destructor.

template<number_type T> inline value(const T n)¶

Construct from any arithmetic type.

Automatically converts arithmetic types to number for convenient usage.

Parameters:: n – The arithmetic value to convert to number

template<string_type T> inline value(const T s)¶

Construct from any string-like type.

Automatically converts string types to string for convenient usage.

Parameters:: s – The string value to convert to string

bool equals(const value &other) const¶

Test equality with another value.

Performs deep comparison considering both type and content.

Parameters:: other – The value to compare with
Returns:: true if both values contain the same type and data

bool operator==(const value &other) const¶

Equality comparison operator.

Parameters:: other – The value to compare with
Returns:: true if values are equal

bool operator!=(const value &other) const¶

Inequality comparison operator.

Parameters:: other – The value to compare with
Returns:: true if values are not equal

explicit operator bool() const¶

Convert to boolean for truthiness testing.

Allows using value in boolean contexts like if statements. Returns false for null values, empty strings, arrays, and dictionaries.

Returns:: true if the value is not null/empty, false otherwise

value &operator=(const std::nullptr_t)¶

Assignment from nullptr (creates null value).

Parameters:: nullptr – value to assign
Returns:: Reference to this value

value &operator=(const value &other)¶

Copy assignment operator.

Parameters:: other – The value to assign from
Returns:: Reference to this value

value &operator=(const boolean &bool_val)¶

Assignment from boolean.

Parameters:: bool_val – The boolean to assign
Returns:: Reference to this value

value &operator=(const number &num)¶

Assignment from number.

Parameters:: num – The number to assign
Returns:: Reference to this value

value &operator=(const string &str)¶

Assignment from string.

Parameters:: str – The string to assign
Returns:: Reference to this value

value &operator=(const array &arr)¶

Assignment from array.

Parameters:: arr – The array to assign
Returns:: Reference to this value

value &operator=(const dictionary &dict)¶

Assignment from dictionary.

Parameters:: dict – The dictionary to assign
Returns:: Reference to this value

value &operator=(const datetime &dt)¶

Assign a datetime to this value.

Parameters:: dt – The datetime to assign
Returns:: Reference to this value

template<class T> bool is() const noexcept¶

Check if the value contains a specific type.

Use this for type checking before casting to avoid exceptions. Supports checking for boolean, number, string, array, dictionary, and datetime types.

Template Parameters:: T – The type to check for
Returns:: true if the value contains type T, false otherwise

template<class T> T as() const noexcept¶

Cast the value to a specific type.

This is a convenience method that delegates to value_cast. If the value is not of the requested type, the behavior is undefined. Use is<T>() to check the type before casting.

Template Parameters:: T – The type to cast to
Returns:: The value as the specified type

class storage¶

Public Functions

storage() = default¶

inline storage(const storage &s)¶

Public Members

std::variant<std::monostate, dross::boolean, dross::number, dross::string, dross::array, dross::dictionary, dross::datetime> value¶

The value class is the central polymorphic type that can hold any supported type:

#include <dross/value.h>

dross::value v1 = 42;                                    // Holds a number
dross::value v2 = "hello";                               // Holds a string
dross::value v3 = dross::array{};                        // Holds an array
dross::value v4 = true;                                  // Holds a boolean
dross::value v5 = dross::datetime{2024, 1, 21, 15, 30, 0, dross::timezone::offset(9)}; // Holds a datetime

// Type checking with seamless string conversion
if (v1.is<dross::number>()) {
    auto num = v1.as<dross::number>();
    std::cout << num << std::endl;  // Direct output
}

if (v5.is<dross::datetime>()) {
    auto dt = v5.as<dross::datetime>();
    std::cout << "Meeting time: " << dt << std::endl;
}

boolean¶

class boolean¶

Boolean type with value semantics and type safety.

The boolean class provides a type-safe boolean value with explicit conversions and full integration with the dross type system. Unlike native bool, this class provides consistent behavior across the type system and enables features like null/undefined distinction when used with std::optional.

Key features:

Type-safe boolean operations
Seamless string conversion (“true”/”false”)
Integration with dross type system
Value semantics (copyable and assignable)
Three-way comparison support
Safe conversions from various types
Thread-safe for read operations

Performance characteristics:

Construction: O(1)
Comparison: O(1)
String conversion: O(1) (returns constant strings)
Memory usage: Minimal (single boolean value + Pimpl overhead)

Thread safety:

Const operations are thread-safe
Non-const operations require external synchronization

// Basic usage
boolean flag{true};
boolean enabled{"true"};  // From string
boolean disabled{0};      // From integer (0 = false, non-zero = true)

// Boolean operations
if (flag) {
    // Handle true case
}

// Logical operations
boolean a{true};
boolean b{false};
boolean result = a && b;  // false

// String conversion (multiple approaches)
std::string str1 = flag;               // Implicit conversion
std::string str2 = to_string(flag);    // STL-style explicit conversion

// Comparison
if (flag == true) {
    // Direct comparison with bool
}

Public Functions

boolean()¶: Default constructor creating a boolean with value false.

boolean(const boolean &other)¶

Copy constructor.

Parameters:: other – The boolean to copy from

boolean(bool value)¶

Construct from native bool.

Parameters:: value – The boolean value

boolean(int value)¶

Construct from integer.

Follows C++ convention where 0 is false and any non-zero value is true.

Parameters:: value – The integer value (0 = false, non-zero = true)

boolean(const std::string &str)¶

Construct from string.

Accepts “true”, “false”, “TRUE”, “FALSE”, “True”, “False”. Also accepts “1” for true and “0” for false. Any other string value results in false.

Parameters:: str – String representation (“true” or “false”, case-insensitive)

boolean(const char *str)¶

Construct from C-style string.

Same parsing rules as std::string constructor.

Parameters:: str – C-style string representation

~boolean()¶: Destructor.

bool value() const¶

Get the boolean value.

Returns:: The underlying boolean value

bool equals(const boolean &other) const¶

Test equality with another boolean.

Parameters:: other – The boolean to compare with
Returns:: true if both booleans have the same value

bool equals(bool value) const¶

Test equality with a native bool.

Parameters:: value – The bool to compare with
Returns:: true if this boolean equals the bool value

bool operator==(const boolean &other) const¶

Equality comparison operator.

Parameters:: other – The boolean to compare with
Returns:: true if both booleans are equal

bool operator!=(const boolean &other) const¶

Inequality comparison operator.

Parameters:: other – The boolean to compare with
Returns:: true if booleans are not equal

bool operator==(bool value) const¶

Equality comparison with native bool.

Parameters:: value – The bool to compare with
Returns:: true if this boolean equals the bool value

bool operator!=(bool value) const¶

Inequality comparison with native bool.

Parameters:: value – The bool to compare with
Returns:: true if this boolean does not equal the bool value

std::strong_ordering operator<=>(const boolean &other) const noexcept¶

Three-way comparison operator (spaceship operator).

Defines a total ordering where false < true, consistent with the standard boolean ordering in C++.

Parameters:: other – The boolean to compare with
Returns:: std::strong_ordering result (false < true)

boolean &operator=(const boolean &other)¶

Copy assignment operator.

Parameters:: other – The boolean to assign from
Returns:: Reference to this boolean

boolean &operator=(bool value)¶

Assignment from native bool.

Parameters:: value – The bool value to assign
Returns:: Reference to this boolean

boolean operator!() const¶

Logical NOT operator.

Returns:: New boolean with inverted value

boolean operator&&(const boolean &other) const¶

Logical AND operator.

Parameters:: other – The boolean to AND with
Returns:: New boolean with result of AND operation

boolean operator||(const boolean &other) const¶

Logical OR operator.

Parameters:: other – The boolean to OR with
Returns:: New boolean with result of OR operation

operator bool() const¶

Convert to native bool.

Allows boolean to be used directly in conditional contexts.

Returns:: The underlying boolean value

operator std::string() const¶

Convert to string.

Implicit conversion to string for seamless integration.

Returns:: “true” or “false”

Public Static Functions

static boolean T()¶

Create a true boolean value.

Factory method for creating true values.

Returns:: A boolean representing true

static boolean F()¶

Create a false boolean value.

Factory method for creating false values.

Returns:: A boolean representing false

class storage¶

Public Members

bool value = {false}¶

The boolean class provides type-safe boolean operations:

#include <dross/boolean.h>

dross::boolean flag{true};
dross::boolean enabled{"true"};  // From string
dross::boolean active{1};        // From integer

// Seamless string conversion
std::string status = flag;       // "true"
std::cout << flag << std::endl;  // Direct output

number¶

class number¶

Arbitrary precision number class with string-based storage.

The number class provides arbitrary precision arithmetic operations using string-based internal representation. This allows handling numbers of any size without overflow concerns, making it suitable for financial calculations, cryptographic operations, and scientific computing where precision is critical.

Key features:

Arbitrary precision arithmetic (no overflow)
String-based storage for maximum precision
Support for integers and floating-point numbers
Full set of arithmetic and comparison operators
Conversion to/from standard arithmetic types
NaN (Not a Number) support for error handling
Value semantics (copyable and assignable)
Thread-safe for read operations

Performance characteristics:

Construction: O(n) where n is the number of digits
Arithmetic operations: O(max(m,n)) for addition/subtraction, O(m*n) for multiplication
Comparisons: O(min(m,n)) for most cases
Memory usage: Proportional to the number of digits

Error handling:

Invalid operations return NaN instead of throwing exceptions
Division by zero results in NaN
Invalid string representations result in NaN

Thread safety:

Const operations are thread-safe
Non-const operations require external synchronization

// Basic usage
number a{"123456789012345678901234567890"};
number b{42};
number result = a * b;  // No overflow!

// Arithmetic operations
number sum = number{"999999999999999999"} + number{"1"};

// Comparisons
if (number{"3.14159"} > number{"3.14"}) {
    // Handle greater value
}

// Conversion
double d = static_cast<double>(number{"123.456"});
std::string s = static_cast<std::string>(number{42});

Public Functions

number()¶: Default constructor creating a number with value 0.

number(const number &other)¶

Copy constructor.

Parameters:: other – The number to copy from

number(const char *str)¶

Construct from C-style string.

Accepts decimal numbers in standard notation (e.g., “123”, “-45.67”, “1.23e-4”). Invalid strings result in NaN.

Parameters:: str – Null-terminated string representation of the number

number(const std::string &str)¶

Construct from std::string.

Accepts decimal numbers in standard notation (e.g., “123”, “-45.67”, “1.23e-4”). Invalid strings result in NaN.

Parameters:: str – String representation of the number

template<number_type T> inline number(const T n)¶

Construct from any arithmetic type.

Converts standard arithmetic types (int, float, double, etc.) to number. The conversion preserves the full precision of the input type.

Parameters:: n – The arithmetic value to convert

~number()¶: Destructor.

bool is_nan() const¶

Check if this number represents NaN (Not a Number).

NaN results from invalid operations like division by zero, invalid string parsing, or arithmetic errors.

Returns:: true if the number is NaN, false otherwise

bool is_integer() const¶

Check if this number represents an integer value.

Returns false for NaN values.

Returns:: true if the number has no fractional part, false otherwise

bool equals(const number &other) const¶

Test equality with another number.

NaN is not equal to any value, including itself.

Parameters:: other – The number to compare with
Returns:: true if both numbers represent the same value, false otherwise

template<number_type T> inline bool equals(const T n) const¶

Test equality with an arithmetic value.

Parameters:: n – The arithmetic value to compare with
Returns:: true if this number equals the arithmetic value, false otherwise

std::strong_ordering compare(const number &other) const noexcept¶

Three-way comparison with another number.

Returns std::strong_ordering::unordered if either number is NaN.

Parameters:: other – The number to compare with
Returns:: std::strong_ordering result (less, equal, greater, or unordered)

template<number_type T> inline std::strong_ordering compare(const T n) const noexcept¶

Three-way comparison with an arithmetic value.

Parameters:: n – The arithmetic value to compare with
Returns:: std::strong_ordering result (less, equal, greater, or unordered)

bool operator==(const number &other) const¶

Equality comparison operator.

Parameters:: other – The number to compare with
Returns:: true if both numbers are equal, false otherwise

bool operator!=(const number &other) const¶

Inequality comparison operator.

Parameters:: other – The number to compare with
Returns:: true if numbers are not equal, false otherwise

std::strong_ordering operator<=>(const number &other) const noexcept¶

Three-way comparison operator (spaceship operator).

Parameters:: other – The number to compare with
Returns:: std::strong_ordering result for use with comparison operators

template<number_type T> inline bool operator==(const T n) const¶

Equality comparison with arithmetic types.

Parameters:: n – The arithmetic value to compare with
Returns:: true if this number equals the arithmetic value

template<number_type T> inline bool operator!=(const T n) const¶

Inequality comparison with arithmetic types.

Parameters:: n – The arithmetic value to compare with
Returns:: true if this number does not equal the arithmetic value

template<number_type T> inline std::strong_ordering operator<=>(const T n) const noexcept¶

Three-way comparison with arithmetic types.

Parameters:: n – The arithmetic value to compare with
Returns:: std::strong_ordering result for use with comparison operators

number &operator=(const number &other)¶

Copy assignment operator.

Parameters:: other – The number to assign from
Returns:: Reference to this number

number &operator=(const char *str)¶

Assignment from C-style string.

Parameters:: str – Null-terminated string representation
Returns:: Reference to this number

number &operator=(const std::string &str)¶

Assignment from std::string.

Parameters:: str – String representation of the number
Returns:: Reference to this number

template<number_type T> inline number &operator=(const T n)¶

Assignment from arithmetic types.

Parameters:: n – The arithmetic value to assign
Returns:: Reference to this number

operator std::string() const¶

Convert to string representation.

Returns “NaN” for NaN values. The string format preserves the full precision of the number.

Returns:: String representation of the number

explicit operator int() const¶

Convert to int.

Throws:: std::runtime_error – if the number is NaN or out of range
Returns:: Integer representation, truncated if necessary

explicit operator double() const¶

Convert to double.

May lose precision for very large numbers or numbers with many decimal places.

Throws:: std::runtime_error – if the number is NaN
Returns:: Double-precision floating-point representation

explicit operator long long() const¶

Convert to long long.

Throws:: std::runtime_error – if the number is NaN or out of range
Returns:: Long long integer representation, truncated if necessary

number operator+(const number &other) const¶

Addition operator.

Returns NaN if either operand is NaN.

Parameters:: other – The number to add
Returns:: Result of addition

number operator-(const number &other) const¶

Subtraction operator.

Returns NaN if either operand is NaN.

Parameters:: other – The number to subtract
Returns:: Result of subtraction

number operator*(const number &other) const¶

Multiplication operator.

Returns NaN if either operand is NaN.

Parameters:: other – The number to multiply by
Returns:: Result of multiplication

number operator/(const number &other) const¶

Division operator.

Returns NaN if either operand is NaN or if dividing by zero.

Parameters:: other – The divisor
Returns:: Result of division

number operator%(const number &other) const¶

Modulo operator.

Returns NaN if either operand is NaN, if the divisor is zero, or if either operand is not an integer.

Parameters:: other – The divisor for modulo operation
Returns:: Remainder after division

number &operator+=(const number &other)¶

Addition assignment operator.

Parameters:: other – The number to add
Returns:: Reference to this number after addition

number &operator-=(const number &other)¶

Subtraction assignment operator.

Parameters:: other – The number to subtract
Returns:: Reference to this number after subtraction

number &operator*=(const number &other)¶

Multiplication assignment operator.

Parameters:: other – The number to multiply by
Returns:: Reference to this number after multiplication

number &operator/=(const number &other)¶

Division assignment operator.

Parameters:: other – The divisor
Returns:: Reference to this number after division

number &operator%=(const number &other)¶

Modulo assignment operator.

Parameters:: other – The divisor for modulo operation
Returns:: Reference to this number after modulo operation

Public Static Functions

static number nan()¶

Create a NaN (Not a Number) value.

Use this to create NaN values for error conditions or to test against NaN using is_nan().

Returns:: A number representing NaN

class storage¶

Public Functions

storage() = default¶

inline storage(const char *s)¶

inline storage(const std::string &s)¶

template<number_type T> inline storage(const T &n)¶

Public Members

std::string number = {"0"}¶

The number class provides arbitrary precision numeric values:

#include <dross/number.h>

dross::number n1(42);
dross::number n2("3.14159265358979323846");
dross::number n3 = n1 + n2;

// Seamless string conversion
std::string result = n3;         // Direct conversion
std::cout << n3 << std::endl;    // Direct output

string¶

class string¶

Unicode-aware string class with value semantics.

The string class provides Unicode-aware string handling with a focus on correctness and safety. It uses internal UTF-8 encoding and provides methods for common string operations while maintaining encoding integrity.

Key features:

Unicode-aware string operations
UTF-8 internal encoding
Value semantics (copyable and assignable)
Safe string manipulation methods
Efficient string concatenation
Thread-safe for read operations

Performance characteristics:

Construction: O(n) where n is the string length
Comparison: O(min(m,n)) for most cases
Concatenation: O(m+n) where m and n are string lengths
Memory usage: Proportional to UTF-8 encoded length

Thread safety:

Const operations are thread-safe
Non-const operations require external synchronization

// Basic usage
string greeting{"Hello, 世界!"};
string name{"Alice"};

// String operations
if (greeting.starts_with("Hello")) {
    greeting += " " + name;
}

// Length and comparison
size_t len = greeting.length();  // Unicode-aware length
if (greeting == "Hello, 世界! Alice") {
    // Handle match
}

// Conversion
std::string std_str = greeting;

Public Functions

string()¶: Default constructor creating an empty string.

string(const string &other)¶

Copy constructor.

Parameters:: other – The string to copy from

string(const std::string &str)¶

Construct from std::string.

The input string is assumed to be valid UTF-8. Invalid UTF-8 sequences may result in undefined behavior.

Parameters:: str – The std::string to copy from

string(const char *str)¶

Construct from C-style string.

The input string is assumed to be valid UTF-8. Invalid UTF-8 sequences may result in undefined behavior.

Parameters:: str – Null-terminated C-style string

~string()¶: Destructor.

bool starts_with(const std::string &prefix) const¶

Check if the string starts with a given prefix.

The comparison is Unicode-aware and case-sensitive.

Parameters:: prefix – The prefix to check for
Returns:: true if the string starts with the prefix, false otherwise

size_t length() const¶

Get the Unicode character length of the string.

Returns the count of Unicode code points, which may be different from the byte length for strings containing non-ASCII characters.

Returns:: The number of Unicode characters (not bytes)

bool equals(const string &other) const¶

Test equality with another string.

Parameters:: other – The string to compare with
Returns:: true if both strings contain the same Unicode sequence

bool equals(const std::string &str) const¶

Test equality with a std::string.

Parameters:: str – The std::string to compare with
Returns:: true if the strings are equal

bool equals(const char *str) const¶

Test equality with a C-style string.

Parameters:: str – The C-style string to compare with
Returns:: true if the strings are equal

bool operator==(const string &other) const¶

Equality comparison operator.

Parameters:: other – The string to compare with
Returns:: true if strings are equal

bool operator!=(const string &other) const¶

Inequality comparison operator.

Parameters:: other – The string to compare with
Returns:: true if strings are not equal

bool operator==(const std::string &str) const¶

Equality comparison with std::string.

Parameters:: str – The std::string to compare with
Returns:: true if strings are equal

bool operator!=(const std::string &str) const¶

Inequality comparison with std::string.

Parameters:: str – The std::string to compare with
Returns:: true if strings are not equal

bool operator==(const char *str) const¶

Equality comparison with C-style string.

Parameters:: str – The C-style string to compare with
Returns:: true if strings are equal

bool operator!=(const char *str) const¶

Inequality comparison with C-style string.

Parameters:: str – The C-style string to compare with
Returns:: true if strings are not equal

string &operator=(const string &other)¶

Copy assignment operator.

Parameters:: other – The string to assign from
Returns:: Reference to this string

string &operator=(const std::string &str)¶

Assignment from std::string.

Parameters:: str – The std::string to assign from
Returns:: Reference to this string

string &operator=(const char *str)¶

Assignment from C-style string.

Parameters:: str – The C-style string to assign from
Returns:: Reference to this string

string &operator+=(const string &other)¶

Append another string to this string.

Parameters:: other – The string to append
Returns:: Reference to this string after concatenation

string &operator+=(const std::string &str)¶

Append a std::string to this string.

Parameters:: str – The std::string to append
Returns:: Reference to this string after concatenation

string &operator+=(const char *str)¶

Append a C-style string to this string.

Parameters:: str – The C-style string to append
Returns:: Reference to this string after concatenation

operator std::string() const¶

Convert to std::string.

The returned string maintains the UTF-8 encoding and can be used with standard library string operations.

Returns:: std::string representation with UTF-8 encoding

class storage¶

Public Functions

storage() = default¶

inline storage(const std::string &s)¶

Public Members

std::string buffer¶

The string class provides Unicode-aware string handling:

#include <dross/string.h>

dross::string s1("Hello");
dross::string s2(" World");
dross::string s3 = s1 + s2;

// Seamless string conversion
std::string result = s3;         // Direct conversion
std::cout << s3 << std::endl;    // Direct output

datetime¶

class datetime¶

Date and time handling with modern timezone support.

The datetime class provides comprehensive date and time operations with full timezone support using type-safe timezone objects. It uses std::chrono internally for high precision time calculations while providing a user-friendly API for common operations. This class is designed as a general-purpose datetime type suitable for configuration files, data serialization, logging, scheduling, and any application requiring robust datetime handling.

Key features:

ISO 8601 and RFC 3339 format support
Type-safe timezone operations with timezone class
Integration with std::chrono for duration arithmetic
Value semantics (copyable and assignable)
Thread-safe for read operations
Support for date-only, time-only, and full datetime values
Factory methods for common datetime patterns
Precision control (date_only, time_only, datetime)

Supported datetime formats (ISO 8601 standard):

Offset datetime: 2024-01-21T15:30:00+09:00
UTC datetime: 2024-01-21T15:30:00Z
Local datetime: 2024-01-21T15:30:00
Local date: 2024-01-21
Local time: 15:30:00

Performance characteristics:

Construction: O(1) for time_point, O(n) for string parsing
Arithmetic operations: O(1) using std::chrono
Comparisons: O(1)
Formatting: O(n) where n is the output string length

Thread safety:

Const operations are thread-safe
Non-const operations require external synchronization

// Basic usage with timezone objects
datetime now = datetime::now();
datetime meeting(2024, 1, 21, 15, 30, 0, timezone::offset(9)); // +09:00
datetime utc_meeting(2024, 1, 21, 6, 30, 0, timezone::utc());   // UTC

// Factory methods for specific precision
datetime birthday = datetime::date(1990, 12, 25);  // Date only
datetime alarm = datetime::time(7, 30, 0);         // Time only

// String parsing
datetime iso_meeting("2024-01-21T15:30:00+09:00");

// Duration arithmetic
datetime tomorrow = now + std::chrono::hours(24);
auto age = now - birthday;

// Timezone operations
if (meeting.timezone().is_utc()) {
    std::cout << "Meeting is in UTC" << std::endl;
}
std::cout << "Timezone: " << meeting.timezone().format() << std::endl;

// Formatting
std::string iso_str = meeting.format(datetime_format::iso8601);
std::string custom = meeting.format("%Y-%m-%d %H:%M");

// Conversion to std::chrono
auto time_point = static_cast<std::chrono::system_clock::time_point>(now);

Public Types

enum class precision¶

Precision options for datetime representation.

This enum defines the level of detail stored and displayed in datetime values. It replaces the previous boolean flags with a more explicit and type-safe approach.

Values:

enumerator date_only¶

enumerator time_only¶

enumerator datetime¶

Public Functions

datetime()¶: Default constructor creating epoch time (1970-01-01T00:00:00Z).

datetime(const datetime &other)¶

Copy constructor.

Parameters:: other – The datetime to copy from

datetime(const std::chrono::system_clock::time_point &tp)¶

Construct from std::chrono::system_clock::time_point.

The resulting datetime will be in UTC (no timezone offset).

Parameters:: tp – The time point to construct from

datetime(const std::string &iso8601_str)¶

Construct from ISO 8601 string.

Supports various ISO 8601 formats:

2024-01-21T15:30:00+09:00 (offset datetime)
2024-01-21T15:30:00 (local datetime)
2024-01-21 (local date)
15:30:00 (local time)

Invalid formats will result in epoch time.

Parameters:: iso8601_str – The ISO 8601 formatted string

datetime(const char *iso8601_str)¶

Construct from const char*.

Parameters:: iso8601_str – The ISO 8601 formatted string

datetime(int year, int month, int day, int hour = 0, int minute = 0, int second = 0, const timezone &tz = timezone::local())¶

Construct from individual date and time components.

Parameters:

year – Year (e.g., 2024)
month – Month (1-12)
day – Day of month (1-31)
hour – Hour (0-23, default 0)
minute – Minute (0-59, default 0)
second – Second (0-59, default 0)
tz – Timezone information (default is local timezone)

datetime(int year, int month, int day, int hour, int minute, int second, int timezone_offset_minutes)¶

Legacy constructor with timezone offset in minutes.

Deprecated:: Use timezone object constructor instead

Parameters:

year – Year (e.g., 2024)
month – Month (1-12)
day – Day of month (1-31)
hour – Hour (0-23)
minute – Minute (0-59)
second – Second (0-59)
timezone_offset_minutes – Timezone offset in minutes from UTC

~datetime()¶: Destructor.

datetime &operator=(const datetime &other)¶: Copy assignment operator.

operator std::chrono::system_clock::time_point() const¶

Implicit conversion to std::chrono::system_clock::time_point.

Returns:: The time point representation (always in UTC)

operator std::string() const¶

Implicit conversion to std::string in ISO 8601 format.

Returns:: ISO 8601 formatted string representation

std::strong_ordering operator<=>(const datetime &other) const¶

Three-way comparison operator.

Parameters:: other – The datetime to compare with
Returns:: Comparison result (strong ordering)

bool operator==(const datetime &other) const¶

Equality comparison operator.

Parameters:: other – The datetime to compare with
Returns:: True if the datetimes represent the same moment in time

datetime operator+(const std::chrono::minutes &duration) const¶

Add a duration to this datetime.

Parameters:: duration – The duration to add (in minutes)
Returns:: New datetime with the duration added

datetime operator-(const std::chrono::minutes &duration) const¶

Subtract a duration from this datetime.

Parameters:: duration – The duration to subtract (in minutes)
Returns:: New datetime with the duration subtracted

datetime operator+(const std::chrono::hours &duration) const¶

Add hours to this datetime.

Parameters:: duration – The duration to add (in hours)
Returns:: New datetime with the duration added

datetime operator-(const std::chrono::hours &duration) const¶

Subtract hours from this datetime.

Parameters:: duration – The duration to subtract (in hours)
Returns:: New datetime with the duration subtracted

datetime operator+(const std::chrono::seconds &duration) const¶

Add seconds to this datetime.

Parameters:: duration – The duration to add (in seconds)
Returns:: New datetime with the duration added

datetime operator-(const std::chrono::seconds &duration) const¶

Subtract seconds from this datetime.

Parameters:: duration – The duration to subtract (in seconds)
Returns:: New datetime with the duration subtracted

std::chrono::system_clock::duration operator-(const datetime &other) const¶

Calculate the duration between two datetimes.

Parameters:: other – The other datetime
Returns:: Duration from other to this datetime

std::string format(datetime_format fmt = datetime_format::iso8601) const¶

Format the datetime using predefined format.

Parameters:: fmt – The format to use
Returns:: Formatted string representation

std::string format(const std::string &custom_format) const¶

Format the datetime using custom format string.

Parameters:: custom_format – strftime-style format string
Returns:: Formatted string representation

int year() const¶

Get the year component.

Returns:: Year (e.g., 2024)

int month() const¶

Get the month component.

Returns:: Month (1-12)

int day() const¶

Get the day component.

Returns:: Day of month (1-31)

int hour() const¶

Get the hour component.

Returns:: Hour (0-23)

int minute() const¶

Get the minute component.

Returns:: Minute (0-59)

int second() const¶

Get the second component.

Returns:: Second (0-59)

bool has_timezone() const noexcept¶

Check if this datetime has timezone information.

Returns:: True if timezone offset is available

dross::timezone timezone() const noexcept¶

Get the timezone information.

Returns:: timezone object representing the timezone

precision precision() const noexcept

Get the precision of this datetime.

Returns:: Precision level (date_only, time_only, or datetime)

Public Static Functions

static datetime now()¶

Create a datetime representing the current moment.

Returns:: datetime object set to current system time with local timezone

static datetime date(int year, int month, int day, const timezone &tz = timezone::local())¶

Create a date-only datetime.

Parameters:

year – Year (e.g., 2024)
month – Month (1-12)
day – Day of month (1-31)
tz – Timezone information (default is local timezone)

Returns:

datetime with date precision

static datetime time(int hour, int minute, int second = 0, const timezone &tz = timezone::local())¶

Create a time-only datetime.

Parameters:

hour – Hour (0-23)
minute – Minute (0-59)
second – Second (0-59, default 0)
tz – Timezone information (default is local timezone)

Returns:

datetime with time precision

class storage¶

Public Functions

inline storage()¶

inline storage(const storage &other)¶

Public Members

std::chrono::system_clock::time_point time_point¶

dross::timezone tz¶

enum datetime::precision precision¶

timezone¶

class timezone¶

Timezone representation with offset and formatting support.

The timezone class provides a type-safe and intuitive way to handle timezone information in datetime objects. It supports UTC, local time, and fixed offset timezones with clear, readable API.

Key features:

Type-safe timezone representation
Clear factory methods for common timezone types
ISO 8601 compliant formatting
Integration with datetime class
Value semantics (copyable and assignable)

Supported timezone types:

UTC: Coordinated Universal Time (offset +00:00)
Local: System local timezone (no offset stored)
Fixed offset: Custom offset from UTC in hours/minutes

// Factory methods
auto utc = timezone::utc();
auto jst = timezone::offset(9);           // +09:00
auto pdt = timezone::offset(-7, 0);       // -07:00
auto custom = timezone::from_string("+05:30");  // India Standard Time

// Usage with datetime
datetime dt(2024, 1, 21, 15, 30, 0, timezone::offset(9));

Public Functions

timezone()¶: Default constructor creating local timezone.

timezone(const timezone &other)¶

Copy constructor.

Parameters:: other – The timezone to copy from

~timezone()¶: Destructor.

timezone &operator=(const timezone &other)¶: Copy assignment operator.

bool is_local() const noexcept¶

Check if this is a local timezone.

Returns:: True if timezone represents local system time

bool is_utc() const noexcept¶

Check if this is UTC timezone.

Returns:: True if timezone represents UTC (+00:00)

bool has_offset() const noexcept¶

Check if this timezone has a fixed offset.

Returns:: True if timezone has a specific offset from UTC

std::optional<int> offset_minutes() const noexcept¶

Get the timezone offset in minutes from UTC.

Positive values indicate east of UTC, negative values indicate west of UTC.

Returns:: Offset in minutes, or nullopt for local timezone

std::string format() const¶

Format timezone as ISO 8601 offset string.

Returns:: Formatted string (e.g., “+09:00”, “-05:30”, “Z”, or empty for local)

operator std::string() const¶

Implicit conversion to std::string.

Returns:: ISO 8601 formatted timezone string

bool operator==(const timezone &other) const noexcept¶

Equality comparison.

Parameters:: other – The timezone to compare with
Returns:: True if timezones are equivalent

std::strong_ordering operator<=>(const timezone &other) const noexcept¶

Three-way comparison operator.

Parameters:: other – The timezone to compare with
Returns:: Comparison result based on offset

Public Static Functions

static timezone utc()¶

Create UTC timezone (+00:00).

Returns:: timezone representing UTC

static timezone local()¶

Create local system timezone.

Returns:: timezone representing local system time

static timezone offset(int hours, int minutes = 0)¶

Create timezone with fixed offset.

Positive values are east of UTC, negative values are west of UTC. The minutes parameter is always added to the absolute value of hours.

Parameters:

hours – Offset hours from UTC (-12 to +14)
minutes – Offset minutes from UTC (0 to 59)

Returns:

timezone with specified offset

static timezone from_string(const std::string &tz_str)¶

Parse timezone from ISO 8601 offset string.

Parameters:: tz_str – Timezone string (e.g., “+09:00”, “-05:30”, “Z”)
Returns:: timezone parsed from string, or local timezone if parsing fails

class storage¶

Public Functions

inline storage()¶

inline storage(std::optional<int> offset)¶

inline storage(const storage &other)¶

Public Members

std::optional<int> offset_minutes¶

The timezone class provides type-safe timezone representation:

#include <dross/timezone.h>

// Factory methods for common timezones
auto utc = dross::timezone::utc();           // UTC (+00:00)
auto local = dross::timezone::local();       // System local timezone
auto jst = dross::timezone::offset(9);       // Japan Standard Time (+09:00)
auto pdt = dross::timezone::offset(-7, 0);   // Pacific Daylight Time (-07:00)
auto ist = dross::timezone::offset(5, 30);   // India Standard Time (+05:30)

// Parse from ISO 8601 strings
auto parsed_utc = dross::timezone::from_string("Z");
auto parsed_offset = dross::timezone::from_string("+09:00");

// Timezone operations
if (jst.is_utc()) {
    std::cout << "This is UTC" << std::endl;
}
if (local.is_local()) {
    std::cout << "This is local timezone" << std::endl;
}
if (jst.has_offset()) {
    auto minutes = jst.offset_minutes().value(); // 540 minutes
    std::cout << "Offset: " << minutes << " minutes" << std::endl;
}

// Formatting and string conversion
std::string utc_str = utc.format();     // "Z"
std::string jst_str = jst.format();     // "+09:00"
std::string local_str = local.format(); // "" (empty for local)

// Implicit string conversion
std::string tz_string = jst;            // "+09:00"
std::cout << "Timezone: " << jst << std::endl;

The datetime class provides comprehensive date and time handling with timezone support:

#include <dross/datetime.h>

// Construction with timezone objects (modern API)
dross::datetime meeting{2024, 1, 21, 15, 30, 0, dross::timezone::offset(9)}; // +09:00
dross::datetime local_time{2024, 6, 15, 12, 30, 45, dross::timezone::local()}; // Local timezone
dross::datetime utc_meeting{2024, 1, 21, 6, 30, 0, dross::timezone::utc()}; // UTC

// Factory methods for specific precision
auto birthday = dross::datetime::date(1990, 12, 25); // Date only
auto alarm = dross::datetime::time(7, 30, 0); // Time only

// Construction from ISO 8601 strings
dross::datetime utc_time{"2024-01-21T15:30:00Z"};
dross::datetime offset_time{"2024-01-21T15:30:00+09:00"};
dross::datetime date_only{"2024-01-21"};
dross::datetime time_only{"15:30:00"};

// Current time
dross::datetime now = dross::datetime::now();

// Duration arithmetic
auto tomorrow = now + std::chrono::hours(24);
auto next_week = now + std::chrono::hours(24 * 7);

// Formatting
std::string iso_str = meeting.format();  // ISO 8601 format
std::string custom = meeting.format("%Y-%m-%d %H:%M");

// Component access
int year = meeting.year();
int month = meeting.month();
bool has_tz = meeting.has_timezone();
auto tz = meeting.timezone(); // Get timezone object
auto prec = meeting.precision(); // Get precision level

// Timezone operations
if (meeting.timezone().is_utc()) {
    std::cout << "Meeting is in UTC" << std::endl;
}
std::cout << "Timezone offset: " << meeting.timezone().format() << std::endl;

// Seamless string conversion
std::string meeting_str = meeting;       // "2024-01-21T15:30:00+09:00"
std::cout << meeting << std::endl;       // Direct output

array¶

class array¶

Dynamic array container for value objects with iterator support.

The array class provides a dynamic container that can hold any number of value objects. It supports standard container operations like iteration, indexing, and modification, making it suitable for building complex data structures and APIs that need flexible arrays.

Key features:

Dynamic sizing with automatic memory management
Value semantics (copyable and assignable)
Range-based for loop support through iterators
Type-safe element access
Efficient append and removal operations
Thread-safe for read operations

Performance characteristics:

Element access: O(1) by index
Append operations: Amortized O(1)
Search operations: O(n) linear scan
Memory usage: Proportional to number of elements

Thread safety:

Const operations are thread-safe
Non-const operations require external synchronization

// Basic usage
array numbers = {value{1}, value{2}, value{3}};

// Adding elements
numbers.append(value{4});

// Iteration
for (const auto& item : numbers) {
    // Process each value
}

// Access by index
value& first = numbers[0];

// Search and removal
size_t pos = numbers.index_of(value{2});
numbers.remove(value{2});

Public Functions

array()¶: Default constructor creating an empty array.

array(const array &other)¶

Copy constructor.

Parameters:: other – The array to copy from

array(const std::initializer_list<value> &values)¶

Construct from initializer list.

Allows convenient array creation with brace initialization.

Parameters:: values – Initializer list of values to populate the array

~array()¶: Destructor.

bool empty() const¶

Check if the array is empty.

Returns:: true if the array contains no elements, false otherwise

size_t length() const¶

Get the number of elements in the array.

Returns:: The number of elements currently stored

bool equals(const array &other) const¶

Test equality with another array.

Parameters:: other – The array to compare with
Returns:: true if both arrays contain the same elements in the same order

size_t index_of(const value &val) const¶

Find the index of the first occurrence of a value.

Parameters:: val – The value to search for
Returns:: The index of the first occurrence, or SIZE_MAX if not found

value &value_at(const size_t index) const¶

Get a reference to the value at the specified index.

Parameters:: index – The index to access
Throws:: std::out_of_range – if index is out of bounds
Returns:: Reference to the value at the given index

void append(const value &val)¶

Append a value to the end of the array.

Parameters:: val – The value to append

void append(iterator first, iterator last)¶

Append a range of values from iterators.

Parameters:

first – Iterator pointing to the beginning of the range
last – Iterator pointing to the end of the range

void append(const_iterator first, const_iterator last)¶

Append a range of values from const iterators.

Parameters:

first – Const iterator pointing to the beginning of the range
last – Const iterator pointing to the end of the range

void remove(const value &val)¶

Remove the first occurrence of a value from the array.

If the value is not found, the array remains unchanged.

Parameters:: val – The value to remove

iterator begin()¶

Get an iterator to the beginning of the array.

Returns:: Iterator pointing to the first element

iterator end()¶

Get an iterator to the end of the array.

Returns:: Iterator pointing past the last element

const_iterator begin() const¶

Get a const iterator to the beginning of the array.

Returns:: Const iterator pointing to the first element

const_iterator end() const¶

Get a const iterator to the end of the array.

Returns:: Const iterator pointing past the last element

const_iterator cbegin() const¶

Get a const iterator to the beginning of the array.

Returns:: Const iterator pointing to the first element

const_iterator cend() const¶

Get a const iterator to the end of the array.

Returns:: Const iterator pointing past the last element

bool operator==(const array &other) const¶

Equality comparison operator.

Parameters:: other – The array to compare with
Returns:: true if arrays are equal

bool operator!=(const array &other) const¶

Inequality comparison operator.

Parameters:: other – The array to compare with
Returns:: true if arrays are not equal

array &operator=(const array &other)¶

Copy assignment operator.

Parameters:: other – The array to assign from
Returns:: Reference to this array

value &operator[](const size_t index) const &¶

Access element by index (const version).

Parameters:: index – The index to access
Throws:: std::out_of_range – if index is out of bounds
Returns:: Reference to the value at the given index

value &operator[](const size_t index) &¶

Access element by index (non-const version).

Parameters:: index – The index to access
Throws:: std::out_of_range – if index is out of bounds
Returns:: Reference to the value at the given index

class const_iterator¶

Const forward iterator for array elements.

Provides read-only iterator interface for traversing array elements. Supports range-based for loops and standard library algorithms.

Public Types

using value_type = value ¶

using difference_type = std::ptrdiff_t¶

using pointer = const value*¶

using reference = const value&¶

using iterator_category = std::forward_iterator_tag¶

Public Functions

const_iterator(const const_iterator &other)¶

Copy constructor.

Parameters:: other – The const_iterator to copy from

~const_iterator()¶: Destructor.

const_iterator &operator++()¶

Pre-increment operator.

Returns:: Reference to this iterator after incrementing

const value &operator*() const¶

Dereference operator.

Returns:: Const reference to the current element

bool operator==(const const_iterator &other) const¶

Equality comparison operator.

Parameters:: other – The const_iterator to compare with
Returns:: true if iterators point to the same element

bool operator!=(const const_iterator &other) const¶

Inequality comparison operator.

Parameters:: other – The const_iterator to compare with
Returns:: true if iterators point to different elements

class impl¶

Public Functions

inline impl(std::vector<value>::const_iterator i)¶

Public Members

std::vector<value>::const_iterator cursor¶

class iterator¶

Forward iterator for array elements.

Provides standard iterator interface for traversing array elements. Supports range-based for loops and standard library algorithms.

Public Types

using value_type = value ¶

using difference_type = std::ptrdiff_t¶

using pointer = value*¶

using reference = value&¶

using iterator_category = std::forward_iterator_tag¶

Public Functions

iterator(const iterator &other)¶

Copy constructor.

Parameters:: other – The iterator to copy from

~iterator()¶: Destructor.

iterator &operator++()¶

Pre-increment operator.

Returns:: Reference to this iterator after incrementing

value &operator*()¶

Dereference operator.

Returns:: Reference to the current element

bool operator==(const iterator &other) const¶

Equality comparison operator.

Parameters:: other – The iterator to compare with
Returns:: true if iterators point to the same element

bool operator!=(const iterator &other) const¶

Inequality comparison operator.

Parameters:: other – The iterator to compare with
Returns:: true if iterators point to different elements

class impl¶

Public Functions

inline impl(std::vector<value>::iterator i)¶

Public Members

std::vector<value>::iterator cursor¶

class storage¶

Public Functions

storage() = default¶

inline storage(const std::initializer_list<value> &list)¶

Public Members

std::vector<value> contents¶

The array class provides a dynamic array of values:

#include <dross/array.h>

dross::array arr;
arr.append(42);
arr.append("hello");
arr.append(dross::array{1, 2, 3});

// Range-based for loop
for (const auto& val : arr) {
    std::cout << val << std::endl;  // Direct stream output
}

dictionary¶

class dictionary¶

Key-value container for string keys and value objects.

The dictionary class provides an associative container that maps string keys to value objects. It supports standard dictionary operations like key lookup, insertion, and iteration, making it suitable for configuration data, JSON-like structures, and dynamic object representations.

Key features:

String-to-value mapping with efficient lookup
Value semantics (copyable and assignable)
Iterator support for key-value traversal
Dynamic sizing with automatic memory management
Type-safe element access
Thread-safe for read operations

Performance characteristics:

Key lookup: O(log n) or better depending on implementation
Insertion: O(log n) or better
Iteration: O(n) to visit all elements
Memory usage: Proportional to number of key-value pairs

Thread safety:

Const operations are thread-safe
Non-const operations require external synchronization

// Basic usage
dictionary config;
config["host"] = value{string{"localhost"}};
config["port"] = value{number{8080}};
config["ssl"] = value{string{"true"}};

// Key checking and access
if (config.contains("timeout")) {
    auto timeout = config["timeout"];
}

// Iteration
for (const auto& [key, val] : config) {
    // Process each key-value pair
}

// Size checking
if (!config.empty()) {
    size_t count = config.size();
}

Public Functions

dictionary()¶: Default constructor creating an empty dictionary.

dictionary(const dictionary &other)¶

Copy constructor.

Parameters:: other – The dictionary to copy from

~dictionary()¶: Destructor.

bool equals(const dictionary &other) const¶

Test equality with another dictionary.

Parameters:: other – The dictionary to compare with
Returns:: true if both dictionaries contain the same key-value pairs

bool contains(const std::string &key) const¶

Check if a key exists in the dictionary.

Parameters:: key – The key to search for
Returns:: true if the key exists, false otherwise

bool empty() const¶

Check if the dictionary is empty.

Returns:: true if the dictionary contains no key-value pairs

size_t size() const¶

Get the number of key-value pairs in the dictionary.

Returns:: The number of entries currently stored

bool operator==(const dictionary &other) const¶

Equality comparison operator.

Parameters:: other – The dictionary to compare with
Returns:: true if dictionaries are equal

bool operator!=(const dictionary &other) const¶

Inequality comparison operator.

Parameters:: other – The dictionary to compare with
Returns:: true if dictionaries are not equal

dictionary &operator=(const dictionary &other)¶

Copy assignment operator.

Parameters:: other – The dictionary to assign from
Returns:: Reference to this dictionary

value &operator[](const std::string &key)¶

Access or create a value by key (non-const version).

If the key doesn’t exist, a new entry is created with a default value.

Parameters:: key – The key to access or create
Returns:: Reference to the value associated with the key

const value &operator[](const std::string &key) const¶

Access a value by key (const version).

Parameters:: key – The key to access
Throws:: std::out_of_range – if the key doesn’t exist
Returns:: Const reference to the value associated with the key

iterator begin()¶

Get an iterator to the beginning of the dictionary.

Returns:: Iterator pointing to the first key-value pair

iterator end()¶

Get an iterator to the end of the dictionary.

Returns:: Iterator pointing past the last key-value pair

const_iterator begin() const¶

Get a const iterator to the beginning of the dictionary.

Returns:: Const iterator pointing to the first key-value pair

const_iterator end() const¶

Get a const iterator to the end of the dictionary.

Returns:: Const iterator pointing past the last key-value pair

const_iterator cbegin() const¶

Get a const iterator to the beginning of the dictionary.

Returns:: Const iterator pointing to the first key-value pair

const_iterator cend() const¶

Get a const iterator to the end of the dictionary.

Returns:: Const iterator pointing past the last key-value pair

class const_iterator¶

Const forward iterator for dictionary key-value pairs.

Provides read-only iterator interface for traversing dictionary entries. Each dereferenced iterator returns a pair of const key and value references.

Public Types

using value_type = std::pair<const std::string&, const value&>¶

using difference_type = std::ptrdiff_t¶

using pointer = const value_type*¶

using reference = value_type ¶

using iterator_category = std::forward_iterator_tag¶

Public Functions

const_iterator(const const_iterator &other)¶

Copy constructor.

Parameters:: other – The const_iterator to copy from

~const_iterator()¶: Destructor.

const_iterator &operator++()¶

Pre-increment operator.

Returns:: Reference to this iterator after incrementing

value_type operator*() const¶

Dereference operator.

Returns:: Pair containing const key and value references

bool operator==(const const_iterator &other) const¶

Equality comparison operator.

Parameters:: other – The const_iterator to compare with
Returns:: true if iterators point to the same element

bool operator!=(const const_iterator &other) const¶

Inequality comparison operator.

Parameters:: other – The const_iterator to compare with
Returns:: true if iterators point to different elements

class impl¶

Public Functions

inline impl(std::map<std::string, dross::value>::const_iterator i)¶

Public Members

std::map<std::string, dross::value>::const_iterator cursor¶

class iterator¶

Forward iterator for dictionary key-value pairs.

Provides iterator interface for traversing dictionary entries. Each dereferenced iterator returns a pair of key and value references.

Public Types

using value_type = std::pair<const std::string&, value&>¶

using difference_type = std::ptrdiff_t¶

using pointer = value_type*¶

using reference = value_type ¶

using iterator_category = std::forward_iterator_tag¶

Public Functions

iterator(const iterator &other)¶

Copy constructor.

Parameters:: other – The iterator to copy from

~iterator()¶: Destructor.

iterator &operator++()¶

Pre-increment operator.

Returns:: Reference to this iterator after incrementing

value_type operator*() const¶

Dereference operator.

Returns:: Pair containing key and value references

bool operator==(const iterator &other) const¶

Equality comparison operator.

Parameters:: other – The iterator to compare with
Returns:: true if iterators point to the same element

bool operator!=(const iterator &other) const¶

Inequality comparison operator.

Parameters:: other – The iterator to compare with
Returns:: true if iterators point to different elements

class impl¶

Public Functions

inline impl(std::map<std::string, dross::value>::iterator i)¶

Public Members

std::map<std::string, dross::value>::iterator cursor¶

class storage¶

Public Members

std::map<std::string, dross::value> properties¶

The dictionary class provides key-value storage:

#include <dross/dictionary.h>

dross::dictionary dict;
dict.set("name", "John Doe");
dict.set("age", 30);
dict.set("active", true);

if (auto name = dict.get("name")) {
    std::cout << "Name: " << name->to_string() << std::endl;
}

data¶

class data¶

Public Functions

data()¶

data(const data&)¶

~data()¶

bool empty() const noexcept¶

size_t length() const noexcept¶

The data class provides raw byte storage:

#include <dross/data.h>

std::vector<uint8_t> bytes = {0x48, 0x65, 0x6C, 0x6C, 0x6F};
dross::data d(bytes);

std::cout << "Size: " << d.size() << " bytes" << std::endl;

error¶

class error¶

Public Functions

error()¶

error(const error&)¶

error(int, const std::error_category&)¶

virtual ~error()¶

template<error_enum_type E> inline error(const E e)¶

std::string domain() const¶

int code() const noexcept¶

std::string message() const¶

const std::error_category &category() const noexcept¶

std::error_condition condition() const noexcept¶

explicit operator bool() const noexcept¶

template<error_enum_type E> inline bool operator==(const E e) const noexcept¶

template<error_enum_type E> inline bool operator!=(const E e) const noexcept¶

bool operator==(const std::error_category&) const noexcept¶

bool operator!=(const std::error_category&) const noexcept¶

std::strong_ordering operator<=>(const error&) const noexcept¶

The error class provides structured error information:

#include <dross/error.h>

dross::error err(dross::error_code::invalid_argument,
                 "Invalid value provided");

std::cout << "Error: " << err.message() << std::endl;

Type Concepts¶

The type system uses C++20 concepts to constrain template parameters:

Warning

doxygenconcept: Cannot find concept “dross::value_type” in doxygen xml output for project “dross” from directory: ../../build/doxygen/xml

template<typename T> concept number_type¶

#include <number.h>

Concept that defines arithmetic types suitable for number construction.

Accepts all arithmetic types except const char* to avoid ambiguity with string constructors.

template<typename T> concept string_type¶

#include <string.h>

Concept that defines string-like types for string construction.

Accepts const char* and std::string for convenient string creation.

Warning

doxygenconcept: Cannot find concept “dross::array_type” in doxygen xml output for project “dross” from directory: ../../build/doxygen/xml

Warning

doxygenconcept: Cannot find concept “dross::dictionary_type” in doxygen xml output for project “dross” from directory: ../../build/doxygen/xml

template<typename T> concept datetime_type¶

#include <datetime.h>

Concept that defines types suitable for datetime construction.

This concept accepts types that can be used to construct a datetime object:

std::chrono::system_clock::time_point for precise time point construction
std::string for ISO 8601 formatted datetime strings
const char* for ISO 8601 formatted datetime string literals

This enables flexible datetime construction from various time representations commonly used in applications, configuration files, and data interchange formats.

Type Conversion¶

All types provide seamless string conversion through multiple approaches:

Implicit conversion: std::string s = type_instance;
STL-style function: std::string s = to_string(type_instance);
Stream output: std::cout << type_instance;
as_T() - Convert value to specific type T (for value type)
is_T() - Check if value is of type T (for value type)

Example:

// Multiple string conversion approaches
dross::boolean flag{true};
dross::number n{42};
dross::string text{"hello"};
dross::datetime meeting{2024, 1, 21, 15, 30, 0, dross::timezone::offset(9)}; // +09:00

// 1. Implicit conversion to std::string
std::string flag_str = flag;      // "true"
std::string num_str = n;          // "42"
std::string text_str = text;      // "hello"
std::string datetime_str = meeting; // "2024-01-21T15:30:00+09:00"

// 2. STL-style explicit conversion
using dross::to_string;
auto flag_string = to_string(flag);      // "true"
auto num_string = to_string(n);          // "42"
auto text_string = to_string(text);      // "hello"
auto datetime_string = to_string(meeting); // "2024-01-21T15:30:00+09:00"

// 3. Direct stream output
std::cout << flag << " " << n << " " << text << " " << meeting << std::endl;

// Value type conversion
dross::value v = 42;
if (v.is<dross::number>()) {
    dross::number num = v.as<dross::number>();
    std::string s = to_string(num);  // STL-style conversion
}

// Datetime in value
dross::value dt_value = dross::datetime::now();
if (dt_value.is<dross::datetime>()) {
    auto dt = dt_value.as<dross::datetime>();
    std::cout << "Current time: " << dt.format("%Y-%m-%d %H:%M:%S") << std::endl;
}

Comparison Operations¶

All types support three-way comparison (spaceship operator):

dross::value v1 = 42;
dross::value v2 = 43;

if (v1 < v2) {
    std::cout << "v1 is less than v2" << std::endl;
}

auto result = v1 <=> v2;  // std::strong_ordering

Error Handling¶

Type operations that may fail use std::optional or std::expected:

dross::dictionary dict;

// Returns std::optional<value>
if (auto val = dict.get("key")) {
    process(*val);
}

// Error handling with expected
auto result = parse_json(json_string);
if (!result) {
    std::cerr << "Parse error: " << result.error().message() << std::endl;
}