String¶
A String
is an immutable sequence of characters in kOS.
Creating strings¶
Unlike other structures, strings are created with a special syntax:
// Create a new string
SET s TO "Hello, Strings!".
Strings are immutable. This means, once a string has been created, it can not be directly modified. However, new strings can be created out of existing strings. For example:
// Create a new string with "Hello" replaced with "Goodbye"
SET s TO "Hello, Strings!".
SET t TO s:REPLACE("Hello", "Goodbye").
CASE SENSITIVIY¶
NOTE: All string comparisons, substring matches, and searches, are currently case in sensive, meaning that for example the letter “A” and the letter “a” are indistinguishable. There are future plans to add mechanisms that will let you choose case-sensitivity when you prefer.
Structure¶
-
structure
String
¶ ¶ Suffix Type Description CONTAINS(string)
boolean True if the given string is contained within this string ENDSWITH(string)
boolean True if this string ends with the given string FIND(string)
integer Returns the index of the first occurrence of the given string in this string (starting from 0) FINDAT(string, startAt)
integer Returns the index of the first occurrence of the given string in this string (starting from startAt) FINDLAST(string)
integer Returns the index of the last occurrence of the given string in this string (starting from 0) FINDLASTAT(string, startAt)
integer Returns the index of the last occurrence of the given string in this string (starting from startAt) INDEXOF(string)
integer Alias for FIND(string) INSERT(index, string)
String
Returns a new string with the given string inserted at the given index into this string LASTINDEXOF(string)
integer Alias for FINDLAST(string) LENGTH
integer Number of characters in the string PADLEFT(width)
String
Returns a new right-aligned version of this string padded to the given width by spaces PADRIGHT(width)
String
Returns a new left-aligned version of this string padded to the given width by spaces REMOVE(index,count)
String
Returns a new string out of this string with the given count of characters removed starting at the given index REPLACE(oldString, newString)
String
Returns a new string out of this string with any occurrences of oldString replaced with newString SPLIT(separator)
String
Breaks this string up into a list of smaller strings on each occurrence of the given separator STARTSWITH(string)
boolean True if this string starts with the given string SUBSTRING(start, count)
String
Returns a new string with the given count of characters from this string starting from the given start position TOLOWER
String
Returns a new string with all characters in this string replaced with their lower case versions TOUPPER
String
Returns a new string with all characters in this string replaced with their upper case versions TRIM
String
returns a new string with no leading or trailing whitespace TRIMEND
String
returns a new string with no trailing whitespace TRIMSTART
String
returns a new string with no leading whitespace
-
String:
CONTAINS
(string)¶ Parameters: - string –
String
to look for
Return type: boolean
True if the given string is contained within this string.
- string –
-
String:
ENDSWITH
(string)¶ Parameters: - string –
String
to look for
Return type: boolean
True if this string ends with the given string.
- string –
-
String:
FIND
(string)¶ Parameters: - string –
String
to look for
Return type: Returns the index of the first occurrence of the given string in this string (starting from 0).
- string –
-
String:
FINDAT
(string, startAt)¶ Parameters: - string –
String
to look for - startAt – integer index to start searching at
Return type: Returns the index of the first occurrence of the given string in this string (starting from startAt).
- string –
-
String:
FINDLAST
(string)¶ Parameters: - string –
String
to look for
Return type: Returns the index of the last occurrence of the given string in this string (starting from 0)
- string –
-
String:
FINDLASTAT
(string, startAt)¶ Parameters: - string –
String
to look for - startAt – integer index to start searching at
Return type: Returns the index of the last occurrence of the given string in this string (starting from startAt)
- string –
-
String:
INDEXOF
(string)¶ Alias for FIND(string)
-
String:
INSERT
(index, string)¶ Parameters: - index – integer index to add the string at
- string –
String
to insert
Return type: Returns a new string with the given string inserted at the given index into this string
-
String:
LASTINDEXOF
(string)¶ Alias for FINDLAST(string)
-
String:
LENGTH
¶ Type: integer Access: Get only Number of characters in the string
-
String:
PADLEFT
(width)¶ Parameters: - width – integer number of characters the resulting string will contain
Return type: Returns a new right-aligned version of this string padded to the given width by spaces.
-
String:
PADRIGHT
(width)¶ Parameters: - width – integer number of characters the resulting string will contain
Return type: Returns a new left-aligned version of this string padded to the given width by spaces.
-
String:
REMOVE
(index,count)¶ Parameters: - index – integer position of the string from which characters will be removed from the resulting string
- count – integer number of characters that will be removing from the resulting string
Return type: Returns a new string out of this string with the given count of characters removed starting at the given index.
-
String:
REPLACE
(oldString,newString)¶ Parameters: Return type: Returns a new string out of this string with any occurrences of oldString replaced with newString.
-
String:
SPLIT
(separator)¶ Parameters: - separator –
String
delimiter on which this string will be split
Returns: Breaks this string up into a list of smaller strings on each occurrence of the given separator. This will return a list of strings, none of which will contain the separator character(s).
- separator –
-
String:
STARTSWITH
(string)¶ Parameters: - string –
String
to look for
Return type: boolean
True if this string starts with the given string .
- string –
-
String:
SUBSTRING
(start,count)¶ Parameters: - start – (integer) starting index (from zero)
- count – (integer) resulting length of returned
String
Returns: Returns a new string with the given count of characters from this string starting from the given start position.
-
String:
TOLOWER
¶ Type: String
Access: Get only Returns a new string with all characters in this string replaced with their lower case versions
-
String:
TOUPPER
¶ Type: String
Access: Get only Returns a new string with all characters in this string replaced with their upper case versions
Access to Individual Characters¶
All string indexes start counting at zero. (The characters are numbered from 0 to N-1 rather than from 1 to N.)
string[expression]
- operator: access the character at position ‘expression’. Any arbitrary complex expression may be used with this syntax, not just a number or variable name.
FOR VAR IN STRING { ... }.
- A type of loop in which var iterates over all the characters of the string from 0 to LENGTH-1.
Examples:
// CORRECT OUTPUTS
SET s TO "Hello, Strings!". // ---------------
PRINT "Original String: " + s. // Hello, Strings!
PRINT "string[7]: " + s[7]. // S
PRINT "LENGTH: " + s:LENGTH. // 15
PRINT "SUBSTRING(7, 6): " + s:SUBSTRING(7, 6). // String
PRINT "CONTAINS(''ring''): " + s:CONTAINS("ring"). // True
PRINT "CONTAINS(''bling''): " + s:CONTAINS("bling"). // False
PRINT "ENDSWITH(''ings!''): " + s:ENDSWITH("ings!"). // True
PRINT "ENDSWITH(''outs!''): " + s:ENDSWITH("outs"). // False
PRINT "FIND(''l''): " + s:FIND("l"). // 2
PRINT "FINDLAST(''l''): " + s:FINDLAST("l"). // 3
PRINT "FINDAT(''l'', 0): " + s:FINDAT("l", 0). // 2
PRINT "FINDAT(''l'', 3): " + s:FINDAT("l", 3). // 3
PRINT "FINDLASTAT(''l'', 9): " + s:FINDLASTAT("l", 9). // 3
PRINT "FINDLASTAT(''l'', 2): " + s:FINDLASTAT("l", 2). // 2
PRINT "INSERT(7, ''Big ''): " + s:INSERT(7, "Big "). // Hello, Big Strings!
PRINT " ".
PRINT " |------ 18 ------|".
PRINT "PADLEFT(18): " + s:PADLEFT(18). // Hello, Strings!
PRINT "PADRIGHT(18): " + s:PADRIGHT(18). // Hello, Strings!
PRINT " ".
PRINT "REMOVE(1, 3): " + s:REMOVE(1, 3). // Ho, Strings!
PRINT "REPLACE(''Hell'', ''Heaven''): " + s:REPLACE("Hell", "Heaven"). // Heaveno, Strings!
PRINT "STARTSWITH(''Hell''): " + s:STARTSWITH("Hell"). // True
PRINT "STARTSWITH(''Heaven''): " + s:STARTSWITH("Heaven"). // False
PRINT "TOUPPER: " + s:TOUPPER(). // HELLO, STRINGS!
PRINT "TOLOWER: " + s:TOLOWER(). // hello, strings!
PRINT " ".
PRINT "'' Hello! '':TRIM(): " + " Hello! ":TRIM(). // Hello!
PRINT "'' Hello! '':TRIMSTART(): " + " Hello! ":TRIMSTART(). // Hello!
PRINT "'' Hello! '':TRIMEND(): " + " Hello! ":TRIMEND(). // Hello!
PRINT " ".
PRINT "Chained: " + "Hello!":SUBSTRING(0, 4):TOUPPER():REPLACE("ELL", "ELEPHANT"). // HELEPHANT