# Core Functionality

The ucumate library has these core features:

1. Lookup of UCUM expressions
2. Printing of UCUM expressions
3. Validation of UCUM expressions
4. Canonicalization of UCUM expressions
5. Conversion UCUM expressions

All functionality can be accessed through a single class: UCUMService. The library heavily uses sealed interface together with switch pattern matching.

By default, the core library caches validation and canonicalization results. Therefore, any subsequent calls to the same expressions lead to blazingly fast results. So the longer the app runs, the faster the answers on average get. You can change these cache settings if desired. You can also add persistent storage if needed.

UCUMService#lookup can be used to look up a UCUM unit when it is not given by its code. For when you want to parse a UCUMExpression use the validator result.

LookupService.LookupResult lookupResult = ucumService.lookup(input);
String print = switch (lookupResult) {
    case NoMatch noMatch -> "Failed to match a unit";
    case DirectMatch directMatch -> "Direct match found!";
    case MultipleMatches multipleMatches -> "Multiple matches found!";
};

Printing more detailed information about a given UCUM expression is very important. Currently, there are 4 print modes:

1. UCUM Syntax: The parsed UCUM expression is printed in valid UCUM syntax.
2. Expressive UCUM Syntax: Includes the human-readable name when printing a unit. May be used to understand how an expression has been parsed.
3. Common Math Syntax: Prints in UCUM Syntax but replaces the math operators with more commonly used ones (i.e. . -> *, + -> ^).
4. LaTeX Syntax: Produces a string that most LaTeX parsers should be able to process and render.

For example, cm/(s.g2) prints the following:

1. UCUM Syntax: cm/(s.g+2)
2. Expressive UCUM Syntax: c (centi)m (meter)/(s (second).g (gram)+2)
3. Common Math Syntax: cm/(s*g^2)
4. LaTeX Syntax: \frac{\mathrm{cm}}{\left(\mathrm{s} \cdot \mathrm{g}^{2}\right)} which renders to

The default printing mode is the UCUM syntax. It is accessible through the UCUMService#print method.

System.out.println(ucumService.print("cm")); // cm
// or when you have a parsed term object
Term term = ...;
System.out.println(ucumService.print(term));

You may also specify the print mode with another parameter.

System.out.println(ucumService.print("cm", Printer.PrintType.EXPRESSIVE_UCUM_SYNTAX)); // c (centi)m (meter)

UCUMService#validate(String input) can be used to validate any given UCUM expression. The result is either a Success containing the parsed Term or a Failure.

ValidationResult valResult = ucumService.validate("cm.s");
String print = switch(valResult) {
    case Failure failure -> "Invalid input";
    case Success sucess -> ucumService.print(success.term(), Printer.PrintType.EXPRESSIVE_UCUM_SYNTAX);
};
System.out.println(print); // c (centi)m (meter).s (second)

If you are only interested whether a given UCUM expression is valid or invalid you may also use UCUMService#validateToBool(String input).

boolean valid = ucumService.validateToBool("cm.s");
System.out.println(valid); // true

UCUMService#canonicalize can be used to validate any given UCUM expression. The result is either a Success containing the parsed Term and its canonicalization factor obtained during the canonicalization or a FailedCanonicalization.

CanonicalizationResult canonResult = ucumService.canonicalize("[in_i]");
String print = switch (canonResult) {
    case FailedCanonicalization failedCanonicalization -> "Invalid input";
    case Success success -> String.format("Canonicalization Factor: %s, Canonical Form: %s".formatted(success.magnitude(), ucumService.print(success.canonicalTerm())));
};
System.out.println(print); // Canonicalization Factor: 0.0254, Canonical Form: m+1

UCUMService#convert can be used to convert any given UCUM expression to another. The result is either a Success containing the resulting conversion facor or a FailedConversion.

ConversionResult convResult = ucumService.convert("[ft_i]", "[in_i]");
String print = switch (convResult) {
    case FailedConversion failedConversion -> "Conversion failed";
    case Success success -> "1 [ft_i] is %s [in_i]".formatted(success.conversionFactor());
};
System.out.println(print); // 1 [ft_i] is 12 [in_i]