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").

Strings are iterable. This scripts prints the string’s characters one per line:

SET str TO "abcde".

FOR c IN str {
  PRINT c.
}

Boolean Operators¶

Equality¶

Using the = and <> operators, two strings are equal if and only if they are the same length and have letters that differ only in capitalization (a and A are considered the same letter for this test).

Ordering¶

Using the <, >, <=, and >= operators, one string is considered to be less than the other if it is alphabetically sooner according to the ordering of its Unicode mapping, with the exception that capitalization is ingored (a and A are considered the same letter). Starting from the lefthand side of the two strings, the characters are compered one at a time until the first difference is found, and that first difference decides the ordering. If one of the strings is shorter length than the other, and the characters are all equal up until one of the two strings runs out of characters, then the shorter string will be considered “less than” the longer one.

Mixtures of strings and non-strings¶

If you attempt to compare two things only one of which is a string and the other is not, then the non-string will be converted into a string first, (Giving the same string as its :TOSTRING suffix would give), and the two will be compared as strings. Example:

print (1234 < 99).    // prints "False"
print ("1234" < 99).  // prints "True"

In the first example, both sides of the < operator are scalars, so the comparison is done numerically, and 1234 is much bigger than 99.

In the second example, one side of the < operator is a string, so the other side is converted from the scalar 99 into the string "99" to perform the comparison, and then the string comparison looks one character at a time and notices that “1” is less than “9” and calls “1234” the lesser value.

CASE SENSITIVIY¶

NOTE: All string comparisons for equality and ordering, all substring matches, and all string 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.

At the moment the only way to force a case-sensitive comparison is to look at the characters one at a time and obtain their numerical ordinal Unicode value with the unchar(a) function.

Structure¶

structure String¶

Members¶
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)`	`Scalar`	Returns the index of the first occurrence of the given string in this string (starting from 0)
`FINDAT(string, startAt)`	`Scalar`	Returns the index of the first occurrence of the given string in this string (starting from startAt)
`FINDLAST(string)`	`Scalar`	Returns the index of the last occurrence of the given string in this string (starting from 0)
`FINDLASTAT(string, startAt)`	`Scalar`	Returns the index of the last occurrence of the given string in this string (starting from startAt)
`INDEXOF(string)`	`Scalar`	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)`	`Scalar`	Alias for FINDLAST(string)
`LENGTH`	`Scalar`	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:ENDSWITH(string)¶

Parameters:	string – `String` to look for
Return type:	boolean

True if this string ends with the given string.

String:FIND(string)¶

Parameters:	string – `String` to look for
Return type:	`String`

Returns the index of the first occurrence of the given string in this string (starting from 0).

String:FINDAT(string, startAt)¶

Parameters:	string – `String` to look for startAt – `Scalar` (integer) index to start searching at
Return type:	`String`

Returns the index of the first occurrence of the given string in this string (starting from startAt).

String:FINDLAST(string)¶

Parameters:	string – `String` to look for
Return type:	`String`

Returns the index of the last occurrence of the given string in this string (starting from 0)

String:FINDLASTAT(string, startAt)¶

Parameters:	string – `String` to look for startAt – `Scalar` (integer) index to start searching at
Return type:	`String`

Returns the index of the last occurrence of the given string in this string (starting from startAt)

String:INDEXOF(string)¶: Alias for FIND(string)

String:INSERT(index, string)¶

Parameters:	index – `Scalar` (integer) index to add the string at string – `String` to insert
Return type:	`String`

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:	`Scalar` (integer)
Access:	Get only

Number of characters in the string

String:PADLEFT(width)¶

Parameters:	width – `Scalar` (integer) number of characters the resulting string will contain
Return type:	`String`

Returns a new right-aligned version of this string padded to the given width by spaces.

String:PADRIGHT(width)¶

Parameters:	width – `Scalar` (integer) number of characters the resulting string will contain
Return type:	`String`

Returns a new left-aligned version of this string padded to the given width by spaces.

String:REMOVE(index,count)¶

Parameters:	index – `Scalar` (integer) position of the string from which characters will be removed from the resulting string count – `Scalar` (integer) number of characters that will be removing from the resulting string
Return type:	`String`

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:	oldString – `String` to search for newString – `String` that all occurances of oldString will be replaced with
Return type:	`String`

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:	`List`

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).

String:STARTSWITH(string)¶

Parameters:	string – `String` to look for
Return type:	boolean

True if this string starts with the given string .

String:SUBSTRING(start,count)¶

Parameters:	start – `Scalar` (integer) starting index (from zero) count – `Scalar` (integer) resulting length of returned `String`
Returns:	`String`

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

String:TRIM¶

Type:	`String`
Access:	Get only

returns a new string with no leading or trailing whitespace

String:TRIMEND¶

Type:	`String`
Access:	Get only

returns a new string with no trailing whitespace

String:TRIMSTART¶

Type:	`String`
Access:	Get only

returns a new string with no leading whitespace

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