3.17. kink/STR

Companion mod for str vals.

3.17.1. type str

A str is a finite immutable sequence of Unicode codepoints. Codepoints are called runes in Kink, likewise in Go.

Str.op_add(Arg_str)

Str.op_add makes a str containing the runes of Str on the front, and the runes of Arg_str on the back.

Arg_str must be a str

Example:

:Str <- 'foo' + 'bar'
stdout.print_line(Str.repr) # => "foobar"

Str.encode(Encoding_name)

Str.encode makes a bin encoding the Str using the character encoding.

Encoding_name must be a str of a valid character encoding on the runtime.

Example:

:Bin <- 'xyz'.encode('UTF-8')
stdout.print_line(Bin.repr) # => BIN.of(0x78 0x79 0x7a)

Str.runes

Str.runes returns a vec of the runes of the Str.

Example:

stdout.print_line('xyz'.runes.repr) # => [120 121 122]

Str.empty?

Str.empty? returns whether the Str contains one or more runes.

Str.nonempty?

Str.nonempty? returns whether the Str contains no runes.

Str.size

Str.size returns the number of runes in the Str.

The result is an int num.

Str.get(Rune_index)

Str.get returns the rune specified by Rune_index.

The result is an int num which represents the rune.

Example:

stdout.print_line('xyz'.get(0).repr) # => 120

Str.slice(From_pos To_pos)

Str.slice returns the specified slice of the Str.

Preconditions:

• From_pos and To_pos must be int nums in the range [0, Str.size]

• From_pos must be less than or equal to To_pos

The result is a str the runes of which are copied from the slice of the Bin.

Example:

:Str <- 'foobar'
:Slice <- Str.slice(1 4)
stdout.print_line(Slice.repr) # => "oob"

Str.take_front(N)

Str.take_front makes a str containing the first N runes of the Str.

N must be an int num in the range [0, Str.size].

Example:

stdout.print_line('foobar'.take_front(2).repr)  # => "fo"

Str.take_back(N)

Str.take_back makes a str containing the last N runes of the Str.

N must be an int num in the range [0, Str.size].

Example:

stdout.print_line('foobar'.take_back(2).repr)  # => "ar"

Str.drop_front(N)

Str.drop_front makes a str dropping the first N runes of the Str.

N must be an int num in the range [0, Str.size].

Example:

stdout.print_line('foobar'.drop_front(2).repr)  # => "obar"

Str.drop_back(N)

Str.drop_back makes a str dropping the last N runes of the Str.

N must be an int num in the range [0, Str.size].

Example:

stdout.print_line('foobar'.drop_back(2).repr)  # => "foob"

Str.search_slice(Min_ind Slice)

Str.search_slice searches the Slice in the Str.

Preconditions:

• Min_rune_ind must be an int num in the range [0, Str.size]

• Slice must be a str

Str.search_slice tries to find the smallest Ind which is >= Min_ind, such that Str.slice(Ind Slice.size) is equal to Slice.

If such an Ind is found, Str.search_slice returns a vec [Ind].

If not found, Str.search_slice returns an empty vec [].

Example:

:attempt_search <- {(:Str :Min_ind :Slice)
  Str.search_slice(Min_ind Slice).each_or(
    {(:Ind) stdout.print_line('found at: {}'.format(Ind.repr)) }
    { stdout.print_line('not found') }
  )
}
attempt_search('foofoo' 0 'oo')  # => found at: 1
attempt_search('foofoo' 1 'oo')  # => found at: 1
attempt_search('foofoo' 2 'oo')  # => found at: 4
attempt_search('foofoo' 3 'oo')  # => found at: 4
attempt_search('foofoo' 4 'oo')  # => found at: 4
attempt_search('foofoo' 5 'oo')  # => not found
attempt_search('foofoo' 6 'oo')  # => not found

Str.have_prefix?(Prefix)

Str.have_prefix? returns whether the Str has the slice Prefix at the front.

Prefix must be a str.

If Str.slice(0 Prefix.size) is equal to Prefix, Str.have_prefix? returns true. If not, Str.have_prefix? returns false.

Str.have_suffix?(Suffix)

Str.have_suffix? returns whether the Str has the slice Suffix at the back.

Suffix must be a str.

If Str.slice(Str.size - Suffix.size Str.size) is equal to Suffix, Str.have_suffix? returns true. If not, Str.have_suffix? returns false.

Str.have_slice?(Slice)

Str.have_slice? returns whether the Str has the Slice.

Slice must be a str.

If there is an Ind such that Str.slice(Ind Ind+Slice.size) is equal to Slice, Str.have_slice? returns true. If not, Str.have_slice? returns false.

Str.trim

Str.trim returns a slice of the Str trimming space-like characters from the front and the back.

Str.trim returns the longest slice of the Str which does not start with the Rune smaller than or equal to 32 (whitespace character), and does not end with the Rune smaller than or equal to 32.

Exaample:

stdout.print_line(" \t\r\nfoobar\n\r\t ".trim.repr) # => "foobar"
stdout.print_line(" \t\r\n\n\r\t ".trim.repr)       # => ""

Str.format(... Args)

Str.format makes a str with the Str as a template.

Calling Str.format is equivalent to calling kink/FORMAT.format, in the form FORMAT.format(Str){(:F) F.args(... Args) }.

Example:

stdout.print_line('{} == 0x{%04x}'.format(42 42))
# Output:
#   42 == 0x1a

stdout.print_line('{}: got an arg: {}'.format('WARN' 'something went wrong'))
# Output:
#   INFO: got an arg: "something went wrong"

Str.op_mul(N)

Str.op_mul makes a str repeating the Str N times.

N must be a nonnegative int num.

Example:

stdout.print_line(('foo' * 0).repr) # => ""
stdout.print_line(('foo' * 1).repr) # => "foo"
stdout.print_line(('foo' * 2).repr) # => "foofoo"
stdout.print_line(('foo' * 3).repr) # => "foofoofoo"

Str.op_eq(Arg_str) Str.op_ne(Arg_str)

Str.op_eq and op_ne returns whether or not two strs contains the same sequence of runes.

Arg_str must be a str.

Example:

stdout.print_line(('foo' == 'foo').repr)  # => true
stdout.print_line(('foo' != 'foo').repr)  # => false

stdout.print_line(('foo' == 'FOO').repr)  # => false
stdout.print_line(('foo' != 'FOO').repr)  # => true

Str.op_lt(Arg_str) Str.op_le(Arg_str) Str.op_gt(Arg_str) Str.op_ge(Arg_str)

Str.op_lt, op_le, op_gt and op_ge compare the runes of the strs lexicographically, then return true or false.

Arg_str must be a str.

Example:

:compare <- {(:Str :Arg_str)
  [:Lt? :Le? :Gt? :Ge?] = [
    Str < Arg_str
    Str <= Arg_str
    Str > Arg_str
    Str >= Arg_str
  ]
  stdout.print_line(
    'Lt?={} Le?={} Gt?={} Ge?={}'.format(Lt?.repr Le?.repr Gt?.repr Ge?.repr))
}

compare('foo' 'foo')  # => Lt?=false Le?=true Gt?=false Ge?=true
compare('foo' 'fooo') # => Lt?=true Le?=true Gt?=false Ge?=false
compare('foo' 'fo')   # => Lt?=false Le?=false Gt?=true Ge?=true

Note that the result of comparison may differ from java.lang.String.compareTo. The reason is that the Java method compares strings by UTF-16 units.

:JAVA.require_from('kink/host_lang/java/')
:X <- "\x{00ffff}"
:Y <- "\x{010302}"
stdout.print_line((X < Y).repr)  # => true
stdout.print_line(
  (JAVA.string(X).call_method('compareTo' JAVA.string(Y)).to_kink_num < 0).repr
)  # => false

Str.show(...[$config={}])

Str.show returns the Str itself.

Str.show can take an optional parameter $config, but it is never used. This parameter exists in order to meet the expectation by kink/FORMAT.format.

Example:

stdout.print_line('xyz'.show)
# Output:
#   xyz

stdout.print_line('xyz'.show{})
# Output:
#   xyz

stdout.print_line("foo\nbar".show)
# Output:
#   foo
#   bar

Str.repr

Str.repr returns the str representation of the Str for debugging, such as "xyz" and "foo\nbar".

Example:

stdout.print_line('xyz'.repr)       # => "xyz"
stdout.print_line("foo\nbar".repr)  # => "foo\nbar"

3.17.2. STR.str?(Val)

STR.str? returns whether the Val is a str val.

3.17.3. STR.of_runes(Runes)

STR.of_runes makes a str which contains the Runes.

Runes must be a vec of int nums in the range [0x000000, 0x10ffff].

Example:

:STR.require_from('kink/')
:Str <- STR.of_runes([120 121 122])
stdout.print_line(Str.repr) # => "xyz"