blob: da96bfe49ac49c1b5c23f08e81ad27646fe9ae13 [file] [log] [blame]
Zesstrad59c3892019-11-28 20:53:39 +01001SYNOPSIS
2 int sscanf(string str, string fmt, mixed var1, mixed var2, ...)
MG Mud User88f12472016-06-24 23:31:02 +02003
Zesstra715ec202025-07-09 22:18:31 +02004DESCRIPTION
5 Parse a string str using the format fmt. fmt can contain
6 strings seperated by %d and %s. Every %d and %s corresponds to
7 one of var1, var2, ... .
MG Mud User88f12472016-06-24 23:31:02 +02008
Zesstra715ec202025-07-09 22:18:31 +02009 The match operators in the format string have one of these
10 formats:
11 %[+][!|~][<size>[.<minmatch>]]<type>
MG Mud User88f12472016-06-24 23:31:02 +020012
Zesstra715ec202025-07-09 22:18:31 +020013 <type> may be:
14 d: matches any number.
15 D: matches any number.
16 U: matches any unsigned number.
17 s: matches any string.
18 %: matches the % character.
19 t: matches whitespace (spaces and tab characters), but does
20 not store them (the simple ' ' matches just spaces and
21 can't be given a size specification).
MG Mud User88f12472016-06-24 23:31:02 +020022
Zesstra715ec202025-07-09 22:18:31 +020023 <size> is the expected field size, <minmatch> the demanded
24 minimal match length (defaults are 0 for strings and 1 for
25 numbers). Each of these both may be specified numerically, or
26 as '*' - then the value of the variable at the current place
27 in the argument list is used.
MG Mud User88f12472016-06-24 23:31:02 +020028
Zesstra715ec202025-07-09 22:18:31 +020029 Specifying + will require that the characters after the field
30 match as well, or the match will be deemed unsuccessful (the variable
31 might still get assigned, though).
MG Mud User88f12472016-06-24 23:31:02 +020032
Zesstra715ec202025-07-09 22:18:31 +020033 Specifying ! will perform the match, but neither store the
34 result nor count the match.
MG Mud User88f12472016-06-24 23:31:02 +020035
Zesstra715ec202025-07-09 22:18:31 +020036 Specifying ~ will perform and count the match, but not store
37 the result.
MG Mud User88f12472016-06-24 23:31:02 +020038
Zesstra715ec202025-07-09 22:18:31 +020039 If the %s specifier is not at the end of the format string,
40 it is matched only if the following character(s) or format
41 is found, too. See below for an example.
MG Mud User88f12472016-06-24 23:31:02 +020042
Zesstra715ec202025-07-09 22:18:31 +020043 The difference between %d and %D/%U is that the latter will abort
44 an immediately preceeding %s as soon as possible, whereas the
45 former will attempt to make largest match to %s first.
46 %D/%U will still not skip whitespace, use %.0t%D to skip optional
47 whitespace.
MG Mud User88f12472016-06-24 23:31:02 +020048
Zesstra715ec202025-07-09 22:18:31 +020049 If a number is matched that exceeds the numerical limits of
50 integers the match is deemed unsuccessful.
Zesstra5481d492021-04-08 20:07:06 +020051
Zesstra715ec202025-07-09 22:18:31 +020052 The number of matched arguments will be returned.
MG Mud User88f12472016-06-24 23:31:02 +020053
Zesstra715ec202025-07-09 22:18:31 +020054 The function sscanf is special, in that arguments are passed
55 by reference automatically.
MG Mud User88f12472016-06-24 23:31:02 +020056
Zesstra715ec202025-07-09 22:18:31 +020057EXAMPLES
Zesstrad59c3892019-11-28 20:53:39 +010058 string who, what;
Zesstra715ec202025-07-09 22:18:31 +020059 if (sscanf("throw frisbee to rover",
60 "throw %s to %s", what, who) != 2)
61 write("Usage: throw <what> to <who>\n");
62 else
63 write("You throw a "+what+" to "+who+" to get his attention.\n");
MG Mud User88f12472016-06-24 23:31:02 +020064
Zesstrad59c3892019-11-28 20:53:39 +010065 sscanf("ab", "%s%s", who, what)
Zesstra715ec202025-07-09 22:18:31 +020066 ==> result 2, who = "", what = "ab"
MG Mud User88f12472016-06-24 23:31:02 +020067
Zesstrad59c3892019-11-28 20:53:39 +010068 sscanf("ab", "%s %s", who, what)
Zesstra715ec202025-07-09 22:18:31 +020069 ==> result 0, who = 0, what = 0
MG Mud User88f12472016-06-24 23:31:02 +020070
Zesstrad59c3892019-11-28 20:53:39 +010071 sscanf("ab ", "%s %s", who, what)
Zesstra715ec202025-07-09 22:18:31 +020072 ==> result 2, who = "ab", what = ""
MG Mud User88f12472016-06-24 23:31:02 +020073
Zesstra715ec202025-07-09 22:18:31 +020074HISTORY
75 LDMud 3.3.713/3.2.13 introduced the '+' specifier.
MG Mud User88f12472016-06-24 23:31:02 +020076
Zesstra715ec202025-07-09 22:18:31 +020077SEE ALSO
MG Mud User88f12472016-06-24 23:31:02 +020078 explode(E), regexp(E)