Strings

Formatted Strings | String | StringBuilder

Overview

Use StringBuilder to efficiently build a String out of multiple parts.
The compiler converts String concatenations ("st1 + st2 + st3") to use StringBuilder underneath where appropriate.

Formatted Strings

When you type a literal string followed by a parenthesized argument list:

  String st = "$, $, $!" (a,b,c)

This is called a formatted string. The '$' characters are called format markers and the (a,b,c) in the example are called the format arguments. The compiler translates it into this:

  String st = a + ", " + b + ", " + c + "!"

The following format markers may be used:

$	Insert format argument with default formatting.
$()	(dollar sign with empty parentheses) Same effect as '$' but may be used to allow a literal '(' to follow the dollar sign. For example, "$()()" (5) would result in the string "5()".
$(5)	Inserts its argument with at least 5 digits before the decimal point. Real numbers still print out 4 digits after by default; use "$(5.0)" to print out only the integer portion of a real number (rounded off).
$(05)	Inserts its argument with at least 5 digits before the decimal point and any unused digits filled with zeros.
$(4.2)	Formats as a real number with at least 4 digits before the decimal point and 2 digits after.
$(04.2)	Real number padded with zeros in front.
$$	Inserts a single '$' - technically not a format marker.

String
class : Object, IndexReadOperations<<Char>>, .AnonymousAspect1

DESCRIPTION
- A String is a sequence of zero or more Unicode characters. Strings are immutable - operations return modified strings rather than changing the original.
- Invariant: a String's state never changes.
- Examples:
```
  local String st = "Slag"
  println( st.length )  # prints: 4
  forEach (ch in st) print("$."(ch))  # prints: S.l.a.g.
```
PROPERTIES
- data : Array<<Char>>
  - The array of characters that comprise the string.
  - Invariant: never altered outside of initializers.
- hash_code : Int32
  - Returns the hash_code of this String. See Object::hash_code().Int32 for more details.
METHODS
- init(Char ch)
  - Creates a String of count==1 containing the single Char 'ch'.
- init(Int32 len)
  - Creates a String of null characters. Used with 'substring'.
- init(Array<<Char>> init:data)
  - Creates a string that directly uses the given character array. Caution: changing the character array after the string is created will change the string contents!
- init(StringBuilder buffer)
  - Turns the content of the given StringBuilder into a single String.
- init(Readable<<Char>> src)
  - Creates a String out of all the characters in 'src'.
  - Example:
```
  local String st( 'A' .. 'F' step 2 )
  println( st )  # prints: ACE
```
- init(Reader<<Char>> src)
  - Creates a String out of all the characters in 'src'.
- create_duplicate().String
  - Returns this same String object since strings are immutable.
- consolidate().String
  - Returns an equivalent substitute string that is guaranteed to be the same string object as any other equivalent string previously returned by consolidate().
  - For example, say that A and B are two strings such that "A == B" is true and "A is B" is false.
  - After these calls:
```
  A = A.consolidate
  B = B.consolidate
```
    Then "A == B" and "A is B" are both true.
- set_hash_code() : native
  - Sets the hash_code from the contents of 'data'.
  - The alogorithm is as follows: - The code starts out at zero. - For each Char ch:
```
  code = code.left_rotated(7) + ch
```
    hash_code = 0 orEach (index of &data) hash_code = &hash_code.left_rotated(7) + &data[index] ndForEach
- hash_code().Int32
  - Returns the hash_code of this String.
- data().Array<<Char>>
  - Enforces the immutable property of strings by throwing an error on any attempt to access this string's data.
- to_String().String
  - Returns this String object unmodified.
- count().Int32
  - Returns the number of characters (0 or more) in this string.
- get(Int32 i).Char
  - Retrieves the character at index i.
  - Requires: 0 <= i < count
- set(Int32 i,Char value)
  - Sets the character at index 'i'.
  - Requires: 0 <= i < count
- op==(Object other).Logical {multimethod}
  - Compares this string to another object.
  - Returns false if 'other' is not a string, or forwards the call to String::op==(String) otherwise.
- op==(String other).Logical : native {multimethod}
  - Compares this string to another string.
  - Returns:
```
  "false" if (this.hash_code != other.hash_code) 
          or (this.count != other.count)
  "true" if all characters match between 'this' and 'other'.
```
    f (this is other) return true f (&hash_code != other.&hash_code) return false eturn op<>( other ) == eq
- equals_ignore_case(String other).Logical
  - Returns true if this string is equal to another string, ignoring the case of characters during comparison.
  - For example, "ABcd".equals_ignore_case("AbCd") returns "true".
- op<>(Object other).Logical {multimethod}
  - Requires:
```
  (other isNot null) and (other instanceOf String)
```
    Returns:
```
  'eq' if this.op==(other)
  'lt' if strings differ at spot 'i' and this[i] < other[i]
  'gt' if strings differ at spot 'i' and this[i] > other[i]
```
- op<>(String other).Logical : native {multimethod}
  - Returns:
```
  'eq' if this.op==(other)
  'lt' if strings differ at spot 'i' and this[i] < other[i]
  'gt' if strings differ at spot 'i' and this[i] > other[i]

     local Int32 my_count = &data.count
     local var   other_data = other.&data
     local Int32 other_count = other_data.count
     local Int32 compare_count = my_count

     if (compare_count > other_count) compare_count = other_count

     forEach (i in 0 ..< compare_count)
       local Char ch1 = &data[i]
       local Char ch2 = other_data[i]
       if (ch1 < ch2)      return lt
       elseIf (ch1 > ch2) return gt
     endForEach

     # Everything matches so far.  Determine final equality
     # based on string length.
     if (my_count == other_count) return eq
     elseIf (my_count > other_count) return gt
     else return lt
```
- matches(Pattern p).Logical
  - Returns:
```
  "true" if this string matches the given pattern with no
         excess characters.
  "false" otherwise.
```
- matches_wildcard_pattern(String wildcard_pattern).Logical
  - Determines whether or not this string matches the given Unix/Dos-style "wildcard pattern". 'wildcard_pattern' is a regular text string that may contain the following special characters:
  - ```
    * - matches zero or more characters of this string.
    ? - matches any one character of this string.
```
  Example:
```
    local String st = "img_01.png"
    println( st.matches_wildcard_pattern("*.png") )  # true
    println( st.matches_wildcard_pattern("img_??.png") )  # true
```
- op+(String other).String
  - Returns a new string consisting of 'this' concatenated with 'other'.
  - Requires: other isNot null
- op+(Char ch).String
  - Returns a new string consisting of 'this' concatenated with 'ch'.
- op+(Int64 n).String
  - Returns a new string consisting of 'this' concatenated with a base 10 string representation of 'n'.
- op+(Int32 n).String
  - Returns a new string consisting of 'this' concatenated with a base 10 string representation of 'n'.
- op+(Real64 n).String
  - Returns a new string consisting of 'this' concatenated with a base 10 string representation of 'n'.
- op+(Logical n).String
  - Returns a new string consisting of 'this' concatenated with string representation of 'n'.
- op+(Object obj).String
  - Adds the string representation of the given object to this string and returns the joined string.
- substring(Int32 first_index).String
  - Returns the subsequence of characters from this[first_index] up to the end of the string.
  - Requires:
```
  0 <= first_index < count
```
- get(Range<<Int32>> range).String
  - Returns the substring of characters specified by the given range of indices.
  - Requires that all indices of the range be valid string indices 0..<count
  - Example:
```
  local String st('A'..'F')   #st: ABCDEF
  println( st[0..4 step 2] )  # prints: ACE
```
- get(Readable<<Int32>> range).String
  - Returns the substring of characters specified by the given 'Readable<<Int32>>' range of indices.
- extract_groups(Pattern p).String[]
  - Extracts the tagged groups that pattern p matches as a list of strings. The entire string must fit the pattern or else "null" is returned - see extract_all_groups(Pattern) for an alternative.
  - Example:
```
  local Pattern p( "'size' ws {digit+} ws 'x' ws {digit+}" )
  println( "size 2x4".extract_groups(p) )
    # Prints: {2,4}
```
- extract_all_groups(Pattern p).String[]
  - Finds each occurrence of pattern 'p' within this string and returns the String list of groups found from all matches. Returns an empty list if the pattern didn't occur in this string or if the pattern didn't contain any groups.
  - Example:
```
  local Pattern comment( "{'#' (not eol)*}" )
  println( "abc #extract\ndef\n#comments".extract_all_groups(comment) )
    # prints: {#extract,#comments}
```
- index_of(String other[,Int32 starting_index]).Int32
  - Finds the first occurrence of the 'other' string within 'this' string, with an optional starting index.
  - Returns the index of the beginning of the match, or -1 if there's no match.
  - Example:
```
  println( "abcdef".index_of("cd") )
    # prints: 2

  println( "abcdef".index_of("cd",2) )
    # prints: 2

  println( "abcdef".index_of("cd",3) )
    # prints: -1
```
- last_index_of(String other[,Int32 starting_index]).Int32
  - Returns the last (rightmost) occurrence of the 'other' string within this string. An optional starting index may be passed as the second parameter. If it's omitted, it is assumed to be 'count - 1'.
  - Returns the leftmost index of the match or -1 if there's no match.
  - Example:
```
  println( "abab".last_index_of("ab") )   # prints: 2
  println( "abab".last_index_of("ab",2) ) # prints: 2
  println( "abab".last_index_of("ab",1) ) # prints: 0
  println( "abab".last_index_of("zz") )   # prints: -1
```
- index_of(Pattern p[,Int32 starting_index]).Int32
  - Finds the first occurrence of the given pattern within this string, with an optional starting index (default: 0).
  - Returns (result >= 0) if found or (-1) if not found.
- begins_with(String st).Logical
  - Returns "true" if this string begins with the given substring or false otherwise.
- starts_with(String st).Logical
  - OBSOLETE as of v0.21. Use begins_with() instead.
- ends_with(String st).Logical
  - Returns "true" if this string ends with the given substring or false otherwise.
- contains(String other).Logical
  - Returns "true" if this string contains the given string as a subsequence.
- replace(Char look_for,Char replace_with).String
  - Replaces all instances of character 'look_for' with character 'replace_with'.
- replace(Char look_for,String replace_with).String
  - Replaces all instances of character 'look_for' with string 'replace_with'.
- replace(String look_for,String replace_with).String
  - Replaces all instances of string 'look_for' with string 'replace_with'.
- replace(Pattern p,String replacement).String
  - Replaces all occurences of pattern 'p' with the given string. The 'replacement' string may contain the insertion markers $[0], $[1], etc. These are replaced by group 0, group 1, etc. from the pattern.
  - Returns the modified string.
  - Example:
```
  local Pattern name( "{id} ws {id}" )
  local String regular = "Abe Pralle"
  local String roster = regular.replace( name, "$[1], $[0]" ) 
  println( roster )  # prints: Pralle, Abe
```
- leftmost(Int32 num_chars).String
  - Returns the leftmost 'num_chars' of this string as a substring.
  - Equivalent to before(num_chars).
  - Requires:
```
  num_chars <= count
```
    Example:
```
  println( "happy".leftmost(3) )
    # prints: hap
```
- rightmost(Int32 num_chars).String
  - Returns the rightmost 'num_chars' of this string as a substring.
  - Requires:
```
  num_chars <= count
```
    Example:
```
  println( "happy".rightmost(2) )
    # prints: py
```
- excluding_leftmost(Int32 num_chars).String
  - Returns the substring of all characters after the leftmost 'num_chars' of this string.
  - Requires:
```
  num_chars <= count
```
    Example:
```
  println( "happy".excluding_leftmost(3) )
    # prints: py
```
- excluding_rightmost(Int32 num_chars).String
  - Returns the substring of all characters before the rightmost 'num_chars' of this string.
  - Requires:
```
  num_chars <= count
```
    Example:
```
  println( "happy".excluding_rightmost(2) )
    # prints: hap
```
- excluding_substring(Int32 first,Int32 last).String
  - Returns all the characters before 'first' and after 'last' - the complement of substring(first,last).
  - Example:
```
  println( "happy".excluding_substring(2,3) )
    # prints: hay
```
- before(Int32 index).String
  - Returns the substring of this string that occur before the given index.
  - Equivalent to leftmost(index).
- after(Int32 index).String
  - Returns the substring of this string that occur after the given index.
  - Equivalent to substring(index+1).
- before_first(Char ch).String
  - Returns the substring of this string that occurs before the first occurrence of the given character, or returns the entire string if 'ch' does not occur in this string.
- before_last(Char ch).String
  - Returns the substring of this string that occurs before the last occurrence of the given character, or returns the entire string if 'ch' does not occur in this string.
- after_last(Char ch).String
  - Returns the substring of this string that occurs after the last occurrence of the given character, or returns the entire string if 'ch' does not occur in this string.
- after_first(Char ch).String
  - Returns the substring of this string that occurs after the first occurrence of the given character, or returns the entire string if 'ch' does not occur in this string.
- from_first(Char ch).String
  - Returns the substring of this string that occurs starting at the first occurrence of the given character, or returns an empty string if 'ch' does not occur in this string.
- before_first(String st).String
  - Returns the substring of this string that occurs before the first occurrence of the given string, or returns the entire string if 'st' does not occur in this string.
- before_last(String st).String
  - Returns the substring of this string that occurs before the first occurrence of the given string, or returns the entire string if 'st' does not occur in this string.
- after_last(String st).String
  - Returns the substring of this string that occurs after the last occurrence of the given string, or returns the entire string if 'st' does not occur in this string.
- after_first(String st).String
  - Returns the substring of this string that occurs after the last occurrence of the given string, or returns the entire string if 'st' does not occur in this string.
- from_first(String st).String
  - Returns the substring of this string that occurs starting at the first occurrence of the given string, or returns an empty string if 'st' does not occur in this string.
- right_justified(Int32 min_chars[,Char fill_char]).String
  - Returns a new string containing this string right-justified in a field width of 'min_chars', with a space as the default 'fill_char'.
  - If this string is already 'min_chars' in length, no modifications are made.
  - Example:
```
  println( "slag".right_justified(7,'0') )
    # prints: 000slag
```
- left_justified(Int32 min_chars[,Char fill_char]).String
  - Returns a new string containing this string left-justified in a field width of 'min_chars', with a space as the default 'fill_char'.
  - If this string is already 'min_chars' in length, no modifications are made.
  - Example:
```
  println( "slag".left_justified(7,'!') )
    # prints: slag!!!
```
- centered(Int32 min_chars[,Char fill_char]).String
  - Returns a new string containing this string centered in a field width of 'min_chars', with a space as the default 'fill_char'.
  - If this string is already 'min_chars' in length, no modifications are made.
  - Example:
```
  println( "slag".centered(7,'-') )
    # prints: -slag--
```
- to_Int32([Int32 base]).Int32
  - Parses an Int32 out of this string and returns it.
  - Example:
```
  local Int32 n = "456".to_Int32
  println( n )  # prints: 456
```
- to_Int64([Int32 base]).Int64
  - Parses an Int64 out of this string and returns it.
  - Example:
```
  local Int64 n = "456".to_Int64
  println( n )  # prints: 456
```
- to_Real64().Real64
  - Parses a Real64 out of this string and returns it.
  - Example:
```
  local Real64 n = "3.14".to_Real64
  println( n )  # prints: 3.1400
```
- to_File().File
  - Returns a File object with this string as the filepath.
- to_uppercase().String
  - Returns an uppercase version of this string. Lowercase "a-z" letters become capital "A-Z" while other letters and symbols remain unmodified.
  - Example:
```
  println( "Hello World!".to_uppercase )
    # prints: HELLO WORLD!
```
- to_lowercase().String
  - Returns a lowercase version of this string. Uppercase "A-Z" letters become lower "a-z" while other letters and symbols remain unmodified.
  - Example:
```
  println( "Hello World!".to_lowercase )
    # prints: hello world!
```
- capitalized().String
  - Returns a capitalized version of this string - if the first letter is lowercase "a-z" it is turned into its uppercase equivalent. There are no other changes.
- split([Char divider_char]).String[]
  - Splits this string into an array of string objects around (and not including) each character. You may wish to tidy() the string first.
  - Returns: a list of String objects.
  - Example:
```
  println( "a b  c ".split )
    # prints: {a,b,,c,}
```
- trim().String
  - Removes any spaces and non-printable characters from both ends of this string. See tidy() for an alternative that removes extra spaces internally as well.
  - Returns the modified string.
  - Example:
```
  println( "($)" ("  a   b  ".trim) )
    # prints: (a   b)
```
- tidy().String
  - Converts tabs and other non-printable characters to spaces, removes all spaces from the ends, and converts groups of spaces into single spaces.
  - Returns the modified string.
  - Example:
```
  println( "($)" ("  a   b  ".tidy) )
    # prints: (a b)
```
- word_wrap(Int32 width).String[]
  - Returns a word-wrapped version of this string as a list of lines. Existing newlines characters will cause a new line to begin immediately. Spaces immediately following existing newline characters are preserved.
- shuffled().String
  - Returns a copy of this string with the characters in a random order.
- reversed().String
  - Return a copy of this string with its characters in reverse order.
- to_utf8().String
  - Returns a copy of this string encoded in UTF-8 format where only the lower 8 bits of each character are used. Any character with the unicode range 0..127 is unchanged; characters originally having a higher unicode value are encoded into a sequence of 2 or 3 consecutive characters.
  - See also:
```
  String::from_utf8(String)
```
- pluralize(Int32 quantity).String
  - Returns a pluralized form of this string.
  - This string may be of the form "singlar" or "singlar/plural", where both singular and plural parts may contain a "#" to indicate where the given quantity should be inserted.
  - If the string only contains the "singular" part, first a substring of the form "(s)" or "(es)" (etc.) is looked for. If that exists, it is included in the result if the string is plural and omitted if the string is singular.
  - If there is no "(s)" (etc.) then either "s" or "es" is inserted after the last letter - "es" is used only when the last letter is an "s" already.
  - Examples:
```
  "cat".pluralize(1)   # returns: cat
  "cat".pluralize(2)   # returns: cats
  "My # glass.".pluralize(1)  # returns: My 1 glass.
  "My # glass.".pluralize(2)  # returns: My 2 glasses.
  "a thief./# thieves".pluralize(1)   # returns: a thief.
  "a thief./# thieves".pluralize(40)  # returns: 40 thieves.
  "# match(es) found".pluralize(1)    # returns: 1 match found
  "# match(es) found".pluralize(0)    # returns: 0 matches found
```
- init_object()
- modification_count().Int32
  - Returns a counter representing the number of times items has been added to or removed. Used by readers to detect concurrent list modification errors. For example, when an inner method removes an item from a list the modification counter is incremented. An outer "forEach" loop will detect that the count is different from its original value and throw a ConcurrentListModification error.
- first().Char
  - Returns the first element of this data. This convenience method is equivalent to get(0).
- last().Char
  - Returns the last element of this data. This convenience method is equivalent to get(count-1).
- end(Int32 from_end).Char
  - Equivalent to get( (count-1) + from_end ).
  - For example, end(0) is equivalent to last() and end(-1) is equivalent to get(count-2).
- random().Char
  - Returns an element of this data at random.
- random_index().Int32
  - Returns the index of a randomly selected element.
- is_empty().Logical
  - Returns true if count == 0.
- is_not_empty().Logical
  - Returns true if count > 0.
- index_of(Char value[,Int32 starting_index]).Int32
  - Returns the first index that the given value occurs at starting at index 0 by default. (-1) is returned if 'value' is not found.
- last_index_of(Char value[,Int32 starting_index]).Int32
  - Returns the last index that the given value occurs at starting at index (count-1) by default. (-1) is returned if 'value' is not found.
- contains(Char value).Logical
  - Returns "true" if this data contains the given value.
- indices().Range<<Int32>>
  - Returns this data's range of indices (0..count-1).
- reverse_indices().Range<<Int32>>
  - Returns this data's range of indices reversed (count-1 downTo 0).
  - Example:
```
  local Int32[] nums = {5..7}
  forEach (i in nums.reverse_indices) println( i )
    # prints: 2 | 1 | 0
```
- to_List().Char[]
  - Converts this indexed data into a list.
- to_bytes().Byte[]
  - Converts this 16-byte character data into a list of 8-bit byte data. The upper 8 bits of each original Char are lost.
- create_reader().Reader<<Char>>
  - Returns a reader that can be used to read() this data one element at a time.
- from(Int32 starting_index).Reader<<Char>>
  - Returns a reader that can be used to read() this data one element at a time with the given 'starting_index'.
- from(Range<<Int32>> range).Reader<<Char>>
  - Returns a reader that can be used to read() this data one element at a time from the given starting index up to and including the ending index.
- reverse_order().Reader<<Char>>
  - Returns a reader that can be used to read() this data one element at a time from the last element (N-1) to the first (0).
- format(String prefix,String prepeat,String suffix).String
  - Converts this list into a string using the following format:
  - ```
    prefix + $0 + [prepeat + $N]* + suffix
```
  where "$0" is the first element and $N is every other element.
- Example:
- ```
  local Int32[] nums = 11..15
  println( nums.to_String("[", "+", "]") )
  # prints: [11+12+13+14+15]
```
- format(String str_format[,String repeater_chars]).String
  - Easier convenience method to accomplish to_String(prefix,prepeat,suffix).
  - Breaks down a simple format like this:
  - ```
    {$[ or $]}
```
  Into a prefix="{", prepeat=" or ", suffix="}".
- Normally "[]" brackets are used to denote the repeater portion, but this may be specified otherwise.
- Example:
- ```
  local Int32[] nums = 11..15
  println( nums.to_String( "[$:+$:]", ":" )
  # prints: [11+12+13+14+15]

  println( nums.to_String( "{$[,$]}" )
  # prints: {11,12,13,14,15}
```
- substring(Int32 i1,Int32 i2).String
  - Returns the sequence of characters in the range [first_index,last_index], inclusive. Note that this differs from Java by having the second parameter be inclusive rather than exclusive.
  - Requires:
```
  first_index >= 0
  last_index < count
  first_index <= last_index
```
- type_name().String : native
- runtime_type().RuntimeType : native
- runtime_properties().RuntimeProperties
- runtime_methods().RuntimeMethods

StringBuilder
class : TextWriter, Char[]

DESCRIPTION
- Class for composing Strings. Using a StringBuilder is more efficient than concatenating Strings ("a" + "b") when three or more concatenations are involved.
- Example:
```
  local Int32 x = 5
  local StringBuilder buffer()
  buffer.print( "The value of x is " )
  buffer.print( x )
  buffer.print( "!" )
  println( buffer.to_String )  # prints: The value of x is 5!
```
  Note: StringBuilder inherites all the variations of print() and println() from base class TextWriter.
PROPERTIES
- modification_count : Int32
- data : ArrayList<<Char>>
  - The internal character buffer.
METHODS
- init([Int32 capacity])
  - Initializes this StringBuffer to be able to store 'capacity' (default 80) characters before having to automatically resize.
- init(Char ch)
  - Initializes this StringBuilder to the default size and store the given character 'ch'.
- init(String st)
  - Initializes this StringBuilder to contain the string 'st' to start with.
- add(String st).StringBuilder
  - Primarily used for internal call chaining - using print() or println() is a more efficient way to write strings.
  - Example:
```
  local StringBuilder buffer()
  buffer.add(alpha).add(beta)
```
- print(String st)
  - Prints the given String to this StringBuilder. A more efficient override of the base class value.
- write(Char ch)
  - Fundamental write operation that all the TextWriter methods depend on.
- count().Int32
  - Returns the number of characters printed to this StringBuilder so far.
- get(Int32 i).Char
  - Returns the character at zero-based index 'i'.
- set(Int32 i,Char value)
  - Sets the character at zero-based index 'i'.
- insert(Char value,Int32 before_index).StringBuilder
  - Inserts the given character before the given index.
- remove(Int32 index).Char
  - Removes the character at 'index' and shifts characters down to close the gap.
- print(Null n).String
- init_object()
- create_duplicate().Object
  - Should create a duplicate of this object such that obj1.op==(obj1.create_duplicate) return true.
  - The command duplicate(obj) is transformed by the compiler into Object.create_duplicate(obj), which then calls this method.
  - For optimal performance (by removing an internal typecast in most situations), have your overridden create_duplicate have the same return type as the class it's defined in. For instance, Strings implementation is 'create_duplicate.String'.
  - This default implementation throws an UnsupportedMethodError.
- capacity().Int32
  - Returns the minimum number of additional values that can written with this writer, or (-1) for "unlimited".
- create_reader().Reader<<Char>>
  - Creates and returns a reader capable of reading the data from this object.
- to_bytes().Byte[]
  - Turns this Readable Char data into a Byte[] list. Available for Readable<<Char>> types only.
- first().Char
  - Returns the first element of this data. This convenience method is equivalent to get(0).
- last().Char
  - Returns the last element of this data. This convenience method is equivalent to get(count-1).
- end(Int32 from_end).Char
  - Equivalent to get( (count-1) + from_end ).
  - For example, end(0) is equivalent to last() and end(-1) is equivalent to get(count-2).
- random().Char
  - Returns an element of this data at random.
- random_index().Int32
  - Returns the index of a randomly selected element.
- is_empty().Logical
  - Returns true if count == 0.
- is_not_empty().Logical
  - Returns true if count > 0.
- index_of(Char value[,Int32 starting_index]).Int32
  - Returns the first index that the given value occurs at starting at index 0 by default. (-1) is returned if 'value' is not found.
- last_index_of(Char value[,Int32 starting_index]).Int32
  - Returns the last index that the given value occurs at starting at index (count-1) by default. (-1) is returned if 'value' is not found.
- contains(Char value).Logical
  - Returns "true" if this data contains the given value.
- indices().Range<<Int32>>
  - Returns this data's range of indices (0..count-1).
- reverse_indices().Range<<Int32>>
  - Returns this data's range of indices reversed (count-1 downTo 0).
  - Example:
```
  local Int32[] nums = {5..7}
  forEach (i in nums.reverse_indices) println( i )
    # prints: 2 | 1 | 0
```
- from(Int32 starting_index).Reader<<Char>>
  - Returns a reader that can be used to read() this data one element at a time with the given 'starting_index'.
- from(Range<<Int32>> range).Reader<<Char>>
  - Returns a reader that can be used to read() this data one element at a time from the given starting index up to and including the ending index.
- reverse_order().Reader<<Char>>
  - Returns a reader that can be used to read() this data one element at a time from the last element (N-1) to the first (0).
- format(String prefix,String prepeat,String suffix).String
  - Converts this list into a string using the following format:
  - ```
    prefix + $0 + [prepeat + $N]* + suffix
```
  where "$0" is the first element and $N is every other element.
- Example:
- ```
  local Int32[] nums = 11..15
  println( nums.to_String("[", "+", "]") )
  # prints: [11+12+13+14+15]
```
- format(String str_format[,String repeater_chars]).String
  - Easier convenience method to accomplish to_String(prefix,prepeat,suffix).
  - Breaks down a simple format like this:
  - ```
    {$[ or $]}
```
  Into a prefix="{", prepeat=" or ", suffix="}".
- Normally "[]" brackets are used to denote the repeater portion, but this may be specified otherwise.
- Example:
- ```
  local Int32[] nums = 11..15
  println( nums.to_String( "[$:+$:]", ":" )
  # prints: [11+12+13+14+15]

  println( nums.to_String( "{$[,$]}" )
  # prints: {11,12,13,14,15}
```
- op+(Char value).Char[]
  - Adds the given value to each of this object's values and returns a list of the results.
- op+(Readable<<Char>> values).Char[]
  - Adds each of the given values to each of this object's corresponding values and returns a list of the results.
- op-(Char value).Char[]
  - Subtracts the given value from each of this object's values and returns a list of the results.
- op-(Readable<<Char>> values).Char[]
  - Subtracts each of the given values from each of this object's corresponding values and returns a list of the results.
- op*(Char value).Char[]
  - Multiplies the given value by each of this object's values and returns a list of the results.
- op*(Readable<<Char>> values).Char[]
  - Multiplies each of the given values by each of this object's corresponding values and returns a list of the results.
- op/(Char value).Char[]
  - Divides each of this object's values by the given value and returns a list of the results.
- op/(Readable<<Char>> values).Char[]
  - Divides each of this object's values by each of the corresponding given values and returns a list of the results.
- op%(Char value).Char[]
  - Returns a list of the remainders of each of this object's values divided by the given value.
- op%(Readable<<Char>> values).Char[]
  - Returns a list of the remainders of each of this object's values divided by each of the corresponding given values.
- op^(Char value).Char[]
  - Raises each of this object's values by the given value and returns a list of the results.
- op^(Readable<<Char>> values).Char[]
  - Raises each of this object's values by each of the corresponding given values and returns a list of the results.
- op-().Char[]
  - Returns a list containing the negative of each value in this object.
- op<>(Char value).Logical[] {multimethod}
  - Compares each of this object's values to the given value and returns a list of Logical 'gt', 'lt', and 'eq' values.
- op<>(Readable<<Char>> values).Logical[] {multimethod}
  - Compares each of this object's values to each corresponding given value and returns a list of Logical 'gt', 'lt', and 'eq' values.
- sum().Char
  - Returns the sum of all the values contained in this list-adaptable object.
- product().Char
  - Returns the product of all the values contained in this list-adaptable object.
- min().Char
  - Returns the lowest value in this list.
- max().Char
  - Returns the highest value in this list.
- op&(Char value).Char[]
  - Performs a bitwise 'and' operation between each of this object's values and the given value and returns a list of results.
  - Only implemented for integer and Logical ListAdaptable types.
- op&(Readable<<Char>> values).Char[]
  - Performs a bitwise 'and' operation between each of this object's values and each corresponding given value and returns a list of results.
  - Only implemented for integer and Logical ListAdaptable types.
- op|(Char value).Char[]
  - Performs a bitwise 'or' operation between each of this object's values and the given value and returns a list of results.
  - Only implemented for integer and Logical ListAdaptable types.
- op|(Readable<<Char>> values).Char[]
  - Performs a bitwise 'or' operation between each of this object's values and each corresponding given value and returns a list of results.
  - Only implemented for integer and Logical ListAdaptable types.
- op~(Char value).Char[]
  - Performs a bitwise 'xor' operation between each of this object's values and the given value and returns a list of results.
  - Only implemented for integer and Logical ListAdaptable types.
- op~(Readable<<Char>> values).Char[]
  - Performs a bitwise 'xor' operation between each of this object's values and each corresponding given value and returns a list of results.
  - Only implemented for integer and Logical ListAdaptable types.
- op!().Char[]
  - Returns a list containing the logical complement of each value in this object.
  - Only implemented for integer and Logical ListAdaptable types.
- set(Readable<<Logical>> element_flags,Readable<<Char>> values)
  - Starting at index 0, sets each element to the next of the given 'values' if the corresponding 'element_flags' are true.
  - Example:
```
  local Int32[] nums = {1..5}
  nums[nums%2==1] = -nums
  println( nums )  # prints: {-1,2,-3,4,-5}
```
- set(Readable<<Logical>> flags,Char value)
  - Starting at index 0, sets each element to the given 'value' if the corresponding 'element_flags' are true.
  - Example:
```
  local Int32[] nums = {1..5}
  nums[nums%2==1] = 0
  println( nums )  # prints: {0,2,0,4,0}
```
- set(Readable<<Int32>> indices,Char value)
  - Sets the element at each of the given 'indices' to the given 'value'.
  - Example:
```
  local Int32[] nums = {1..5}
  nums[{0,4}] = nums[{4,0}]
  println( nums )
    # prints: {5,2,3,4,1}
```
- set(Readable<<Int32>> indices,Readable<<Char>> values)
  - Sets the element at each of the given 'indices' to each of the corresponding 'values'.
  - Requires:
```
  The number of indices == the number of values.
```
    Example:
```
  local Int32[] nums = {1..5}
  nums[0..4 step 2] = {7,8,9}
  println( nums )
    # prints: {7,2,8,4,9}
```
- get(Readable<<Logical>> flags).Char[]
  - Returns a new list containing the subset of elements of which each of the corresponding 'flags' is true.
  - Example:
```
  local Int32[] nums = {1..10}
  println( nums[nums % 2 == 0] )
    # prints: {2,4,6,8,10}
```
- get(Readable<<Int32>> indices).Char[]
  - Gets the element at each of the given zero-based 'indices'.
  - Example:
```
  local Int32[] nums = {1..5}
  nums[{0,4}] = nums[{4,0}]
  println( nums )
    # prints: {5,2,3,4,1}
```
- swap(Int32 index_a,Int32 index_b)
  - Swaps the value at 'index_a' with the one at 'index_b'.
  - Requires:
```
  0 <= index_a < count
  0 <= index_b < count
```
    Invariant:
```
  this[index_a] = old[index_b]
  this[index_b] = old[index_a]
```
- op==(Readable<<Char>> other).Logical {multimethod}
  - Returns true if each element of this data op==() each corresponding element from in 'other'.
- op==(Char value).Logical[] {multimethod}
  - Returns a list of Logical values where each value true if the corresponding element of this indexed data op==() the given value.
- subset(Int32 first_index,Int32 last_index).Char[]
  - Returns the subset of this data between indices [first_index,last_index] inclusive.
- shuffle()
  - Swaps every element of this data with another element at a randomly-chosen position.
- shuffled().IndexedData<<Char>>
  - Returns a shuffled copy of this data.
- reverse()
  - Reverses the order of the elements in this data.
- reversed().IndexedData<<Char>>
  - Returns an list containing the elements of this data in reverse order.
- sort([Sort order][,Comparator<<Char>> comparator])
  - Sorts this list in place using a HeapSort.
  - 'order' is Sort.ascending by default.
  - 'comparator' is an optional functor that compares two values and returns whether the first argument is "lt", "eq", or "gt" the second argument.
  - Only implemented for numerical and String lists. To enable it for lists of other types (say, Event), add this augment:
```
  augment List<<Event>>
    METHODS
      method sort( Sort order=Sort.ascending ):
        HeapSort<<DataType>>.sort( this, order )
  endAugment
```
- sorted([Sort order][,Comparator<<Char>> comparator]).Char[]
  - Returns an list containing the elements of this data sorted into order. Only implemented for numerical and String lists.
  - 'order' is Sort.ascending by default.
  - 'comparator' is an optional functor that compares two values and returns whether the first argument is "lt", "eq", or "gt" the second argument.
- modification_count().Int32
  - Returns a counter representing the number of times items has been added to or removed. Used by readers to detect concurrent list modification errors. For example, when an inner method removes an item from a list the modification counter is incremented. An outer "forEach" loop will detect that the count is different from its original value and throw a ConcurrentListModification error.
- ensure_capacity(Int32 desired_capacity)
  - Directs a list to prepare itself to hold a total of 'desired_capacity' elements. Proper use prevents ArrayLists from having to resize their data structures multiple times over the course of an operation.
- ensure_count(Int32 num_items)
  - Increases the size of this list by enough null/zero items so that its count is at least 'num_items'.
  - Default implementation.
- add(Char value).Char[]
  - Appends 'value' to the end of this list.
  - Returns a reference to this list for call-chaining, e.g.:
  - ```
    list.add(3).add(4).add(5)
```
  Invariant:
```
    new.count == old.count + 1
    new.last is value
```
- add(Char value,Int32 after_index).Char[]
  - Inserts 'value' after the given index.
  - Returns:
```
  A reference to this list for call-chaining.
```
    Requires:
```
  after_index >= -1 and after_index < count
```
    Invariant:
```
  new.count          == old.count + 1
  new[after_index+1] == value
```
- add(Readable<<Char>> source).Char[]
  - Adds each item from the Readable source to this list.
  - Returns a reference to this list for call-chaining.
- insert(IndexedData<<Char>> seq[,Int32 before_index]).Char[]
  - Inserts all the given values in front of 'before_index'. Elements at 'begin_index' and higher are logically shifted up by one.
  - Returns:
```
  A reference to this list for call chaining.
```
    Requires:
```
  0 <= before_index and before_index <= count
```
    Invariant:
```
  this[before_index]   = value
  this[before_index+seq.count] = old[before_index]
  count = old.count + seq.count
```
    naive default implementation
- copy_from(Readable<<Char>> source).Char[]
  - Equivalent to:
```
  list.clear
  list.add( source )
```
- transfer_from(Char[] source).Char[]
  - Equivalent to:
```
  list.clear
  list.add( source )
  source.clear
```
- to_List().Char[]
  - Satisifies the ListAdaptable aspect of the IndexedData aspect by returning this list with no modifications.
- remove(Int32 first,Int32 last).Char[]
  - Removes and returns the elements in the specified range. See discard() for a variant that's optimal when you don't need the return value.
  - 'first' and 'last' are clipped to be a valid range.
  - Returns:
```
  The list of elements from old[first] through old[last].
```
    This default implementation is non-optimal.
- remove(Range<<Int32>> range).Char[]
  - Removes and returns the elements in the specified range. See discard() for a variant that's optimal when you don't need the return value.
  - Requires: range.is_contiguous_ascending
- remove_first().Char
  - Equivalent to:
```
  list.remove(0)
```
- remove_last().Char
  - Equivalent to:
```
  list.remove(list.count-1)
```
- remove_value(Char value).Logical
  - Removes the first occurrence of 'value' from the list.
  - Returns:
```
  "true" if an occurrence of 'value' was found
  and removed, or "false" if it was not found.
```
    Technical note: this method can't be named remove() because in an Int32[] list, remove(index) and remove(value) would have the same signature.
- discard(Int32 first[,Int32 last])
  - Removes the elements in the specified range. Does not return the list of removed elements like remove() does. If only the 'first' parameter is given, elements from 'first' to the end of the list are discarded.
  - 'first' and 'last' are clipped to be a valid range.
  - This default implementation is non-optimal.
- discard(Range<<Int32>> range)
  - Removes elements in the specified range.
  - Requires: range.is_contiguous_ascending
- discard_first()
  - Removes the first element in the list without returning it.
  - This default implementation is non-optimal.
- discard_last()
  - Removes the last element in the list without returning it.
- discard_first(Int32 n)
  - Removes 'n' elements from the front of the list. Does not return the list of removed elements like remove() does.
  - This default implementation is non-optimal.
- discard_last(Int32 n)
  - Removes 'n' elements from the end of the list. Does not return the list of removed elements like remove() does.
  - This default implementation is non-optimal.
- modification_count(Int32 modification_count.839)
- clear()
  - Clears all the characters from this StringBuilder.
- to_String().String
  - Converts the data in this StringBuilder to a String.
- hash_code().Int32
- op==(Object other).Logical {multimethod}
- op<>(Object other).Logical {multimethod}
- type_name().String : native
- runtime_type().RuntimeType : native
- runtime_properties().RuntimeProperties
- runtime_methods().RuntimeMethods
- write(Reader<<Char>> src)
- holds_another().Logical
- position().Int32
- position(Int32 new_pos)
- skip(Int32 skip_count)
- flush()
- close()
- clean_up()
- print(Char ch)
- print(Object obj)
- print(Int64 n)
- print(Byte n)
- print(Real64 n)
- print(Real32 n)
- print(Logical n)
- println(String st)
- println(Object obj)
- println(Int64 n)
- println(Byte n)
- println(Char n)
- println(Real64 n)
- println(Logical n)
- println()
- print(Reader<<Char>> reader)
- println(Reader<<Char>> reader)
- print(ParsePos p)
- println(ParsePos p)

Navigation

User login

Strings

Overview

Formatted Strings