Summary ^^^^^^^ .All functions **** <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <> **** .Functions by topic **** String Functions:: <>, <>, <>, <>, <>, <>, <>, <>, <> Conversion Functions:: <>, <>, <> I/O Functions:: <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <> Miscelaneous Functions:: <> Deprecated Functions:: <>, <>, <>, <>, <>, <>, <>, <> **** .String Functions **** [[library-v1:regexp]] [caption=""] .regexp ==== [listing, swiftdoc] ---- string regexp(string input, string pattern, string transform) ---- Returns a string that is constructed by replacing the first occurrence of the regular expression +pattern+ in +input+ by +transform+. The +transform+ string can contain references to capture groups in +pattern+. References are introduced using the dollar sign (+$+) and can either be named references (e.g., +${groupName}+) or positional (e.g. $1, $2, etc.). A literal dollar sign can be inserted in the replacement string by escaping it with a backslash: "\\$". ==== [[library-v1:strcat]] [caption=""] .strcat ==== [listing, swiftdoc] ---- string strcat(any... s) ---- Returns a string formed by concatenating all of the parameters. The parameters that are not already strings are converted to strings. Example: [listing, swift] ---- string result = strcat("One", "Two", 3); <1> ---- <1> +result+ is the string +"OneTwo3"+ ==== [[library-v1:strcut]] [caption=""] .strcut ==== [listing, swiftdoc] ---- string strcut(string input, string pattern) ---- Matches the regular expression in +pattern+ against +input+ and returns the first capture group that is not the full match. If the first capture group has no match in +input+, +strcut()+ returns an empty string. If +pattern+ does not define a capture group, +strcut()+ returns an error. ==== [[library-v1:strstr]] [caption=""] .strstr ==== [listing, swiftdoc] ---- int strstr(string input, string find) ---- Returns the first index in +input+ at which the string +find+ appears. If +find+ does not appear in +input+, the result is +-1+. ==== [[library-v1:strsplit]] [caption=""] .strsplit ==== [listing, swiftdoc] ---- string[] strsplit(string input, string pattern) ---- Splits +input+ around matches of the regular expression +pattern+ and returns the resulting array. If +pattern+ cannot be found in +input+, +strsplit()+ returns an array of length one containing the entire string +input+. Consecutive delimiters are not explicitly merged, but the regular expression can contain quantifiers that control this behaviour. ==== [[library-v1:strjoin]] [caption=""] .strjoin ==== [listing, swiftdoc] ---- string strjoin(any[] array, string delim) ---- Returns a string formed by concatenating all elements in +array+ with +delim+ inserted between consecutive elements of +array+. The items in +array+ are converted to strings before being concatenated. ==== [[library-v1:format]] [caption=""] .format ==== [listing, swiftdoc] ---- string format(string format, any...) ---- Formats the parameters according to +format+ which must conform to the the specification in http://docs.oracle.com/javase/7/docs/api/java/util/Formatter.html#syntax[Java string formatter] and returns the resulting string. ==== [[library-v1:pad]] [caption=""] .pad ==== [listing, swiftdoc] ---- string pad(int size, int value) ---- Returns a zero-padded string representation of +value+. The number of digits is controlled by the +size+ parameter. If the string representation of +value+ naturally contains more than +size+ characters, +pad()+ returns that representation without any padding. In other words, +pad()+ returns a string that has at least +size+ characters, but possibly more. ==== [[library-v1:sprintf]] [caption=""] .sprintf ==== [listing, swiftdoc] ---- string sprintf(string format, any...) ---- Formats the parameters according to +format+ which is a string allowing the following format specifiers: * %%: the +'%'+ character. * %M: Filename output: waits for close * %p: String representation of an arbitrary value. * %b: A +boolean+ value. * %f: A +float+ value. * %i: An +int+ value. * %s: A +string+ value. * %k: Parameter is sKipped; no output. * %q: Format an array. ==== **** .Conversion Functions **** [[library-v1:toInt]] [caption=""] .toInt ==== [listing, swiftdoc] ---- int toInt(string value) ---- Parses +value+ as a +integer+ and returns the resulting value. ==== [[library-v1:toFloat]] [caption=""] .toFloat ==== [listing, swiftdoc] ---- float toFloat(string value) ---- Parses +value+ as a floating point number and returns the resulting value. ==== [[library-v1:toString]] [caption=""] .toString ==== [listing, swiftdoc] ---- string toString(any value) ---- Returns a string representation of +value+. ==== **** .I/O Functions **** [[library-v1:readData]] [caption=""] .readData ==== [listing, swiftdoc] ---- T readData(any f) ---- Reads data from a file in a format that is a variation of the Comma-separated values format. The separator is a white space (space or tab) character. The format of the file depends on the type of value stored in it and must be as follows: + -- +int+, +float+, +boolean+:::: The file contains a value literal +string+:::: The entire contents of the file represents a string Arrays of primitive types:::: The file contains one primitive literal on each line. If the array is an array of strings, each line represents the value of the string without quotes Structures:::: The first line represents a header that must consist of the structure field names separated by white space. The second line is a data line consisting of value literals separated by white space. String value literals should be double-quoted if they contain spaces. If a string literal contains a double quote character, it must appear as a sequence of two double-quotes (e.g. +"A string with ""quotes"""+). Consecutive white space is ignored. Structure arrays:::: The first line represents a header as above. Subsequent lines represent individual items in the array and must follow the format of the data lines in simple structures. If the return type +T+ is a mapped type or if +T+ is a type that contains fields that are of a mapped type, +read()+ returns an error. -- ==== [[library-v1:readStructured]] [caption=""] .readStructured ==== [listing, swiftdoc] ---- T readStructured(any f) ---- The file is formatted as field value pairs separated by an equal sign that is optionally surrounded by whitespace. The field is the qualifying part of an <> with array keys restricted to +int+, +float+ or +string+ primitive literals. If there is no qualifying part, such as when reading a variable that is of a primitive type, the field must be the dollar sign (+$+). The allowed values are primitive literals. For example, given the following Swift program: + -- [listing, swift] ---- type struct { int a; float b; string c; boolean d; } struct[] a = read("file1.dat", format = "FieldAndValue"); int n = read("file2.dat", format = "FieldAndValue"); ---- then +file1.dat+ could consist of the following: [listing, shell] ---- [0].a = 1 [0].b = 2.3 [0].c = "Some string\n" [0].d = false ---- while +file2.dat+ could have the following contents: [listing, shell] ---- $ = 10 ---- If the return type +T+ is a mapped type or if +T+ is a type that contains fields that are of a mapped type, +read()+ returns an error. -- ==== [[library-v1:readData2]] [caption=""] .readData2 ==== [listing, swiftdoc] ---- T readData2(any f) ---- An alias to <>. ==== [[library-v1:writeData]] [caption=""] .writeData ==== [listing, swiftdoc] ---- file writeData(any value) ---- Writes the contents of +value+ into a file and returns a reference to the file. The format used by +writeData()+ matches the format accepted by <>. ==== [[library-v1:extractInt]] [caption=""] .extractInt ==== [listing, swiftdoc] ---- int extractInt(any f) ---- Reads an integer from a file. Expects +f+ to be file-valued. The file must, on the first line, contain an integer literal. Subsequent lines are ignored. ==== [[library-v1:extractFloat]] [caption=""] .extractFloat ==== [listing, swiftdoc] ---- float extractFloat(any f) ---- Reads an +float+ from a file. Expects +f+ to be file-valued. The file must, on the first line, contain a +float+ literal. Subsequent lines are ignored. ==== [[library-v1:trace]] [caption=""] .trace ==== [listing, swiftdoc] ---- trace(any... args) ---- Prints, on the console, a representation of the values of +args+ waiting for each of them to be closed. The output is prefixed by the string +"SwiftScript trace: "+. ==== [[library-v1:tracef]] [caption=""] .tracef ==== [listing, swiftdoc] ---- tracef(string format, any... args) ---- Prints, on the console, a formatted representation of +args+ waiting for each of them to be closed. The format is as described in <>. ==== [[library-v1:printf]] [caption=""] .printf ==== [listing, swiftdoc] ---- printf(any... args) ---- Like <>, except the output is not prefixed by anything. ==== [[library-v1:fprintf]] [caption=""] .fprintf ==== [listing, swiftdoc] ---- fprintf(string filename, string spec, any... args) ---- Writes a formatted set of values to a file. The arguments, +args+, are converted to a string according to +spec+ whose format is as in <>. The resulting string is appended atomically to the file with name +filename+. ==== [[library-v1:filename]] [caption=""] .filename ==== [listing, swiftdoc] ---- string filename(any f) ---- Returns the path(s) of the file(s) that +f+ is mapped to. If +f+ is a primitive value, or if +f+ is a composite type with any mapped components, +filename()+ returns an error. If +f+ is a simple file value, then +filename+ returns one path. If +f+ is a composite type with multiple file-valued fields, +filename+ returns a space separated list of the paths of all file-valued fields in +f+. The returned path(s) can either be relative to the directory from which Swift was invoked or absolute. If used in an <>, Swift guarantees that the paths point to valid files in the application's sandbox (see <>). ==== [[library-v1:filenames]] [caption=""] .filenames ==== [listing, swiftdoc] ---- string[] filenames(any f) ---- Returns the paths of the files that +f+ is mapped to. If +f+ is a primitive value, or if +f+ is a composite type with any mapped components, +filenames()+ returns an error. If +f+ is a simple file value, then the returned array has one item. The returned path(s) can either be relative to the directory from which Swift was invoked or absolute. If used in an <>, Swift guarantees that the paths point to valid files in the application's sandbox (see <>). ==== [[library-v1:dirname]] [caption=""] .dirname ==== [listing, swiftdoc] ---- string dirname(any f) ---- Like <>, except it returns the path of the directory(ies) in which the file(s) that +f+ is mapped to reside. ==== [[library-v1:arg]] [caption=""] .arg ==== [listing, swiftdoc] ---- string arg(string argName) ---- Returns the value of the command line argument +argName+. If there is no command line argument named +argName+, +arg()+ returns an error. Named arguments to a Swift program are passed on the command line after the program name (see <>) in the following format: [listing, shell] ---- swift [--=]* ---- ==== [[library-v1:arg-2]] [caption=""] .arg ==== [listing, swiftdoc] ---- string arg(string argName, string defaultValue) ---- Returns the value of the command line argument named +argName+ as above. If there is no command line argument named +name+, +arg()+ returns the value of +defaultValue+. ==== [[library-v1:args]] [caption=""] .args ==== [listing, swiftdoc] ---- string[string] args(string format) ---- Parses a Swift program's command line arguments according to +format+ and returns an array representing the name/value pairs of the arguments. The values of the arguments are validated to conform to the types in the specification, but are left as strings. The +format+ is as follows: [listing, syntax] ---- := * := | := '[' ']' := [ ] := ('-' | '/' | '_' | '0'...'9' | 'a'...'z' | 'A...Z')+ := ' ' | '=' | ':' := '<' [ ':' ] '>' := 'int' | 'string' | 'boolean' | 'float' := ---- Optional arguments without a separator and type specification are considered to be flags. If they are present on the command line, their names will appear as keys in the returned array and their value will be set to +"true"+. Arguments with a default value are considered optional (without the need to enclose them between square brackets). If they are not present on the command line, the returned array will contain their respective default values. Example: [listing, swift] ---- string[string] args = args("-min: -max: -bins: [-normalize]"); ---- ==== [[library-v1:assert]] [caption=""] .assert ==== [listing, swiftdoc] ---- assert(boolean assertion) ---- If +assertion+ is +false+, +assert()+ causes the program to abort with the message "Assertion failed". If +assertion+ is +true+, this function does nothing. ==== [[library-v1:assert-2]] [caption=""] .assert ==== [listing, swiftdoc] ---- assert(boolean assertion, string message) ---- If +assertion+ is +false+, +assert()+ causes the program to abort with the message +message+. If +assertion+ is +true+, this function does nothing. ==== [[library-v1:assert-3]] [caption=""] .assert ==== [listing, swiftdoc] ---- assert(int assertion) ---- Equivalent to <>+(assertion != 0)+. ==== [[library-v1:assert-4]] [caption=""] .assert ==== [listing, swiftdoc] ---- assert(int assertion, string message) ---- Equivalent to <>+(assertion != 0, message)+. ==== [[library-v1:java]] [caption=""] .java ==== [listing, swiftdoc] ---- T java(string cls, string method, any... args) ---- Allows invocation of certain static Java methods. The string +cls+ contains a fully qualified class name and the string +method+ contains a method name. The +java()+ function searches the class +cls+ for a method +method+ that can be invoked with the given +args+. If such a method is found, it is invoked and, if it returns a non-+null+ value that can be converted into a Swift value, then +java()+ returns the corresponding Swift value, otherwise it returns +false+. The determination of whether a method can be invoked with the given +args+ is made based on the types of +args+. All methods in the class hierarchy of +cls+ matching the name +method+ are first enumerated. The implementation of +java()+ then checks whether each of the +args+ can be converted to a Java type matching the respective method parameter and the first matching method is invoked. The conversion rules that +java()+ supports are listed in the following table: [options="header"] |======================================== |Java method parameter type| Swift type | +int+ | +int+ | +java.lang.Integer+ | +int+ | +long+ | +int+ | +java.lang.Long+ | +int+ | +float+ | +float+ | +java.lang.Float+ | +float+ | +double+ | +float+ | +java.lang.Double+ | +float+ | +boolean+ | +boolean+ | +java.lang.Boolean+ | +boolean+ | +java.lang.String+ | +string+ | +java.lang.Object[]+ | +any[int]+ | +java.util.Map+ | +any[string]+ |======================================== The Swift type returned also depends on the Java type returned by the method as follows: [options="header"] |======================================== |Java method return type | Swift return type | +int+ | +int+ | +java.lang.Integer+ | +int+ | +double+ | +float+ | +java.lang.Double+ | +float+ | +boolean+ | +boolean+ | +java.lang.Boolean+ | +boolean+ | +java.lang.String+ | +string+ |======================================== ==== [[library-v1:system]] [caption=""] .system ==== [listing, swiftdoc] ---- string[] system(string cmd) ---- ==== **** .Miscelaneous Functions **** [[library-v1:length]] [caption=""] .length ==== [listing, swiftdoc] ---- int length(any[] array) ---- Waits for +array+ to be closed and returns its length. ==== **** .Deprecated Functions **** [[library-v1:readdata]] [caption="Deprecated: "] .readdata ==== [listing, swiftdoc] ---- T readdata(any f) ---- Deprecated capitalization for <> ==== [[library-v1:readdata2]] [caption="Deprecated: "] .readdata2 ==== [listing, swiftdoc] ---- T readdata2(any f) ---- Deprecated capitalization for <> ==== [[library-v1:readstructured]] [caption="Deprecated: "] .readstructured ==== [listing, swiftdoc] ---- T readstructured(any f) ---- Deprecated capitalization for <> ==== [[library-v1:writedata]] [caption="Deprecated: "] .writedata ==== [listing, swiftdoc] ---- file writedata(any f) ---- Deprecated capitalization for <> ==== [[library-v1:extractint]] [caption="Deprecated: "] .extractint ==== [listing, swiftdoc] ---- int extractint(any f) ---- Deprecated capitalization for <> ==== [[library-v1:toint]] [caption="Deprecated: "] .toint ==== [listing, swiftdoc] ---- int toint(any value) ---- Deprecated capitalization for <> ==== [[library-v1:tofloat]] [caption="Deprecated: "] .tofloat ==== [listing, swiftdoc] ---- float tofloat(any value) ---- Deprecated capitalization for <> ==== [[library-v1:tostring]] [caption="Deprecated: "] .tostring ==== [listing, swiftdoc] ---- string tostring(any value) ---- Deprecated capitalization for <> ==== ****