String represents an array of Chars.
Strings can be written literally using double quotes:
A sequence of string literals will be concatenated together:
Backslash is the escape character. See Literals: Characters.
Note that, while Char does not support encodings aside from ASCII—such as multi-byte encodings like UTF-8 and UTF-16, or the full Latin-1 (ISO 8859-1) character set—Chars with negative values are perfectly legal, and may be strung together in strings that use these encodings.
The SuperCollider IDE uses UTF-8 (a superset of ASCII) to decode and display strings, which means that the string "🎹🙄🎻😂🎚️🎛️🎤😍" can be written in the editor, posted in the post window, and treated for the most part like any other string. However, because non-ASCII UTF-8 characters consist of two or more bytes, and a SuperCollider String's members are one-bit Chars, concepts of size and indexing may not behave intuitively. For instance, the "size" of the string above is 38, not 8, and the value of its first index is -16, which is not a valid ASCII value at all but rather the signed 8-bit representation of the first byte of the UTF-8 value of the piano keyboard emoji (🎹), 0xF09F8EB9.
Read the entire contents of a File and return them as a new String.
Deprecated alias for Platform.resourceDir. Please use Platform: *resourceDir instead.
Creates a String representing the name of a note.
| name |
Name or MIDI pitch of the note to construct. |
| alt |
Number of half-steps (semitones) to adjust the note by. Equivalent to 100 cents. If this exceeds the |
| octave |
The octave of the note. |
| cents |
Number of cents, i.e. one-hundredths of a half-step (semitone) to adjust the note by. |
| maxAlt |
Maximum number of accidentals to include in the string. Any excess will be translated into cents which can be obtained from the resulting string via the unique Defaults to 2. |
An IdentityDictionary mapping characters representing note names to their offsets within the MIDI octave. For example, $C maps to 0, and $D maps to 2. Accidentals are not supported.
Strings respond to .at in a manner similar to other indexed collections. Each element is a Char.
Returns an Array of ASCII values of the Strings's characters.
Note that if a string contains multi-byte UTF-8 characters, this array will not be of the same length as the number of visible characters, nor will it necessarily be an array of valid 7-bit ASCII values.
Returns an integer less than, equal to or greater than zero, depending on whether the receiver should be sorted before the argument, is equal to the argument or should be sorted after the argument. This is a case sensitive compare.
Returns a Boolean whether the receiver should be sorted before the argument.
Returns a Boolean whether the receiver should be sorted after the argument.
Returns a Boolean whether the receiver should be sorted before the argument, including the same string.
Returns a Boolean whether the receiver should be sorted after the argument, including the same string.
Returns a Boolean whether the two Strings are not equal.
With fuzzy comparison, the strings don't need to match exactly - we can work out how similar they are, and make decisions based on that. This behaviour is inherited from the SequenceableCollection: -editDistance, and is documented fully there, but to provide an example:
Prints the string to the current post window.
Prints the string and a carriage return to the current post window.
Prints a formatted string with arguments to the current post window. The % character in the format string is replaced by a string representation of an argument. To print a % character use \\% .
As -postln, but posts the compileString of the receiver.
Prepends an error banner and posts the string.
Prepends a warning banner and posts the string.
Legacy method (although due to widespread use, it will not be removed). This is identical to postln.
Compiles a String containing legal SuperCollider code and returns a Function.
Compile and execute a String containing legal SuperCollider code, returning the result.
Compile, execute and print the result of a String containing legal SuperCollider code.
Returns a String formatted for compiling.
Return a Symbol derived from the String.
Return an Integer derived from the String. Strings beginning with non-numeric characters return 0.
Return a Float derived from the String. Strings beginning with non-numeric characters return 0.
Return a Float based on converting a time string in format (ddd:)hh:mm:ss(.z), where z is any sequence of digits. This is the inverse method to SimpleNumber: -asTimeString.
Return a concatenation of the two strings.
Return a concatenation of the two strings with a space between them.
Concatenates this and path, as components of a filesystem path on the host operating system. The strings are joined to avoid duplicate path separators.
If this ends with a path separator and path begins with one, then the separator in path is dropped. If there is a path separator on either side, this has the same effect as using ++. If neither side has a path separator, the platform's preferred separator ('\' on Windows, '/' otherwise) is added.
Returns this and path concatenated. If path was a PathName, the result is a PathName; otherwise, it is a String.
| path |
Any object that can be converted to a string. Typically, either a String, Symbol, or PathName. |
Concatenate this string with the following args.
Same as -catArgs, but with spaces in between.
Same as -catArgs, but with commas in between.
As -catArgs, -scatArgs and -ccatArgs above, but takes a Collection (usually a List or an Array) as an argument.
The String class provides access to the boost library's regular expression functions. Boost's default uses Perl settings. (Currently, there is no hook to override the regex style.) Syntax details may be found at https://www.boost.org/doc/libs/1_69_0/libs/regex/doc/html/boost_regex/syntax/perl_syntax.html.
Note carefully the argument order:
regexp.matchRegexp(stringToSearch)stringToSearch.findRegexp(regexp) (and similar for findAllRegexp and findRegexpAt).findRegexp follows the pattern established by String: -find, where the receiver is the string to be searched. matchRegexp follows the pattern of matchItem, where the receiver is the pattern to match and the first argument is the object to be tested. This is a common source of confusion, but it is based on this precedent.
Perl regular expression matching (see String: Regular expressions). Returns true if the receiver (a regular expression pattern) matches the string passed to it. The start is an offset where to start searching in the string (default: 0), end where to stop.
regexp.matchRegexp(stringToSearch) and not the other way around! See above: String: Regular expressions.Perl regular expression search (see String: Regular expressions). This method searches exhaustively for matches and collects them into an array of pairs, in the format [character index, matching string].
"Leftmost largest match": As in most flavors of regular expressions, * and + are greedy; if it is possible to have more than one overlapping match for a part of the regular expression, the match list will include only the leftmost and largest of them. In "foobar".findRegexp("o+"), "o+" may potentially have three matches: "o" at index 1 (second character), "o" at index 2, and "oo" at index 1. findRegexp will return only the last of these ("oo"), because it begins in the leftmost-possible matching position, and it is the longest possible match at that position.
Note, though, that parentheses for grouping (a "marked sub-expression" or "capturing group") will produce a separate result: "aaa".findRegexp("(a+)"); appears to produce duplicated results [ [ 0, aaa ], [ 0, aaa ] ], but this is because the first match is for the parentheses and the second is for a+.
To see the marked sub-expression results more clearly, consider:
"oobar" matches the entire regular expression. "oo" and "bar" match the first and second parenthesized sub-expressions, respectively.
A nested array, where each sub-array is a pair, [character index, matching string]. If there are no matches, an empty array.
Like -findAll, but use regular expressions (see String: Regular expressions). Unlike findRegexp, it returns only the indices of the matches: string.findAllRegexp(regexp) returns the same as string.findRegexp(regexp).flop.at(0).
An array of integer character indices pointing to all the possible matches.
Match a regular expression (see String: Regular expressions) at the given offset, returning the match and the length of the match in an Array, or nil if it doesn't match. The match must begin right at the offset.
An array [matching string, length] if a match is found at the specified offset; nil if the offset doesn't match.
Returns the index of the string in the receiver, or nil if not found. If ignoreCase is true, find makes no difference between uppercase and lowercase letters. The offset is the point in the string where the search begins. string may be a String or a Char.
Same like -find, but starts at the end of the string.
Returns the indices of the string in the receiver, or nil if not found.
Returns a Boolean indicating if the String contains string.
Same as -contains, but case insensitive.
Returns a Boolean indicating if the String contains string beginning at the specified index.
Same as -containsStringAt, but case insensitive.
Returns true if this string begins/ends with the specified other string.
| string |
The other string |
A Boolean
Rotate the string by n steps.
Randomize the order of characters in the string.
Like -tr, but with Strings as well as Chars as arguments.
Returns a formatted string with arguments. The % character in the format string is replaced by a string representation of an argument. To print a % character use \\% .
Add the escape character (\) before any character of your choice.
Return this string enclosed in double-quote ( " ) characters.
Return this string enclosed in space characters.
Return this string followed by dashes in the next line ( - ).
Transliteration. Replace all instances of from with to.
Pad this string with string so it fills size character.
| size |
Number of characters to fill |
| string |
Padding string |
Return this string with uppercase letters.
Return this string with lowercase letters.
Returns a new String with all RTF formatting removed.
Returns an Array of Strings split at the separator. The separator is a Char, and is not included in the output array.
Print the String on stream.
Same as -printOn, but formatted -asCompileString.
Where relevant, the current working directory is the same as the location of the SuperCollider app and the shell is the Bourne shell (sh). Note that the cwd, and indeed the shell itself, does not persist:
It is however possible to execute complex commands:
Also on os x applescript can be called via osascript:
Should you need an environment variable to persist you can use -setenv.
Execute a UNIX command asynchronously using the standard shell (sh).
| action |
A Function that is called when the process has exited. It is passed two arguments: the exit code and pid of the exited process. |
| postOutput |
A Boolean that controls whether or not the output of the process is displayed in the post window. |
An Integer - the pid of the newly created process. Use Integer: -pidRunning to test if a process is alive.
Example:
Similar to -unixCmd except that the stdout of the process is returned (synchronously) rather than sent to the post window.
Executes a UNIX command synchronously using the standard shell (sh).
Error code of the UNIX command
Execute the String in a new terminal window (asynchronously).
| shell |
The shell used to execute the string. |
Example:
Set the environment variable indicated in the string to equal the String value. This value will persist until it is changed or SC is quit. Note that if value is a path you may need to call -standardizePath on it.
Returns the value contained in the environment variable indicated by the String.
Set the environment variable to nil.
Make a directory from the given path location.
Returns an Array containing all paths matching this String. Wildcards apply, non-recursive.
Load and execute the file at the path represented by the receiver.
Perform -pathMatch on this String, then load and execute all paths in the resultant Array.
| warn |
Post a warning if path doesn't point to any file. |
| action |
If a function is passed, it is called with each path as argument. |
Load and execute the file at the path represented by the receiver, interpreting the path as relative to the current document or text file. Requires that the file has been saved. This can be used e.g. to load initialization code from files in the same folder.
| warn |
Warn if a file is not found. |
| action |
A function that is called for each file path that is found. |
Convert the receiver from a relative path to an absolute path, relative to the current document or text file. Requires that the current text file has been saved. Absolute paths are left untransformed.
Expand ~ to your home directory, and resolve aliases on macOS. See PathName for more complex needs. See File: *realpath if you want to resolve symlinks.
Open file, directory or URL via the operating system. On macOS this is implemented via open, on Linux via xdg-open and on Windows via start.
Also see -+/+ for path concatenation.
The term "path separator" is a platform-independent term for the character(s) that can be used to separate components of a path. On Windows, both forward slash "/" and backward slash "\\" are path separators. On POSIX-based systems like macOS and Linux, only forward slash is allowed.
Return a new string suitable for use as a filename in a shell command, by enclosing it in single quotes ( ' ). If the string contains any single quotes they will be escaped.
You should use this method on a path before embedding it in a string executed by -unixCmd or -systemCmd.
Return this path as an absolute path by prefixing it with File: *getcwd if necessary.
Return this path as relative to the specified path.
| relativeTo |
The path to make this path relative to. |
Appends a path separator if one is not already present.
Removes a trailing path separator if one is present.
Return the filename from a Unix path.
Return the directory name from a Unix path.
Split off the extension from a filename or path and return both in an Array as [path or filename, extension].
Parse this string as YAML/JSON.
A nested structure of Arrays (for sequences), Dictionaries (for maps) and Strings (for scalars).
Same as parseYAML but parse a file directly instead of a string. This is faster than reading a file into a string and then parse it.
This method is currently just an alias for -parseYAML, in the future it will only accept valid JSON.
A nested structure of Arrays (for sequences), Dictionaries (for maps) and Strings (for scalars).
This method is currently just an alias for -parseYAMLFile, in the future it will only accept valid JSON files.
Create a new Document with this.
Create a new Document from the path corresponding to this. The selection arguments will preselect the indicated range in the new window. Returns this.
Returns the path for the helpfile named this, if it exists, else returns nil.
Performs -findHelpFile on this, and opens the file it if it exists, otherwise opens the main helpfile.
Returns class StringInspector.
The following methods must be called within an Window-drawFunc or a SCUserView-drawFunc function, and will only be visible once the window or the view is refreshed. Each call to Window-refresh SCUserView-refresh will 'overwrite' all previous drawing by executing the currently defined function.
See also: Window, UserView, Color, and Pen.
Pen.stringAtPoint, Pen.stringInRect, Pen.stringCenteredIn, Pen.stringLeftJustIn, Pen.stringRightJustIn instead.Draws the String at the current 0@0 Point. If not transformations of the graphics state have taken place this will be the upper left corner of the window. See also Pen.
Draws the String into the given Rect using the Font and Color specified.
Draws the String into the given Rect using the Font and Color specified.
Tries to return a Rect with the size needed to fit this string if drawn with given font.
| font |
A Font |
Strips whitespace at the beginning and end of the string.
The stripped string
Like -unixCmdGetStdOut but returns the lines in an Array instead.
an Array of each line of output
Same as String: *notesDict.
Converts a note name to a MIDI note pitch.
| cents |
Number of cents to adjust |
Float corresponding to a MIDI note pitch
-1 / 1 / 2 if the String contains b / # / x respectively, or 0 otherwise.
Memoizes the result.
Integer corresponding to the numerical component of the note.
Does not take into account accidentals shifting the pitch into a different octave. This is probably a bug!
Memoizes the result.