Introduction

printf syntax is a universally recognized method of formatted strings. This module attempts to implement the most-used conversion specifications.

Requirements

The Format module requires the RegExModule. You can get it from the Downloads section.

A Quick Guide to the Syntax

The format string can contain both ordinary text and conversion specifications.

A conversion specification begins with a % and ends with a particular conversion specifier (see below). In between, and in the following order, there may be zero or more flags, an optional field width, and an optional precision.

Flags

The % character is followed by zero or more flags :

Field width

An optional number specifying a minimum field width.

If the converted value has fewer characters than the field width, it will be padded with spaces on the left (or right, if the left-justify flag has been given).

In no case does a non-existent or small field width cause truncation of a field; if the result of a conversion is wider than the field width, the field is expanded to contain the conversion result.

Precision

An optional precision, in the form of a period ('.') followed by an optional integer value.

If the precision is given as just '.', or the precision is negative, the precision is taken to be zero.

This gives the minimum number of digits to appear for integer (d, i, o, u, x, X) conversions, the number of digits to appear after the radix character for e, E and f conversions, or the maximum number of characters to be printed from a string for s conversions.

Conversion specifiers

Using the Formatter

You begin by creating a formatter, using the TFormatter type. The Create method takes a format String as a parameter. See the syntax guide below for formatting details.

Local formatter:TFormatter = TFormatter.Create("VAT = %2.1f%%")

Each conversion specification expects an argument (with the exception of %n and %%), to which you must supply an appropriate value. You do this by calling one of the following methods: ByteArg, ShortArg, IntArg, LongArg, FloatArg, DoubleArg or StringArg.

formatter.FloatArg(17.5)

Since each Arg method returns the TFormatter object, it allows you to tag together a sequence of arguments, like so:

Local formatter:TFormatter = TFormatter.Create("Name = %s : Id = X%09d")
formatter.StringArg("William Smith").IntArg(65002)

The Format method formats the text using the given arguments, and returns the String result.

Print formatter.format()

To reuse a formatter, you can call the Clear method to remove the arguments, allowing you to apply some new ones without the formatting engine having to re-process the format string.

Building

See HowToInstallModules to help you get started.