Vocabulary/Printf

From J Wiki
Jump to: navigation, search

Back to: Vocabulary

printf

J's version of printf is an addon, which provides:

  • printf, the verb for formatted typeout
  • sprintf, the verb behind printf, to create a formatted character list
  • cprintf to parse patterns and vsprintf to use a preparsed pattern
  • vbsprintf, a faster form when you have to format lots of data
  • qprintf, a verb for debugging, to type named variables easily

Make the printf addon available by

   require 'format/printf'

printf and sprintf

   '%d out of %d programmers use printf - a %4.1f%% rate.' printf 9;10;90
9 out of 10 programmers use printf - a 90.0% rate.

Fields, which begin with % and end with a field type character, are replaced with the formatted value of the corresponding atom of y. If the atom of y is boxed, it is opened.

The supported fields are:

Standard field types supported by printf
Field type character Type of opened y Formatting Interpretation of precision Default precision
d numeric decimal integer minimum number of digits displayed 1
u numeric unsigned decimal integer
o numeric octal integer
x numeric hex integer 0123456789abcdef
X numeric HEX integer 0123456789ABCDEF
f numeric real number (decimal fraction) Number of digits after the decimal point 6
e numeric scientific form nnemm
E numeric scientific form nnEmm
g numeric like f or e, whichever is shorter
G numeric like f or E, whichever is shorter
c character string of characters Maximum length of formatted value _
s character string of characters
J extension types
S character or list of boxes if list of boxes, the contents of the boxes are run together with a space between Maximum length of formatted value _
j any uses J's default formatting
J any like j, but flattened to a list by putting newline before each 1-cell and then raveling each 2-cell, and repeating the procedure until the result is a list, which then has a newline added at the end

Numeric contents of y may be a list, in which case the values, each formatted according to the field specification, will be run together with a space between.

The format of a field is

%[flags][width][.precision][?verb?]field-type-character

The width is the minimum number of character positions that the field will fill. The width will be extended as necessary to show all high-order digits.

The precision is interpreted according to the table above.

The flags are:

Flag Meaning
# prefix o fields with 0, x fields with 0x, X fields with 0X
- align result to be left-aligned in the field
^ center the result in the field
+ prepend '+' to result if the value is numeric and nonnegative
space prepend space to result if the value is numeric and nonnegative
0 left-fill numeric result with 0 to the end of the field

Flags may be mixed.

If a verb is specified, it is applied to the opened contents of y before formatting begins. printf and sprint apply the verb in the jprintf locale; the verb defined by vsprintf and vbsprintf apply the verb in whatever locale is is invoked from.

Special characters, and the percent character, can be represented by escape sequences:

Escape Sequences
Use to represent
%% %
\t TAB
\b BS (backspace)
\r CR (carriage return)
\f VT (vertical tab)
\' ' (single quote)
\l LF (linefeed)
\n newline (CRLF on Windows, LF on Unix)
\\ \
\nnn (where nnn is 3 octal digits) byte number nnn from a.

cprintf and vsprintf

cprintf pattern compiles the pattern to an internal form. The internal form can be used as the left argument of printf or sprintf, to save recompiling it.

Usually a better idea is to use pattern vsprintf. vsprintf is an adverb that produces a verb that can be applied to a single argument to do the formatting called for by the pattern. The verb has rank 0 is there is no more than 1 field in the pattern, rank 1 otherwise.

vbsprintf

The fastest formatting in the printf family is provided by pattern vbsprintf, which creates a verb that formats each cell of its argument and boxes the result, so that when it is applied on an array it produces an array of boxes. The verb has rank 0 is there is no more than 1 field in the pattern, rank 1 otherwise.

   fastv =: 'First name: %j, Last name: %j.\n' vbsprintf
   fastv 2 2 $ 'Ike';'Newton';'Chuck';'Gauss'
+-------------------------------------+--------------------------------------+
|First name: Ike, Last name: Newton.  |First name: Chuck, Last name: Gauss.  |
+-------------------------------------+--------------------------------------+

qprintf

qprintf does not use formatting patterns. It simply displays the values of phrases. You can stick a call to qprintf into a verb to see typeout of the progress of the verb.

   qprintf 'name1 name2 ' [ 'name1 name2'=.5 10
name1=5 name2=10
   qprintf 'vec >./vec {.vec ' [ vec =. 20 50 10
vec=20 50 10 >./vec=50 {.vec=20
   qprintf 'Time remaining: ?tr!%left: ?100*pct!ivbl!' [ 'tr pct ivbl' =. 20 0.2 5
Time remaining: 20 %left: 20 ivbl=5
   qprintf 'box1 box2 ' [ 'box1 box2' =. (<'555'),&< <'666'
box1=
+---+
|555|
+---+
 box2=
+---+
|666|
+---+

The last character of the argument is the field separator. Each occurrence of the field separator marks the end of a field and is not included in any field. The field has the form

[label?]phrase

i. e. a phrase optionally preceded by question mark (?) and a label. If the ? is omitted, the phrase itself, followed by the equals sign (=), is used for the label.

The phrase is evaluated and displayed following the label. Private variables may be used in the phrase.