refactor!: consolidate formatting API

BREAKING CHANGE: Rename Format enum values (Iso8601Basic→Iso8601, Iso8601Extended→Iso8601Precise, DateOnly→Iso8601Date, TimeOnly→Iso8601Time), fractional seconds now always 7 digits, DateTimeOffset uses explicit offset format, removed toIso8601Extended()

Author: ronan-fdev

CHANGELOG.md

@@ -13,15 +13,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- NIL
+- **BREAKING**: DateTime::Format enum renamed (`Iso8601Basic` → `Iso8601`, `Iso8601Extended` → `Iso8601Precise`, `DateOnly` → `Iso8601Date`, `TimeOnly` → `Iso8601Time`)
+- **BREAKING**: Fractional seconds always display exactly 7 digits (tick precision) in `Iso8601Precise` format
+- **BREAKING**: DateTimeOffset offset always explicit (`±HH:MM`), removed `Z` notation for UTC
+- **BREAKING**: toString() consolidated to single method with default parameter
 
 ### Deprecated
 
 - NIL
 
 ### Removed
 
-- NIL
+- **BREAKING**: Standalone `toIso8601Extended()` method (use `toString(Format::Iso8601Precise)`)
 
 ### Fixed
 
@@ -31,6 +34,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - NIL
 
+
 ## [0.1.1] - 2025-11-27
 
 ### Changed

README.md

@@ -221,7 +221,8 @@ TimeSpan oneHour = TimeSpan::fromHours(1);
 DateTime later = dt1 + oneHour;
 
 // Formatting
-std::string iso = dt1.toIso8601Extended();  // "2025-01-24T05:42:00.0000000Z"
+std::string iso = dt1.toString(DateTime::Format::Iso8601);             // "2025-01-24T05:42:00Z"
+std::string precise = dt1.toString(DateTime::Format::Iso8601Precise);  // "2025-01-24T05:42:00.0000000Z"
 
 // Epoch timestamp conversions
 std::int64_t epochSeconds = dt1.toEpochSeconds();
@@ -279,8 +280,8 @@ std::int64_t epochMillis = dto1.toEpochMilliseconds();
 DateTimeOffset fromEpoch = DateTimeOffset::fromEpochSeconds(epochSeconds);
 
 // Formatting
-std::string iso = dto1.toString();  // "2025-01-24T05:42:00+02:00"
-std::string extended = dto1.toIso8601Extended();  // "2025-01-24T05:42:00.0000000+02:00"
+std::string iso = dto1.toString();                                      // "2025-01-24T05:42:00+02:00"
+std::string precise = dto1.toString(DateTime::Format::Iso8601Precise);  // "2025-01-24T05:42:00.0000000+02:00"
 ```
 
 ### TimeSpan - Duration Calculations
@@ -355,12 +356,12 @@ int main()
 
     // Get current UTC time
     DateTime now = DateTime::utcNow();
-    std::cout << "Current UTC time: " << now.toIso8601Extended() << std::endl;
+    std::cout << "Current UTC time: " << now.toString(DateTime::Format::Iso8601Precise) << std::endl;
 
     // Calculate future date using TimeSpan
     TimeSpan oneWeek = TimeSpan::fromDays(7);
     DateTime nextWeek = now + oneWeek;
-    std::cout << "One week from now: " << nextWeek.toIso8601Extended() << std::endl;
+    std::cout << "One week from now: " << nextWeek.toString(DateTime::Format::Iso8601Precise) << std::endl;
 
     // Work with timezones
     DateTimeOffset localNow = DateTimeOffset::now();
@@ -510,4 +511,4 @@ All dependencies are automatically fetched via CMake FetchContent when building
 
 ---
 
-_Updated on November 17, 2025_
+_Updated on January 05, 2026_

benchmark/BM_DateTime.cpp

@@ -118,13 +118,13 @@ namespace nfx::time::benchmark
 		}
 	}
 
-	static void BM_DateTime_toIso8601Extended( ::benchmark::State& state )
+	static void BM_DateTime_toIso8601Precise( ::benchmark::State& state )
 	{
 		auto dt{ DateTime::utcNow() };
 
 		for ( auto _ : state )
 		{
-			auto str{ dt.toIso8601Extended() };
+			auto str{ dt.toString( DateTime::Format::Iso8601Precise ) };
 			::benchmark::DoNotOptimize( str );
 		}
 	}
@@ -261,7 +261,7 @@ namespace nfx::time::benchmark
 	//----------------------------------------------
 
 	BENCHMARK( BM_DateTime_ToString_ISO8601 );
-	BENCHMARK( BM_DateTime_toIso8601Extended );
+	BENCHMARK( BM_DateTime_toIso8601Precise );
 
 	//----------------------------------------------
 	// Arithmetic

include/nfx/datetime/DateTime.h

@@ -65,8 +65,8 @@
  * │  2024-01-15T12:30:45Z          │  Jan 15, 2024, 12:30:45 UTC       │
  * │  2024-06-20T00:00:00Z          │  Jun 20, 2024, midnight UTC       │
  * │  2024-12-31T23:59:59Z          │  Dec 31, 2024, 23:59:59 UTC       │
- * │  2024-01-15T12:30:45.123Z      │  With milliseconds (123 ms)       │
- * │  2024-01-15T12:30:45.123456Z   │  With microseconds (123.456 ms)   │
+ * │  2024-01-15T12:30:45.1230000Z  │  With 7-digit fractions (123 ms)  │
+ * │  2024-01-15T12:30:45.1234560Z  │  With microseconds (123.456 ms)   │
  * │  2024-01-15T12:30:45.1234567Z  │  Full precision (100 ns ticks)    │
  * │  1970-01-01T00:00:00Z          │  Unix epoch (start of Unix time)  │
  * │  0001-01-01T00:00:00Z          │  Minimum DateTime value           │
@@ -178,8 +178,8 @@
  * │  DateTime fromEpoch{ DateTime::fromEpochSeconds(epochSecs) };        │
  * │                                                                      │
  * │  // Format output                                                    │
- * │  std::string basic{ dt.toString() };             // Basic ISO 8601   │
- * │  std::string precise{ dt.toIso8601Extended() };  // With fractions   │
+ * │  std::string iso{ dt.toString(Format::Iso8601) };                    │
+ * │  std::string precise{ dt.toString(Format::Iso8601Precise) };         │
  * └──────────────────────────────────────────────────────────────────────┘
  * @endcode
  *
@@ -233,25 +233,28 @@ namespace nfx::time
 		 */
 		enum class Format : std::uint8_t
 		{
-			/** @brief ISO 8601 basic format: "2024-01-01T12:00:00Z" */
-			Iso8601Basic,
+			/** @brief ISO 8601 with seconds precision: "2024-01-01T12:00:00Z" */
+			Iso8601,
 
-			/** @brief ISO 8601 extended format with fractional seconds: "2024-01-01T12:00:00.1234567Z" */
-			Iso8601Extended,
+			/** @brief ISO 8601 with full tick precision (7 decimal digits): "2024-01-01T12:00:00.1234567Z" */
+			Iso8601Precise,
 
-			/** @brief Date and time with timezone: "2024-01-01T12:00:00+02:00" */
+			/** @brief ISO 8601 with numeric offset (always +00:00 for DateTime): "2024-01-01T12:00:00+00:00" */
 			Iso8601WithOffset,
 
-			/** @brief Date only format: "2024-01-01" */
-			DateOnly,
+			/** @brief ISO 8601 compact form without separators: "20240101T120000Z" */
+			Iso8601Compact,
 
-			/** @brief Time only: "12:00:00" */
-			TimeOnly,
+			/** @brief ISO 8601 date only: "2024-01-01" */
+			Iso8601Date,
 
-			/** @brief Epoch timestamp format: "1704110400" (seconds since epoch) */
+			/** @brief ISO 8601 time only: "12:00:00" */
+			Iso8601Time,
+
+			/** @brief Unix epoch seconds (integer): "1704110400" */
 			UnixSeconds,
 
-			/** @brief Epoch timestamp with milliseconds: "1704110400123" */
+			/** @brief Unix epoch milliseconds (integer): "1704110400000" */
 			UnixMilliseconds,
 		};
 
@@ -632,27 +635,13 @@ namespace nfx::time
 		// String formatting
 		//----------------------------------------------
 
-		/**
-		 * @brief Convert to ISO 8601 string (basic format)
-		 * @return String representation in ISO 8601 basic format (e.g., "2024-01-01T12:00:00Z")
-		 * @note This function is marked [[nodiscard]] - the return value should not be ignored
-		 */
-		[[nodiscard]] std::string toString() const;
-
 		/**
 		 * @brief Convert to string using specified format
 		 * @param format The format to use for string conversion
 		 * @return String representation using the specified format
 		 * @note This function is marked [[nodiscard]] - the return value should not be ignored
 		 */
-		[[nodiscard]] std::string toString( Format format ) const;
-
-		/**
-		 * @brief Convert to ISO 8601 extended format with full precision
-		 * @return String representation in ISO 8601 extended format with fractional seconds (e.g., "2024-01-01T12:00:00.1234567Z")
-		 * @note This function is marked [[nodiscard]] - the return value should not be ignored
-		 */
-		[[nodiscard]] std::string toIso8601Extended() const;
+		[[nodiscard]] std::string toString( Format format = Format::Iso8601 ) const;
 
 		//----------------------------------------------
 		// std::chrono interoperability

include/nfx/datetime/DateTimeOffset.h

@@ -57,24 +57,23 @@
  *
  * @par Format Examples:
  * @code
- * ┌────────────────────────────────┬─────────────────────────────────┐
- * │          Input String          │             Meaning             │
- * ├────────────────────────────────┼─────────────────────────────────┤
- * │  2024-01-15T12:30:45Z          │  UTC time (Z = zero offset)     │
- * │  2024-01-15T12:30:45+02:00     │  Local: 12:30, UTC+2 (East)     │
- * │  2024-01-15T12:30:45-05:00     │  Local: 12:30, UTC-5 (West)     │
- * │  2024-01-15T12:30:45.123+01:00 │  With milliseconds, UTC+1       │
- * │  2024-06-20T08:15:00+05:30     │  India Standard Time (UTC+5:30) │
- * │  2024-12-25T00:00:00-08:00     │  Pacific Standard Time (UTC-8)  │
- * └────────────────────────────────┴─────────────────────────────────┘
+ * ┌──────────────────────────────────────┬─────────────────────────────────┐
+ * │            Input String              │             Meaning             │
+ * ├──────────────────────────────────────┼─────────────────────────────────┤
+ * │  2024-01-15T12:30:45+00:00           │  UTC time (explicit offset)     │
+ * │  2024-01-15T12:30:45+02:00           │  Local: 12:30, UTC+2 (East)     │
+ * │  2024-01-15T12:30:45-05:00           │  Local: 12:30, UTC-5 (West)     │
+ * │  2024-01-15T12:30:45.1230000+01:00   │  With 7-digit fractions, UTC+1  │
+ * │  2024-06-20T08:15:00+05:30           │  India Standard Time (UTC+5:30) │
+ * │  2024-12-25T00:00:00-08:00           │  Pacific Standard Time (UTC-8)  │
+ * └──────────────────────────────────────┴─────────────────────────────────┘
  * @endcode
  *
  * @par Timezone Offset Rules:
  * - Valid range: **±14:00:00** (±840 minutes, ±50,400 seconds)
  * - Positive offset: East of UTC (e.g., +09:00 for Japan)
  * - Negative offset: West of UTC (e.g., -05:00 for US Eastern)
- * - **Z** notation: Represents UTC (zero offset), equivalent to +00:00
- * - Offset format: Always ±HH:MM in string representation
+ * - Offset format: Always **±HH:MM** in string representation (explicit, no 'Z' notation)
  *
  * @par Internal Composition:
  * @code
@@ -626,27 +625,13 @@ namespace nfx::time
 		// String formatting
 		//----------------------------------------------
 
-		/**
-		 * @brief Convert to ISO 8601 string with offset
-		 * @return String representation in ISO 8601 format with timezone offset (e.g., "2024-01-01T12:00:00+02:00")
-		 * @note This function is marked [[nodiscard]] - the return value should not be ignored
-		 */
-		[[nodiscard]] std::string toString() const;
-
 		/**
 		 * @brief Convert to string using specified format
 		 * @param format The format to use for string conversion
 		 * @return String representation using the specified format
 		 * @note This function is marked [[nodiscard]] - the return value should not be ignored
 		 */
-		[[nodiscard]] std::string toString( DateTime::Format format ) const;
-
-		/**
-		 * @brief Convert to ISO 8601 extended format with full precision and offset
-		 * @return String representation in ISO 8601 extended format with fractional seconds and offset (e.g., "2024-01-01T12:00:00.1234567+02:00")
-		 * @note This function is marked [[nodiscard]] - the return value should not be ignored
-		 */
-		[[nodiscard]] std::string toIso8601Extended() const;
+		[[nodiscard]] std::string toString( DateTime::Format format = DateTime::Format::Iso8601 ) const;
 
 		//----------------------------------------------
 		// Comparison methods

include/nfx/detail/datetime/DateTime.inl

@@ -299,7 +299,7 @@ namespace std
 
 		auto format( const nfx::time::DateTime& dt, std::format_context& ctx ) const
 		{
-			return format_to( ctx.out(), "{}", dt.toString() );
+			return format_to( ctx.out(), "{}", dt.toString( nfx::time::DateTime::Format::Iso8601 ) );
 		}
 	};
 } // namespace std

samples/Sample_DateTime.cpp

@@ -98,7 +98,7 @@ int main()
 		std::cout << "----------------------------------\n";
 
 		DateTime dt{ 2024, 6, 15, 14, 30, 45, 123 };
-		std::cout << "DateTime: " << dt.toIso8601Extended() << "\n";
+		std::cout << "DateTime: " << dt.toString( DateTime::Format::Iso8601Precise ) << "\n";
 		std::cout << "  Year:         " << dt.year() << "\n";
 		std::cout << "  Month:        " << dt.month() << "\n";
 		std::cout << "  Day:          " << dt.day() << "\n";

src/DateTime.cpp

@@ -373,11 +373,6 @@ namespace nfx::time
 	// String formatting
 	//----------------------------------------------
 
-	std::string DateTime::toString() const
-	{
-		return toString( Format::Iso8601Basic );
-	}
-
 	std::string DateTime::toString( Format format ) const
 	{
 		std::int32_t y, mon, d, h, min, s, ms;
@@ -388,86 +383,61 @@ namespace nfx::time
 
 		switch ( format )
 		{
-			case Format::Iso8601Basic:
+			case Format::Iso8601:
 			{
 				oss << std::setfill( '0' ) << std::setw( 4 ) << y << "-" << std::setw( 2 ) << mon << "-" << std::setw( 2 ) << d << "T" << std::setw( 2 ) << h << ":"
 					<< std::setw( 2 ) << min << ":" << std::setw( 2 ) << s << "Z";
-
 				break;
 			}
-			case Format::Iso8601Extended:
+			case Format::Iso8601Precise:
 			{
 				std::int32_t fractionalTicks{ static_cast<std::int32_t>( m_ticks % constants::TICKS_PER_SECOND ) };
-
-				// Format fractional seconds and strip trailing zeros
-				std::ostringstream fractionOss;
-				fractionOss << std::setfill( '0' ) << std::setw( 7 ) << fractionalTicks;
-				std::string fractionStr = fractionOss.str();
-
-				// Strip trailing zeros (but keep at least one digit if all zeros)
-				auto lastNonZero = fractionStr.find_last_not_of( '0' );
-				if ( lastNonZero != std::string::npos )
-				{
-					fractionStr = fractionStr.substr( 0, lastNonZero + 1 );
-				}
-				else
-				{
-					fractionStr = "0";
-				}
-
 				oss << std::setfill( '0' ) << std::setw( 4 ) << y << "-" << std::setw( 2 ) << mon << "-" << std::setw( 2 ) << d << "T" << std::setw( 2 ) << h
-					<< ":" << std::setw( 2 ) << min << ":" << std::setw( 2 ) << s << "." << fractionStr << "Z";
-
+					<< ":" << std::setw( 2 ) << min << ":" << std::setw( 2 ) << s << "." << std::setw( 7 ) << fractionalTicks << "Z";
 				break;
 			}
 			case Format::Iso8601WithOffset:
 			{
-				// UTC DateTime always has +00:00 offset
 				oss << std::setfill( '0' ) << std::setw( 4 ) << y << "-" << std::setw( 2 ) << mon << "-" << std::setw( 2 ) << d << "T" << std::setw( 2 ) << h
 					<< ":" << std::setw( 2 ) << min << ":" << std::setw( 2 ) << s << "+00:00";
-
 				break;
 			}
-			case Format::DateOnly:
+			case Format::Iso8601Compact:
+			{
+				oss << std::setfill( '0' ) << std::setw( 4 ) << y << std::setw( 2 ) << mon << std::setw( 2 ) << d << "T" << std::setw( 2 ) << h
+					<< std::setw( 2 ) << min << std::setw( 2 ) << s << "Z";
+				break;
+			}
+			case Format::Iso8601Date:
 			{
 				oss << std::setfill( '0' ) << std::setw( 4 ) << y << "-" << std::setw( 2 ) << mon << "-" << std::setw( 2 ) << d;
-
 				break;
 			}
-			case Format::TimeOnly:
+			case Format::Iso8601Time:
 			{
 				oss << std::setfill( '0' ) << std::setw( 2 ) << h << ":" << std::setw( 2 ) << min << ":" << std::setw( 2 ) << s;
-
 				break;
 			}
 			case Format::UnixSeconds:
 			{
 				oss << toEpochSeconds();
-
 				break;
 			}
 			case Format::UnixMilliseconds:
 			{
 				oss << toEpochMilliseconds();
-
 				break;
 			}
 			default:
 			{
-				oss << toString( Format::Iso8601Basic );
-
+				oss << toString( Format::Iso8601 );
 				break;
 			}
 		}
 
 		return oss.str();
 	}
 
-	std::string DateTime::toIso8601Extended() const
-	{
-		return toString( Format::Iso8601Extended );
-	}
-
 	//----------------------------------------------
 	// Validation methods
 	//----------------------------------------------
@@ -742,7 +712,7 @@ namespace nfx::time
 
 	std::ostream& operator<<( std::ostream& os, const DateTime& dateTime )
 	{
-		os << dateTime.toString();
+		os << dateTime.toString( nfx::time::DateTime::Format::Iso8601 );
 
 		return os;
 	}