Conversion Functions

Conversion functions are available throughout the Articles report script editor. They convert values between different types, handle nulls, map codes to descriptions, and transform text and numbers into usable formats for your reports.

---

AgeFromDOB

Calculates a person’s current age in years from a date of birth.

AgeFromDOB(DOB: TDateTime): Integer

Parameter	Type	Description
DOB	TDateTime	The date of birth

Result := IntToStr(AgeFromDOB([Employee.DateOfBirth])) + ' years old';

// Use in a conditional
if AgeFromDOB([Employee.DateOfBirth]) >= 65 then
  Result := 'Eligible for retirement'
else
  Result := 'Not yet eligible';

// Show age on an employee report
Result := 'Age: ' + IntToStr(AgeFromDOB([Employee.DOB]));

---

BoolToText

Converts a boolean or boolean-like variant to a custom true or false string. Similar to FormatBoolText in Formatting Functions.

BoolToText(V: Variant; TrueText, FalseText: String): String

Parameter	Type	Description
V	Variant	The value to evaluate
TrueText	String	Text returned when the value is true
FalseText	String	Text returned when the value is false

Result := BoolToText([Item.Taxable], 'Taxable', 'Non-Taxable');

Result := BoolToText([Customer.OnHold], 'On Hold', 'Active');

Result := BoolToText([Employee.Salaried], 'Salary', 'Hourly');

---

CleanAlpha

Strips everything from a string except letters (A-Z, a-z). Useful for isolating the alphabetic portion of a mixed code or field.

CleanAlpha(S: String): String

Parameter	Type	Description
S	String	The string to clean

Result := CleanAlpha('AB-1234-CD');
// Returns: 'ABCD'

// Extract only the letters from a mixed item code
Result := CleanAlpha([Item.Code]);

// Use to get just the state letters from a formatted field
Result := CleanAlpha('FL 33101');
// Returns: 'FL'

---

CleanNumber

Strips everything from a string except digits (0-9). Use this before passing a phone number, SSN, or zip code to a formatting function.

CleanNumber(S: String): String

Parameter	Type	Description
S	String	The string to clean

Result := CleanNumber('(555) 123-4567');
// Returns: '5551234567'

// Always clean before formatting
Result := FormatPhone(CleanNumber([Customer.Phone]));

// Validate digit count before using
if Length(CleanNumber([Customer.Phone])) = 10 then
  Result := FormatPhone(CleanNumber([Customer.Phone]))
else
  Result := '(invalid)';

---

CleanPrintable

Removes non-printable control characters from a string. Useful when data imported from external sources contains hidden characters that can cause display or export problems.

CleanPrintable(S: String): String

Parameter	Type	Description
S	String	The string to clean

// Clean a notes field that may contain embedded control characters
Result := CleanPrintable([Orders.Notes]);

// Clean before exporting to CSV or fixed-width format
Result := CleanPrintable([Item.Description]);

// Combine with Trim for thorough cleaning
Result := Trim(CleanPrintable([Customer.Comments]));

---

Coalesce

Returns the first non-null, non-empty value from two options. If A has a value, A is returned; otherwise B is returned. Useful for providing fallback values when a field may be blank.

Coalesce(A, B: Variant): Variant

Parameter	Type	Description
A	Variant	The preferred value — returned if not null or empty
B	Variant	The fallback value — returned if A is null or empty

// Use a billing address if shipping address is blank
Result := Coalesce([Customer.ShipAddress], [Customer.BillAddress]);

// Fall back to company name if contact name is missing
Result := Coalesce([Customer.ContactName], [Customer.CompanyName]);

// Provide a default label when a field has no value
Result := Coalesce([Item.Category], 'Uncategorised');

---

CountryNormalize

Normalises a country string to a consistent form. Handles abbreviations, alternate spellings, and mixed case. See also NormalizeCountry in Formatting Functions.

CountryNormalize(S: String): String

Parameter	Type	Description
S	String	The country value to normalise

Result := CountryNormalize([Customer.Country]);
// 'usa', 'US', 'U.S.A.' all return 'United States'

---

DateTimeToStr

Converts a date and time value to a string using the system’s default date and time format. For a specific format, use FormatDateTime instead.

DateTimeToStr(E: Extended): String

Parameter	Type	Description
E	Extended	The date/time value to convert

Result := DateTimeToStr(Now);
// Returns current date and time as a string, e.g. '3/15/2024 2:30:00 PM'

Result := 'Printed: ' + DateTimeToStr(Now);

---

DateToStr

Converts a date value to a string using the system’s default short date format. For a specific format use FormatDateTime.

DateToStr(E: Extended): String

Parameter	Type	Description
E	Extended	The date value to convert

Result := DateToStr([Orders.OrderDate]);
// Returns: '3/15/2024'

// Quick date stamp in a report header
Result := 'As of: ' + DateToStr(Date);

---

DefaultIfEmpty

Returns a default string if the input string is empty or null. A simpler alternative to Coalesce when both values are strings.

DefaultIfEmpty(S, Default: String): String

Parameter	Type	Description
S	String	The string to check
Default	String	The value to return if S is empty

Result := DefaultIfEmpty([Customer.Email], '(no email)');

Result := DefaultIfEmpty([Item.Notes], 'No additional notes');

// Use to avoid blank cells in a grid column
Result := DefaultIfEmpty(TrimSafe([Orders.PONumber]), 'N/A');

---

DS_YesNo

Returns Yes or No for an integer value where 0 = No and 1 = Yes.

DS_YesNo(I: Integer): String

Parameter	Type	Description
I	Integer	0 returns ‘No’, 1 returns ‘Yes’

Result := DS_YesNo([Item.Taxable]);
// 0 returns 'No', 1 returns 'Yes'

Result := DS_YesNo([Customer.Active]);

---

FloatToStr

Converts a floating point number to a string using the system’s default numeric format. For controlled decimal places or thousands separators, use FormatFloat instead.

FloatToStr(E: Extended): String

Parameter	Type	Description
E	Extended	The float value to convert

Result := FloatToStr([Item.Weight]);
// Returns: '12.5'

// Combine with other text
Result := 'Weight: ' + FloatToStr([Item.Weight]) + ' lbs';

---

IIF

Inline if — returns one of two values based on a condition. Equivalent to writing a full if/then/else block but usable in a single expression.

IIF(Condition: Boolean; TrueValue, FalseValue: Variant): Variant

Parameter	Type	Description
Condition	Boolean	The condition to evaluate
TrueValue	Variant	Value returned when the condition is true
FalseValue	Variant	Value returned when the condition is false

// Simple true/false label
Result := IIF([Orders.IsRush], 'Rush', 'Standard');

// Use directly in an inline text expression
// [IIF([Customer.Balance] > 0, 'Balance Due', 'Paid')]

// Nested IIF for multiple conditions
Result := IIF([Orders.Total] > 1000, 'Large',
          IIF([Orders.Total] > 500,  'Medium', 'Small'));

---

IntToStr

Converts an integer value to its string representation.

IntToStr(I: Integer): String

Parameter	Type	Description
I	Integer	The integer value to convert

Result := IntToStr([Orders.OrderNumber]);
// Returns: '1234'

// Zero-pad an order number for display
Result := PadLeft(IntToStr([Orders.OrderNumber]), 6, '0');
// Returns: '001234'

// Build a label
Result := 'Item ' + IntToStr([LineItem.LineNumber]) + ' of ' +
          IntToStr([LineItem.TotalLines]);

---

IsNull

Returns True if a variant value is Null or empty. Use this to check for missing data before processing a field.

IsNull(V: Variant): Boolean

Parameter	Type	Description
V	Variant	The value to check

if IsNull([Customer.Email]) then
  Result := '(no email on file)'
else
  Result := [Customer.Email];

// Guard before a calculation
if not IsNull([Orders.DiscountRate]) then
  Result := FormatCurrencySafe([Orders.Total] * [Orders.DiscountRate]);

// Use in inline expressions
// [IIF(IsNull([Employee.TermDate]), 'Active', 'Terminated')]

---

MaskEmail

Masks an email address for privacy, revealing only the first character and the domain. For example, john.smith@example.com becomes j***@example.com.

MaskEmail(S: String): String

Parameter	Type	Description
S	String	The email address to mask

Result := MaskEmail([Customer.Email]);
// 'john.smith@example.com' becomes 'j***@example.com'

// Use on reports shared outside the organisation
Result := MaskEmail([Employee.Email]);

---

MaskName

Masks a person’s name for privacy, showing only the first character of each part.

MaskName(S: String): String

Parameter	Type	Description
S	String	The name to mask

Result := MaskName([Employee.FullName]);
// 'John Smith' becomes 'J*** S***'

Result := MaskName([Customer.ContactName]);

---

MaskPhone

Masks a phone number for privacy, showing only the last 4 digits.

MaskPhone(S: String): String

Parameter	Type	Description
S	String	The phone number to mask

Result := MaskPhone([Customer.Phone]);
// '5551234567' becomes '***-***-4567'

Result := MaskPhone([Employee.Phone]);

---

MaskSSN

Masks a Social Security Number for privacy, showing only the last 4 digits in the form ***-**-1234.

MaskSSN(S: String): String

Parameter	Type	Description
S	String	The SSN to mask

Result := MaskSSN([Employee.SSN]);
// '123456789' becomes '***-**-6789'

---

NullToBlank

Converts a Null or empty variant value to a blank string. Useful for ensuring a field always returns a string rather than Null, which can cause display issues in text objects.

NullToBlank(V: Variant): String

Parameter	Type	Description
V	Variant	The value to convert

Result := NullToBlank([Customer.Address2]);
// Returns '' instead of NULL

// Safe concatenation without null errors
Result := NullToBlank([Customer.Address1]) + ' ' +
          NullToBlank([Customer.Address2]);

// Use in a text object where null would show as an error
// [NullToBlank([Orders.PONumber])]

---

NumberToWords_Check

Converts a numeric dollar amount to its written check wording. Used for printing the written amount line on cheques.

NumberToWords_Check(Value: Double): String

Parameter	Type	Description
Value	Double	The dollar amount to convert

Result := NumberToWords_Check([Check.Amount]);
// 1250.75 returns 'One Thousand Two Hundred Fifty and 75/100'

// Typical use on a cheque report
Result := NumberToWords_Check([Payroll.NetPay]) + ' Dollars';

---

Pluralize

Returns the singular or plural form of a word based on a count value.

Pluralize(Count: Integer; Singular, Plural: String): String

Parameter	Type	Description
Count	Integer	The count that determines singular or plural
Singular	String	The singular form of the word
Plural	String	The plural form of the word

Result := IntToStr([Orders.ItemCount]) + ' ' +
          Pluralize([Orders.ItemCount], 'item', 'items');
// 1 returns '1 item', 3 returns '3 items'

Result := IntToStr([Invoice.PageCount]) + ' ' +
          Pluralize([Invoice.PageCount], 'page', 'pages');

Result := 'You have ' + IntToStr([Customer.OpenOrders]) + ' open ' +
          Pluralize([Customer.OpenOrders], 'order', 'orders');

---

ProperCase

Converts a string to proper case, capitalising the first letter of each word and lowercasing the rest. See also NameCase in String Functions, which does the same thing.

ProperCase(S: String): String

Parameter	Type	Description
S	String	The string to convert

Result := ProperCase('ACME MANUFACTURING CO');
// Returns: 'Acme Manufacturing Co'

Result := ProperCase([Customer.Name]);

// For best results with all-caps data, lowercase first
Result := ProperCase(Lowercase([Customer.Name]));

---

RemoveQuotations

Removes quotation marks from inside a string. Useful when data fields contain embedded quotes that should not appear in printed output.

RemoveQuotations(S: String): String

Parameter	Type	Description
S	String	The string to process

Result := RemoveQuotations([Item.Description]);
// '"Widget" Model A' becomes 'Widget Model A'

Result := RemoveQuotations([Orders.Notes]);

---

RepeatText

Repeats a string a specified number of times. Useful for building separator lines or simple patterns.

RepeatText(S: String; Count: Integer): String

Parameter	Type	Description
S	String	The string to repeat
Count	Integer	Number of times to repeat it

Result := RepeatText('-', 40);
// Returns: '----------------------------------------'

Result := RepeatText('* ', 5);
// Returns: '* * * * * '

// Build a separator scaled to a report width
Result := RepeatText('=', 60);

---

SafeConcat

Concatenates two strings with smart spacing — if either value is empty, no extra space is added. Useful for combining name parts or address fields where some components may be blank.

SafeConcat(A, B: String): String

Parameter	Type	Description
A	String	The first string
B	String	The second string

// Join first and last name — no double space if either is blank
Result := SafeConcat([Customer.FirstName], [Customer.LastName]);
// 'John' + 'Smith' = 'John Smith'
// 'John' + ''      = 'John'  (no trailing space)

// Build an address line safely
Result := SafeConcat([Customer.Address1], [Customer.Address2]);

---

StateAbbrevToName

Converts a 2-letter US state abbreviation to the full state name.

StateAbbrevToName(S: String): String

Parameter	Type	Description
S	String	A 2-letter state abbreviation

Result := StateAbbrevToName('FL');
// Returns: 'Florida'

Result := StateAbbrevToName([Customer.State]);
// Use on reports where the full state name is required

---

StateNameToAbbrev

Converts a full US state name to its 2-letter abbreviation.

StateNameToAbbrev(S: String): String

Parameter	Type	Description
S	String	The full state name

Result := StateNameToAbbrev('Florida');
// Returns: 'FL'

Result := StateNameToAbbrev([Customer.State]);
// Useful when state is stored as full name but abbreviation is needed

---

StrToDate

Converts a string to a date value using the system’s default date format. Raises an error if the string cannot be parsed as a date.

StrToDate(S: String): Extended

Parameter	Type	Description
S	String	A date string in the system’s default date format

var d := StrToDate('03/15/2024');

// Compare a string date to today
if StrToDate([Param.StartDate]) > Date then
  Result := 'Future date'
else
  Result := 'Past or present';

---

StrToDateTime

Converts a string to a date and time value.

StrToDateTime(S: String): Extended

Parameter	Type	Description
S	String	A date/time string in the system’s default format

var dt := StrToDateTime('03/15/2024 14:30:00');

// Calculate elapsed time from a stored string timestamp
var elapsed := Now - StrToDateTime([Log.Timestamp]);

---

StrToFloat

Converts a string to a floating point number. Raises an error if the string is not a valid number. Use VarToIntDef or check with ValidFloat first if the value may be invalid.

StrToFloat(S: String): Extended

Parameter	Type	Description
S	String	A string representing a numeric value

var rate := StrToFloat([Param.Rate]);
Result := FormatCurrencySafe([Orders.Total] * rate);

// Guard with ValidFloat before converting
if ValidFloat([Param.Multiplier]) then
  Result := FloatToStr(StrToFloat([Param.Multiplier]) * [Item.Price])
else
  Result := 'Invalid rate';

---

StrToInt

Converts a string to an integer. Raises an error if the string is not a valid integer.

StrToInt(S: String): Integer

Parameter	Type	Description
S	String	A string representing an integer value

var qty := StrToInt([Param.Quantity]);

// Guard with ValidInt first
if ValidInt([Param.PageSize]) then
  var pageSize := StrToInt([Param.PageSize])
else
  var pageSize := 25;

---

StrToTime

Converts a string to a time value using the system’s default time format.

StrToTime(S: String): Extended

Parameter	Type	Description
S	String	A time string in the system’s default time format

var t := StrToTime('14:30:00');

// Check if a shift start time is before noon
if StrToTime([Employee.ShiftStart]) < StrToTime('12:00:00') then
  Result := 'Morning shift'
else
  Result := 'Afternoon shift';

---

StringMap

Maps a value to a replacement by looking it up in a comma-separated from-list and returning the corresponding entry from a to-list. Useful for translating codes to descriptions without writing multiple if statements.

StringMap(Value: Variant; FromList: Variant; ToList: Variant): Variant

Parameter	Type	Description
Value	Variant	The value to look up
FromList	Variant	Comma-separated list of source values
ToList	Variant	Comma-separated list of replacement values

// Map a single-letter status code to a description
Result := StringMap([Orders.Status], 'O,P,S,C', 'Open,Processing,Shipped,Closed');
// 'O' returns 'Open', 'S' returns 'Shipped'

// Map a department code to a full name
Result := StringMap([Employee.Dept], 'HR,IT,FN,MK', 'Human Resources,Information Technology,Finance,Marketing');

// Map a priority number to a label
Result := StringMap([Orders.Priority], '1,2,3', 'High,Medium,Low');

---

TimeToStr

Converts a time value to a string using the system’s default time format.

TimeToStr(E: Extended): String

Parameter	Type	Description
E	Extended	The time value to convert

Result := TimeToStr(Time);
// Returns current time, e.g. '2:30:00 PM'

Result := 'Generated at: ' + TimeToStr(Time);

---

VarToIntDef

Converts a variant to an integer, returning a default value if the conversion fails or the value is Null. Safer than StrToInt when the value may be missing or non-numeric.

VarToIntDef(V: Variant; Default: Integer): Integer

Parameter	Type	Description
V	Variant	The variant value to convert
Default	Integer	Value returned if conversion fails

// Safely convert a parameter that might be blank
var qty := VarToIntDef([Param.Quantity], 1);

// Use 0 as default for a nullable count field
var count := VarToIntDef([Customer.OrderCount], 0);
Result := IntToStr(count) + ' orders';

// Provide a sensible default page size if the parameter is missing
var pageSize := VarToIntDef([Param.PageSize], 25);

---

VarToStr

Converts any variant value to a string. Returns an empty string for Null values rather than raising an error. A safe general-purpose way to get a string from any field.

VarToStr(V: Variant): String

Parameter	Type	Description
V	Variant	The variant value to convert to a string

// Safely convert any field to string without null errors
Result := VarToStr([Customer.Notes]);

// Use before string operations on a variant field
if Length(VarToStr([Orders.PONumber])) > 0 then
  Result := 'PO: ' + VarToStr([Orders.PONumber])
else
  Result := 'No PO';

---

YesNo

Returns Yes or No for any variant value that can be evaluated as a boolean.

YesNo(V: Variant): String

Parameter	Type	Description
V	Variant	The value to evaluate

Result := YesNo([Customer.TaxExempt]);
// Returns 'Yes' or 'No'

Result := YesNo([Item.Discontinued]);

// Use in an inline text expression
// [YesNo([Orders.IsRush])]