Update doc/efun/ aus Driversourcen.
Manpages der efuns aktualisiert, neue Manpages hinzugefuegt.
Change-Id: I7cc91684269ff56d1aef47d5c5e7c87f7fd531dc
diff --git a/doc/efun/sprintf b/doc/efun/sprintf
index 41a7c0e..cd74317 100644
--- a/doc/efun/sprintf
+++ b/doc/efun/sprintf
@@ -1,147 +1,191 @@
SYNOPSIS
string sprintf(string fmt, ...)
-BESCHREIBUNG
- Mit dieser Funktion kann man auf einfache Weise aus dem Inhalt
- von Variablen einen String bauen; und dies effektiver als
- mit der ueblichen "Du hast "+anzahl+" Punkt(e)"-Methode.
+DESCRIPTION
+ Most of the characters in the format string (FMT) get passed
+ straight through to the output (ie: printed or put in the
+ return string), to format the arguments into the string it is
+ necessary to include an argument format string (AFS) in the
+ FMT. An AFS is a series of characters starting with a percent
+ sign "%" and terminated with a argument type specifier.
+ To include a "%" sign in the output, it is necessary to include a
+ double percent sign "%%". The sequence "%^" will output "%^" again.
- Die Funktion bekommt als erstes Argument einen Formatstring fmt,
- der Informationen darueber enthaelt, wie die weiteren beliebigen
- Argumente in den Ergebnisstring eingebaut werden sollen.
- Die meisten Zeichen gelangen vom Formatstring unveraendert in
- den Ausgabestring. Die Regeln zum Einbau eines Arguments werden
- immer mit '%' eingeleitet. Moechte man ein '%' in die Ausgabe
- bringen, so muss man im Formatstring "%%" verwenden.
+ Valid argument type specifiers are:
+ "s" : the argument is a string.
+ "d" : the argument is an integer to be included in decimal
+ representation.
+ "i" : same as "d".
+ "b" : the argument is an integer to be included in binary
+ representation.
+ "o" : the argument is an integer to be included in octal
+ representation.
+ "x" : the argument is an integer to be included in hexadecimal
+ representation.
+ "X" : as "x" except letters are capitalised.
+ "e","E","f","g","G" : the argument is a float to be included in
+ decimal representation; see examples for details
+ "c" : the argument is an int to included as a character
+ "O" : the argument is an LPC datatype to be printed in an arbituary
+ format, this is for debugging purposes.
+ If the argument is an object then the function
+ printf_obj_name() on the master object is called with the
+ object as a parameter, the string returned is included in
+ brackets at the end of object file name.
+ If 0 is returned then nothing is appended after the file name.
+ "Q" Like "O", except that special characters in strings are
+ printed in LPC notation.
- Ein einfaches Beispiel ist erg=sprintf("%s %d", str, i);
- '%' leitet einen Argumentformatstring (AFS) ein. Das 's' schliesst
- ihn ab und besagt, dass ein String eingebaut werden soll. Das
- folgende Leerzeichen wird unveraendert uebernommen. '%' leitet
- wieder einen neuen Formatstring ein, wobei 'd' eine Ganzzahl
- bezeichnet (eine Variable von Typ int).
- Dies ist ein allerdings nur ein sehr einfaches Beispiel.
+ Between the percent sign and the argument type specifier in
+ the AFS, the following modifiers can be included to specify
+ the formatting information. Order is not important unless
+ otherwise specified. "n" is used to specify a integer, which
+ can be a "*" in which case the next argument is used as the
+ number.
- Jeder Argumentformatstring kennzeichnet also, auf welche Art
- ein Argument in das Ergebnis eingebaut werden soll. Der erste
- AFS ist fuer das zweite Argument der Funktion, der zweite AFS
- fuer das dritte Argument u.s.w. (das erste Argument der Funktion
- ist ja der Formatstring selbst).
+ Modifiers:
+ n specifies the field size. If the size is prepended with
+ a 0, the argument is printed with leading zeroes.
+ "."n specifies the precision, for simple (not columns or tables)
+ strings specifies the truncation length.
+ ":"n n specifies both the field size _and_ the presision, if n is
+ prepended by a zero then the pad string is set to "0".
+ "'X'" the pad string is set to the char(s) between the single
+ quotes, if the field size is also prepended with a zero then
+ which ever is specified last will overrule.
+ NOTE: to include "'" in the pad string, you must use "\\'"
+ (as the backslash has to be escaped past the interpreter),
+ similarly, to include "\" requires "\\\\".
+ " " pad positive integers with a space.
+ "+" pad positive integers with a plus sign.
+ "-" left aligned within field size.
+ NB: std (s)printf() defaults to right alignment, which is
+ unnatural in the context of a mainly string based language
+ but has been retained for "compatibility" ;)
+ "|" centered within field size.
+ "$" justified to field size. Ignored unless the type specifier
+ is 's'.
+ "=" column mode. Ignored unless the argument type specifier is 's'.
+ Field size must be specified, if precision is specified then
+ it specifies the width for the string to be wordwrapped in, if
+ not then the field size is. The field size specifies the width
+ of the column and has the effect that the last line of the
+ column is padded with spaces to achieve this length.
+ "#" For strings: table mode.
+ Field size must be specified, if precision is
+ specified then it specifies the number of columns in
+ the table, otherwise the number is "optimally"
+ generated (as few lines and columns as possible).
+ Table mode is passed a list of backslash-n separated
+ 'words' which are put in a format similar to that of
+ ls.
+ For %O/%Q: compact output.
+ "@" the argument is an array. the corresponding AFS (minus all
+ "@") is applied to each element of the array.
- Jeder AFS beginnt mit einem '%' und endet mit einem der
- folgenden Zeichen (Argumenttyp-Kennzeichner):
- Zeichen Argumenttyp Bemerkung
- 's' string
- 'c' integer als ASCII-Zeichen
- 'd' 'i' integer Dezimalschreibweise
- 'o' integer Oktalschreibweise
- 'b' 'B' integer Binaerschreibweise
- 'x' 'X' integer Hexadezimalschreibweise
- 'e' 'E' float Exponentialschreibweise
- 'f' 'F' float Gleitkommadarstellung
- 'g' 'G' float Gleitkommadarstellung
- 'O' mixed Gibt fuer Debugging alles irgendwie
- lesbar aus, auch Arrays und Mappings
- 'Q' mixed Wie 'O', gibt jedoch Sonderzeichen in
- Strings in der LPC-Notation aus
-
- Zwischen dem '%' und dem Argumenttyp-Kennzeichner kann man
- noch mehrere Modifikatoren setzen, die das Verhalten
- beeinflussen.
- Hier eine Uebersicht. n steht hier fuer eine Ganzzahl, also
- zum Beispiel "12".
- Modifikator Bedeutung
- n Minimale Stringlaenge, die fuer dieses Argument
- verwendet werden soll. Fehlende Zeichen werden mit
- einem Fuellzeichen aufgefuellt. Beginnt n mit einer
- '0' (etwa "08") so ist das Fuellzeichen '0' sonst
- ist es per Default ' '. (sogenannte 'Feldbreite')
- .n Bei Ganzzahlen die Maxanzahl der Stellen, bei Gleit-
- kommazahlen die Maximalzahl der Nachkommastellen.
- Bei (einfachen) Strings die Maximallaenge.
- :n Ist dasselbe wie n.n - setzt also beide Werte auf
- dieselbe Zahl.
- 'X' Als Fuellzeichen wird X genutzt. X koennen dabei
- auch mehrere Zeichen sein, etwa fuehrt '-=' zu
- Fuellungen der Art "-=-=-=-=". Um mit Hochkommas
- zu fuellen ist '\\'' anzugeben. Rueckwaerts-
- schraegstrich entsprechend mit '\\\\'.
- <Space> Vor positive Zahlen wird ein Leerzeichen gefuegt.
- + Vor positive Zahlen wird ein '+' gefuegt.
- - Der Wert wird linksbuendig in das fuer dieses Argument
- vorgesehene Feld eingefuegt (Standard ist rechts-
- buendig). Bei Strings wird meistens diese Ausrichtung
- die sinnvollste sein.
- | Der Wert wird zentriert in das Feld eingefuegt.
- (Siehe Modifikator n, Feldbreite)
- $ Blocksatz. Benoetigt eine Feldbreite, funktioniert nur
- bei Strings (auch im Spaltenmodus).
- = Spaltenmodus (siehe unten).
- # Fuer Strings: Tabellenmodus (siehe unten).
- Fuer '%O'/'%Q': kompakte Ausgabe.
- @ Arraymodus (siehe unten).
- * Ein Stern kann immer dort eingesetzt werden, wo
- hier weiter oben ein n fuer eine Ganzzahl steht.
- Der Wert der Zahl muss dann als weiterer Parameter
- an die Funktion uebergeben werden.
+ When the formatting of an element results in several output lines
+ (column or table mode) and no explicit pad strings has been
+ defined, then the efun removes any padding whitespace before
+ the newlines of all but the last line. However, if an explicit
+ pad string has been given, even if it is the simple ' ', then
+ the padding will not be removed.
-BEISPIELE
- Mit den bis jetzt erwaehnten Moeglichkeiten kann man zB machen:
- sprintf("%d (dec) == %o (octal) == %x (hex)", 20, 20, 20);
- => "20 (dec) == 24 (octal) == 14 (hex)"
+EXAMPLES
+ sprintf("decimal=%d, octal=%o, hexadecimal=%x\n", 7, 7, 7);
- sprintf("Du drehst den Knopf um %.3f Umdrehungen", 12.3456);
- => "Du drehst den Knopf um 12.345 Umdrehungen"
+ sprintf("array=%O\n", ({1, 2, 3}));
+ this will return the following:
+ ({ /* sizeof() == 3 */
+ 1,
+ 2,
+ 3
+ })
+ An array will be printed recursively and each element of the
+ array will be indented. Can also be used as a debugging tool.
- sprintf("Du liest %|'*':9s", "Fiona");
- => "Du liest **Fiona**"
+ sprintf("%-*#s\n", 80, implode(get_dir("~/."), "\n"));
- sprintf("Auf dem Zettelstueck steht: %-.*s...", 7, "Hallo Du da");
- => "Auf dem Zettelstueck steht: Hallo D...
+ sprintf("foo") // returns "foo"
-ERWEITERTE MODI
- Mit dem Modifikatoren = # und @ stehen maechtige Werkzeuge zur
- Verfuegung. Mit ein wenig Ueberlegung kann man sich oft viele
- Zeilen Code ersparen.
- Arraymodus (@):
- sprintf("%@s", arr_of_string);
- Der Argumentformatstring (allerdings ohne das @) wird sooft
- hintereinandergereiht, wieviele Elemente das Array hat.
- Jeder AFS wird dann fuer ein Element des Arrays benutzt.
- sprintf("%@s", ({"aaa","bbb"})) ist somit dasselbe wie
- sprintf("%s%s", "aaa", "bbb"). Allerdings passt es sich
- immer an die Elementzahl der uebergebenden Arrays an.
- Dies ist nuetzlich um Ergebnisse von map() oder aehnlich
- auszugeben.
- sprintf("%@s", map_objects(all_inventory(), "short"));
- Der Argumenttyp-Kennzeichner muss hierbei immer dem Typen
- eines Elementes des Arrays entsprechen.
- Spaltenmodus (=):
- Diese Funktion bricht Text um. Die Feldbreite muss angegeben
- werden. Wird neben der Feldbreite auch eine maximale String-
- laenge angegeben, so wird die letztere fuer die Breite des
- Umbrechens verwendet, die Feldbreite wird mit Fuellzeichen
- aufgefuellt.
- sprintf("%=-20s", str); bricht den String str 'wordwrap'end
- auf 20 Zeichen Laenge um. sprintf("%=-*s", len, str);
- ist schon eine einfache break_string() Variante.
- Tabellenmodus (#):
- Diese Funktion gibt Strings tabellenartig aus. Die Teilstrings
- muessen mit \n getrennt als ein String als Argument uebergeben
- werden. Die Feldbreite muss angegeben werden und bezeichnet
- die (maximale) Gesamtbreite der Tabelle.
- Die Anzahl der Spalten der Tabelle wird moeglichst optimal
- bestimmt, und ist fuer alle Spalten gleich. Wird ein
- Wert als 'Praezision' angegeben, so ist dies die Anzahl von
- Spalten, die verwendet werden soll.
- sprintf("%#30.4s", str) erzeugt eine Tabelle, die maximal
- 30 Zeichen breit ist und 4 Spalten enthaelt.
- sprintf("%#30s", str) legt die Spaltenzahl dynamisch anhand
- der Einzelstringlaengen fest, so dass der laengste String
- noch genau in die Tabelle passt.
- Wenn string* worte die in die Tabelle einzubettenden Worte
- enthaelt, so muss str=implode(worte,"\n") sein.
+ sprintf("%s","foo") // returns "foo"
+ sprintf("%7s","foo") // returns " foo"
+ sprintf("%-7s","foo") // returns "foo "
+ sprintf("%|7s","foo") // returns " foo "
+ sprintf("%7'.'s","foo") // returns "....foo"
+ sprintf("%-7'+-'s","foo") // returns "foo+-+-"
+ sprintf("%|9'-+'s","foo") // returns "-+-foo-+-"
+ sprintf("%3s","foobarbloh") // returns "foobarbloh"
+ sprintf("%3.6s","foobarbloh") // returns "foobar"
+ sprintf("%6.3s","foobarbloh") // returns " foo"
+ sprintf("%:6s","foobarbloh") // returns "foobar"
+ sprintf("%:3s","foobarbloh") // returns "foo"
+ sprintf("%*.*s",-7,2,"foobarbloh") // returns "fo "
-SIEHE AUCH
- printf(E)
+ sprintf("%=12s","this is a very long sentence\n")
+ // returns " this is a\n"
+ // " very long\n"
+ // " sentence\n"
+ sprintf("%=-12s","this is a very long sentence\n")
+ // returns "this is a\n"
+ // "very long\n"
+ // "sentence\n"
+ sprintf("%=|12s","this is a very long sentence\n")
+ // returns " this is a\n"
+ // " very long\n"
+ // " sentence\n"
+ sprintf("%=10.6s","this is a very long sentence\n")
+ // returns " this\n"
+ // " is a\n"
+ // " very\n"
+ // " long\n"
+ // " senten\n"
+ // " ce\n"
+ sprintf("%#-40.3s\n",
+ "one\ntwo\nthree\nfour\nfive\nsix\nseven\neight\nnine\nten\n")
+ // returns "one five nine\n"
+ // "two six ten\n"
+ // "three seven \n"
+ // "four eight \n"
+ sprintf("%#-40s\n",
+ "one\ntwo\nthree\nfour\nfive\nsix\nseven\neight\nnine\nten\n")
+ // returns "one three five seven nine\n"
+ // "two four six eight ten\n"
+
+ sprintf("%@-5s",({"foo","bar","bloh"})) // returns "foo bar bloh "
+
+ sprintf("%d",123) // returns "123"
+ sprintf("%7d",123) // returns " 123"
+ sprintf("%-7d",123) // returns "123 "
+ sprintf("%d/%d",123,-123) // returns "123/-123"
+ sprintf("% d/% d",123,-123) // returns " 123/-123"
+ sprintf("%+d/%+d",123,-123) // returns "+123/-123"
+ sprintf("%+5d/%5d",123,123) // returns " +123/ 123"
+ sprintf("%|6d",123) // returns " 123 "
+ sprintf("%|10d",123) // returns " 123 "
+ sprintf("%|10d%3s",123,"foo") // returns " 123 foo"
+
+ sprintf("%o",16) // returns "20"
+ sprintf("%'0'3o",8) // returns "010"
+
+ sprintf("%x",123) // returns "7b"
+ sprintf("%X",123) // returns "7B"
+
+ sprintf("%f",123.5) // returns "124"
+ sprintf("%8.3f",123.5) // returns " 123.500"
+ sprintf("%E",123.5) // returns "1E+02"
+ sprintf("%12.4e",123.5) // returns " 1.2350e+02"
+ sprintf("%g",123.5) // returns "1e+02"
+ sprintf("%8.3G",123.5) // returns " 124"
+ sprintf("%8.6g",123.5) // returns " 123.5"
+
+HISTORY
+ LDMud 3.2.9 added the "%^" sequence for compatibility with
+ terminal_colour(), added the "%Q" sequence, clarified the meaning of
+ leading 0s in the field size modifier, clarified the interaction
+ between the padding and newlines, and added the '$' formatter for
+ justified printing of strings.
+ LDMud 3.2.10 added modifier '#' for '%O'/'%Q' and the datatype '%b'.
+
+SEE ALSO
+ printf(E), terminal_colour(E)