TypeHelper to the rescue!

In this video, I demonstrate and talk about all the great functions that hidden away in the Type Helper codeunit.

https://youtu.be/yJzYlbJ_d4k

In this video, Erik explores Codeunit 10 “Type Helper” in Business Central — a treasure trove of utility functions that many AL developers don’t realize exists. From evaluating strings with culture-specific formatting to URL encoding, bitwise operations, and date manipulation, the Type Helper codeunit can save you from writing a lot of custom code. Erik walks through practical examples of handling locale-specific data conversion, a common pain point when importing data from different countries.

Understanding Strong Typing in AL

Before diving into the Type Helper, it’s important to understand why it exists. AL (Pascal-based) is a strongly typed language. This means you cannot simply assign a value of one type to a variable of another type without explicit conversion.

For example, you cannot assign an integer to a text variable directly — you need to use Format(). Going the other way, converting text to a number, requires Evaluate(). Some languages handle this automatically (dynamically typed languages like Lua, where values have types but variables do not), but AL requires you to be explicit about your conversions.

The Problem with Locale-Specific Formatting

The built-in Evaluate() function works fine when your text data matches the language/locale of your Business Central environment. But what happens when it doesn’t?

Consider decimals: in English-speaking countries, 10.5 means ten and a half. But in Denmark (and many other European countries), the comma is used as the decimal separator, so the same number would be written as 10,5. It gets even more complex — Denmark uses a dot as the thousands separator, so ten thousand and a half would be written as 10.000,5. Sweden uses spaces for thousands separators. Every locale has its own conventions.

The built-in Evaluate() function does have a third parameter, but it only accepts the value 9 (for XML formatting). You can’t pass a language ID like 1030 (Danish) or 1033 (English US) to tell it how to interpret the string. This is where the Type Helper comes to the rescue.

Codeunit 10: Type Helper

The Type Helper is Codeunit 10, and it lives in the Base App (not the System Application, which is where you might expect to find it). Erik notes that this is a very low object number and has been around for quite some time, though it didn’t exist in the earliest character-based versions of Navision.

The Evaluate Function with Culture Support

The key function is TypeHelper.Evaluate(), which accepts four parameters:

  1. Variable (Variant) — the output variable, passed as a variant
  2. String — the input text to evaluate
  3. Format — a .NET format string (e.g., 'G' for general)
  4. Culture Name — a culture identifier like 'da-DK' or 'en-US'

There’s a quirk here: because the variable is passed as a Variant, you need to assign a value of the correct type to the variant before calling the function. The function internally uses a case true of Variable.IsDate, Variable.IsDateTime, Variable.IsDecimal, Variable.IsInteger pattern to determine how to evaluate the string. If the variant has no type, it won’t know what to do.

Erik notes that if this codeunit were ever moved to the System Application, his first pull request would be to create proper overloads so you could pass Date, DateTime, Decimal, or Integer directly instead of going through the Variant workaround.

Getting Culture Names from Language IDs

The Type Helper also includes LanguageIDToCultureName(), which converts a numeric language ID (like 1030 for Danish) into a culture name string (like 'da-DK'). This is much easier than trying to remember culture name codes.

Complete Working Example

Here’s the full example from the video that demonstrates evaluating a Danish-formatted decimal string and then formatting it back:

pageextension 50100 CustomerListExt extends "Customer List"
{
    trigger OnOpenPage();
    var
        TypeHelper: Codeunit "Type Helper";
        i: Integer;
        d: Decimal;
        t: Text;
        V: Variant;
        CultureInfo: Text;
    begin
        CultureInfo := TypeHelper.LanguageIDToCultureName(1030);
        t := '10.000,5';

        //TypeHelper.UrlEncode(t);
        t := TypeHelper.UrlEncode(t);

        // //Evaluate(d, t);
        V := d;
        TypeHelper.Evaluate(V, t, 'G', CultureInfo);
        d := V;
        message('Result = %1 (%2)', d, TypeHelper.FormatDecimal(d, 'G', CultureInfo));
    end;
}

The flow is:

  1. Get the culture name for Danish (language ID 1030) → 'da-DK'
  2. Set the input text to a Danish-formatted number: '10.000,5'
  3. Assign the decimal variable to the variant (giving the variant the Decimal type)
  4. Call TypeHelper.Evaluate() with the format 'G' (general) and the Danish culture
  5. Extract the result back from the variant into the decimal variable
  6. Use TypeHelper.FormatDecimal() to format it back to Danish for display

The result: 10,000.5 is correctly parsed as ten thousand and a half, even though the Business Central environment is running in English.

Format Strings

The format parameter uses .NET standard format strings. Erik references the Microsoft documentation (formerly MSDN) for these. Key format specifiers for numeric values include:

  • C — Currency
  • D — Decimal (integer formatting)
  • E — Exponential/scientific notation
  • F — Fixed-point
  • G — General (the most commonly useful one)

Similar format strings exist for dates, times, and timespans, with both standard and custom format options.

Other Useful Functions in Type Helper

Beyond evaluate and format, the Type Helper codeunit contains a wealth of utility functions that many developers end up reimplementing themselves:

Date and Time Functions

  • GetLocalizedMonthToInt — Get the month number from a localized month name
  • CompareDateTime — Compare two datetimes and get an integer result
  • FormatDate — Format a date with a language ID or current culture
  • GetHoursMinutesSecondsFromTime — Extract time components (Erik notes he’s seen this reimplemented by many developers)
  • IsLeapYear — Check if a year is a leap year
  • AddHoursToDateTime — Add or subtract hours (useful for timezone calculations)
  • GetUserTimezoneOffset — Very useful because functions like CurrentDateTime and Today may return UTC dates when running outside a user session (e.g., via web services)
  • ConvertUnixTimestamp — Convert from Unix time (milliseconds since January 1, 1970) to a DateTime
  • GetFormattedCurrentDateTimeInUserTimeZone — Get the current datetime formatted in the user’s timezone

String and Encoding Functions

  • UrlEncode / UrlDecode — Encode/decode strings for use in URLs (e.g., spaces become %20)
  • HtmlEncode — Encode HTML special characters (brackets, etc.)
  • UriEscapeDataString — A newer, cleaner version of URL encoding
  • GetNewLine / CRLFSeparator — Get the proper line separator characters instead of manually doing CR(13) + CR(10) and risking getting them reversed
  • ReadAsTextWithSeparators — Read text with line separators

Erik points out a design issue with UrlEncode: the function both modifies the parameter by reference (var) and returns a value, meaning both of these lines do the same thing:

TypeHelper.UrlEncode(t);     // modifies t in place (var parameter)
t := TypeHelper.UrlEncode(t); // also returns the value

This dual behavior is confusing and can cause issues with code analyzers. Erik recommends the return-value approach should be the only one supported.

Math and Numeric Functions

  • BitwiseAnd / BitwiseOr / BitwiseXor — Bitwise operations that AL natively lacks
  • IntegerToHex — Convert an integer to hexadecimal
  • GetMaximumOrMinimumOfTwoValues — Get max/min of two values
  • CalculateLog — Logarithmic calculations (not part of built-in math)

Record and Field Functions

  • GetKeyAsString — Convert an entire record’s key to a string representation
  • TransferFieldWithValidate — Transfer a field value with validation
  • GetOptionNumber / GetOptionNumberFromTableField — Work with option values (will be partially replaced by enums)
  • IsNumeric — Check if a value is numeric
  • GetMaximumNumberOfParametersInSQLQuery — Returns 2100 (the SQL Server limit)

Text Comparison

  • TextDistance (Levenshtein Distance) — Calculate the number of edits needed to transform one text into another. Erik mentions this is likely used in the Tell Me search function and shares that he once used it to find duplicate customer names by detecting near-matches and catching typos.

Real-World Application: BCCL Data Import

Erik mentions that in BCCL (his data import/output tool for Business Central), the Type Helper’s evaluate functions are used extensively. While XML, JSON, and Excel have predetermined formatting, delimited files like CSV and TSV have no inherent concept of locale formatting. A Danish CSV file might use commas for decimals and dots for thousands separators, while a UK file does the opposite.

BCCL lets users define what language/locale the file is in, and then every field value is passed through the Type Helper’s evaluate function with the appropriate culture code. This approach is far more reliable than trying to manually manipulate strings by replacing commas with dots.

Conclusion

Codeunit 10 “Type Helper” is a hidden gem in Business Central’s Base App. It contains dozens of utility functions that solve common problems — from locale-aware data conversion to URL encoding, bitwise operations, and date calculations. Many developers write their own versions of these functions without realizing they already exist. The next time you find yourself handling data from a different locale, manipulating URLs, working with Unix timestamps, or needing bitwise operations in AL, check the Type Helper first. It’s likely already got what you need, and it’ll be more robust than a hand-rolled solution.

Picture of hougaard

hougaard