format

Gamma: Version 4.0
Prev |  | Next

# `format`

`format` -- generates a formatted string.

## Syntax

    format (format_string, arguments?...)

## Arguments

`format_string`

  A string containing format directives and literal text.

`arguments`

  Expressions which will be matched to format directives on a one-to-one basis.

## Returns

A string.

## Description

Generates a formatted string using directives similar to those used in the "C" `printf` function. Text in the `format_string` will be output literally to the formatted string. Format directives consist of a percent sign (%) followed by one or more characters. The following directives are supported:

- a Any Gamma or Lisp expression. The `princ_name` (the same result as applying the string function on the expression) of a Lisp expression is written to the result string.

- d An integer number. A numeric expression is cast to a long integer and written to the result string. %d is equivalent to %ld.

- f A floating point number. A numeric expression is cast to a long floating point number and written to the result string.

- g A floating point number in "natural" notation. A numeric expression is cast to a long floating point number and written to the result string using the most easily read notation which will fit into the given field size, if any. If no field size is specified, use a notation which minimizes the number of characters in the result.

- s A character string. A string is written to the result string.

The format directive may contain control flags between the % sign and the format type character. These control flags are:

- - Left justify the field within a specified field size.

- + Numbers with a positive value will begin with a + sign. Normally only negative numbers are signed.

- " " (A space). Signed positive numbers will always start with a space where the sign would normally be.

- 0 A numeric field will be filled with zeros to make the number consume the entire field width.

Format directives may contain field width specifiers which consist of an optional minimal field width as an integer, optionally followed by a period and a precision specified as an integer. The precision has different meanings depending on the type of the field.

- a The field width option does not apply to this general case. To specify precision on a s_exp, you can convert it to a string and use the `s` format directives.

- d The precision specifies the minimum number of digits to appear. Leading zeros will be used to make the necessary precision.

- f The precision specifies the number of digits to be presented after the decimal point. If the precision is zero, the decimal point is not shown.

- g The precision specifies the maximum number of significant digits to appear.

- s The precision specifies the maximum number of characters to appear.

## Example

        Gamma> pi = 3.1415926535;
        3.1415926535000000541
        Gamma> format("PI is %6.3f",pi);
        "PI is  3.142"
        Gamma> alpha = "abcdefghijklmnopqrstuvwxyz";
        "abcdefghijklmnopqrstuvwxyz"
        Gamma> format("Alphabet starts: %.10s",alpha);
        "Alphabet starts: abcdefghij"
        Gamma> x = [1,2,3,4,5,6,7,8,9];
        [1 2 3 4 5 6 7 8 9]
        Gamma> format("x is: %a",x);
        "x is: [1 2 3 4 5 6 7 8 9]"
        Gamma> format("x is: %.6s",string(x));
        "x is: [1 2 3"
        Gamma>

Prev | Home | Next
`buffer_to_string` | Up | `make_buffer`

Copyright 1995-2002 by Cogent Real-Time Systems, Inc.