How Conversions Are Handled in TheAlgorithms/Java: A Complete Guide to the Conversion Framework

TheAlgorithms/Java handles conversions through a dual architecture that combines a generic affine-based unit conversion system for measurement units with a library of stateless static utility classes for specific transformations like numeral systems, color spaces, and text encoding.

The com.thealgorithms.conversions package in the TheAlgorithms/Java repository provides a comprehensive, production-ready framework for data-type and unit transformations. This conversion framework employs two complementary design strategies: an extensible graph-based system for measurement units and a collection of focused static utilities for specialized algorithms. All conversion classes are intentionally stateless, implementing the private constructor pattern to ensure thread safety and eliminate instantiation overhead.

Generic Affine-Based Unit Conversion

The framework's first approach uses immutable affine transformations to automatically derive conversion paths between measurement units. This eliminates the need to write explicit conversion methods for every possible unit pair.

Core Components

Three classes form the backbone of this system:

• AffineConverter – An immutable representation of the linear equation y = slope × x + intercept. Stored in src/main/java/com/thealgorithms/conversions/AffineConverter.java, this class provides convert(), invert(), and compose() methods for building transformation chains.
• UnitsConverter – The engine class (src/main/java/com/thealgorithms/conversions/UnitsConverter.java) that constructs a complete conversion graph from minimal base formulas. It automatically generates inverse conversions via the invert() method and creates composite conversions through compose(), storing the transitive closure in an internal conversions map.
• UnitConversions – A convenience holder (src/main/java/com/thealgorithms/conversions/UnitConversions.java) that exposes pre-configured UnitsConverter instances. Currently, it defines TEMPERATURE for Celsius, Fahrenheit, and Kelvin conversions.

Automatic Graph Construction

When you instantiate UnitsConverter with a base set of unit relationships, the constructor automatically calculates the transitive closure. If you provide a conversion from meters to feet, the engine immediately creates the inverse (feet to meters) and can chain through intermediate units to reach any connected node in the graph.

Usage Example

// Convert 100°C to Fahrenheit using the pre-configured converter
double fahrenheit = UnitConversions.TEMPERATURE.convert("Celsius", "Fahrenheit", 100.0);
System.out.println(fahrenheit); // 212.0

// Build a custom length converter with automatic inverse generation
Map<Pair<String,String>, AffineConverter> base = Map.of(
    Pair.of("Meter", "Foot"), new AffineConverter(3.28084, 0.0)
);
UnitsConverter length = new UnitsConverter(base);
double feet = length.convert("Meter", "Foot", 2.5); // 8.2021...
double meters = length.convert("Foot", "Meter", 8.2021); // Automatically derived: 2.5

Special-Purpose Static Conversion Utilities

For transformations that do not fit the affine model, the package provides dozens of utility classes following a strict static API pattern.

Design Pattern

Each utility class adheres to this structure:

public final class SomeConversion {
    private SomeConversion() { } // Prevent instantiation
    
    public static ReturnType convert(ParamType input) {
        // Algorithm implementation
    }
}

This design makes the API discoverable (ClassName.convert(...)), eliminates mutable state, and guarantees thread safety without synchronization.

Representative Classes

The package includes specialized converters for diverse domains:

• TurkishToLatinConversion – Text transliteration (convertTurkishToLatin(String)) stored in src/main/java/com/thealgorithms/conversions/TurkishToLatinConversion.java.
• RgbHsvConversion – Color-space transformations with rgbToHsv(int,int,int) and hsvToRgb(double,double,double) methods.
• RomanToInteger and IntegerToRoman – Bidirectional Roman numeral conversion via romanToInt(String) and intToRoman(int).
• BinaryToDecimal, DecimalToBinary, OctalToBinary – Base-N numeral system conversions.
• MorseCodeConverter – Text encoding/decoding with encode(String) and decode(String).
• IPConverter and IPv6Converter – Network address transformations (ipv4ToLong(String), longToIpv4(long)).
• EndianConverter – Byte-order swapping for primitives (swapEndianInt(int)).
• TimeConverter – Temporal unit conversion (convert(long, TimeUnit, TimeUnit)).
• WordsToNumber and NumberToWords – Natural language number parsing.

Static Utility Examples

// Turkish text transliteration
String latin = TurkishToLatinConversion.convertTurkishToLatin("İstanbul");
System.out.println(latin); // "Istanbul"

// Color space conversion
double[] hsv = RgbHsvConversion.rgbToHsv(255, 0, 0); // Red → [0.0, 1.0, 1.0]
int[] rgb = RgbHsvConversion.hsvToRgb(120.0, 1.0, 1.0); // Green → [0, 255, 0]

// Numeral system conversion
int decimal = BinaryToDecimal.binaryToDecimal("1011"); // 11
String binary = DecimalToBinary.decimalToBinary(42);   // "101010"

All static methods validate inputs and throw IllegalArgumentException for malformed data, such as invalid color components or malformed numeral strings.

Extending the Conversion Framework

Adding new functionality requires selecting the appropriate architectural path:

For measurement units, create a new UnitsConverter instance in UnitConversions with a minimal set of base AffineConverter objects. The engine automatically generates inverse and chained conversions, requiring only one directional formula per unit pair.

For algorithmic conversions, implement a final class with a private constructor and static conversion methods. Place the file under src/main/java/com/thealgorithms/conversions/ and include corresponding JUnit tests in src/test/java/com/thealgorithms/conversions/.

Summary

• Dual architecture: TheAlgorithms/Java combines a generic affine-based graph system (AffineConverter, UnitsConverter) for measurement units with specialized static utilities for specific algorithms.
• Automatic derivation: The UnitsConverter class automatically builds inverse and composite conversions from minimal base formulas, eliminating redundant code.
• Stateless design: All conversion classes use private constructors and static methods, ensuring thread safety and zero instantiation cost.
• Comprehensive coverage: The package includes converters for temperature, color spaces, numeral systems (binary, decimal, octal, Roman), IP addresses, Morse code, endianness, and natural language numbers.
• Extensibility: New measurement domains require only base unit definitions, while new algorithmic conversions follow a simple static utility pattern.

Frequently Asked Questions

What is the difference between AffineConverter and the static utility classes?

AffineConverter is an immutable mathematical representation of linear transformations (y = mx + b) used specifically for measurement units like temperature and length, while static utility classes implement discrete algorithms for non-linear transformations like Roman numerals, color spaces, or text encoding. The affine system automatically derives conversion paths, whereas static utilities implement explicit one-to-one mappings.

How does UnitsConverter automatically generate inverse conversions?

The UnitsConverter constructor calls invert() on each AffineConverter in the base map to create reverse mappings (e.g., Fahrenheit to Celsius from the Celsius to Fahrenheit definition). It then computes the transitive closure using compose() to generate conversion paths between indirectly connected units, storing all reachable pairs in the internal conversions map.

Are the conversion classes in TheAlgorithms/Java thread-safe?

Yes, all conversion classes are thread-safe. The affine-based classes (AffineConverter, UnitsConverter) are immutable value objects. The static utility classes follow the private constructor pattern, exposing only stateless public static methods with no shared mutable state, making them safe for concurrent access without synchronization.

How can I add a new conversion type to the repository?

For measurement units, add a new UnitsConverter instance to UnitConversions.java with base AffineConverter definitions for your unit relationships. For specialized conversions, create a final class under src/main/java/com/thealgorithms/conversions/ with a private constructor and static conversion methods, following the pattern used by TurkishToLatinConversion or BinaryToDecimal. Include comprehensive JUnit tests in the corresponding test directory.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}