# Strings

Operators and functions for working with strings (**str** type) are described here.

* [bool( str s ) bool](#bool-str-s-bool)
* [float( str s ) float](#float-str-s-float)
* [int( str s ) int](#int-str-s-int)
* [Find( str s, str substr ) int](#find-str-s-str-substr-int)
* [Format( str s, anytype args... ) str](#format-str-s-anytype-args-str)
* [HasPrefix( str s, str prefix ) bool](#hasprefix-str-s-str-prefix-bool)
* [HasSuffix( str s, str suffix ) bool](#hassuffix-str-s-str-suffix-bool)
* [Left( str s, int i ) string](#left-str-s-int-i-str)
* [Lines( str s ) arr.str](#lines-str-s-arrstr)
* [Lower( str s ) string](#lower-str-s-str)
* [Repeat( str s, int count ) str](#repeat-str-s-int-count-str)
* [Replace( str s, str old, str new ) str](#replace-str-s-str-old-str-new-str)
* [Right( str s, int i ) string](#right-str-s-int-i-str)
* [Size( int size, str format ) string](#size-int-size-str-format-str)
* [Split( str s, str sep ) arr.str](#split-str-s-str-sep-arrstr)
* [Substr( str s, int off, int length ) str](#substr-str-s-int-off-int-length-str)
* [Trim( str s, str cutset ) str](#trim-str-s-str-cutset-str)
* [TrimLeft( str s, str cutset ) str](#trimleft-str-s-str-cutset-str)
* [TrimRight( str s, str cutset ) str](#trimright-str-s-str-cutset-str)
* [TrimSpace( str s ) str](#trimspace-str-s-str)
* [Upper( str s ) string](#upper-str-s-str)

## Operators

| Operator             | Result | Description                                                                                       |
| -------------------- | ------ | ------------------------------------------------------------------------------------------------- |
| str **+** str        | str    | Merges two strings.                                                                               |
| **\*** str           | int    | Returns the length of the string.                                                                 |
| str **?**            | bool   | Calls *bool(str)*.                                                                                |
| **\|** str           | str    | This unary operator trims whitespace characters in the each line of the string.                   |
| str **==** str       | bool   | Returns *true* if the two strings are equal and *false*, otherwise.                               |
| str **>** str        | bool   | Returns *true* if the first string is greater than the second and *false*, otherwise.             |
| str **<** str        | bool   | Returns *true* if the first string is less than the second and *false*, otherwise.                |
| str **!=** str       | bool   | Returns *true* if the two strings are not equal and *false*, otherwise.                           |
| str **>=** str       | bool   | Returns *true* if the first string is greater than or equal to the second and *false*, otherwise. |
| str **<=** str       | bool   | Returns *true* if the first line is less than or equal to the second and *false*, otherwise.      |
| str **=** str        | str    | Assignment operator.                                                                              |
| str **=** int        | str    | Converts an integer to a string and assigns it to a variable.                                     |
| str **=** bool       | str    | Assigns "true" or "false".                                                                        |
| str **+=** str       | str    | Appends a string to a string variable.                                                            |
| str **\[** int **]** | int    | Sets/gets Unicode code by index.                                                                  |

## Functions

### bool(str s) bool

The *bool* function returns *false* if the string is empty, "0" or "false", otherwise, it returns *true*.

### float(str s) float

The *float* function converts a string to a number of *float* type. If the string has the wrong format, an error is returned.

### int(str s) int

The *int* function converts a string to an integer number. If the string has the wrong format, an error is returned.

### Find(str s, str substr) int

The *Find* function returns the index of the first instance of *substr* in *s*, or -1 if *substr* is not present in *s*.

### Format(str s, anytype args...) str

The *Format* function formats according to a *s* specifier and returns the resulting string. There are the following format verbs:

#### General

* **%v** - the value in a default format
* **%%** - a literal percent sign; consumes no value

#### bool

* **%t** -    the word true or false

#### int

* **%b** - base 2
* **%c** - the character represented by the corresponding Unicode code point
* **%d** - base 10. This is the default format for *int*.
* **%o** - base 8
* **%x** - base 16, with lower-case letters for a-f
* **%X** - base 16, with upper-case letters for A-F
* **%U** - Unicode format: U+1234

#### float

* **%e** - scientific notation, e.g. -1.234456e+78
* **%E** - scientific notation, e.g. -1.234456E+78
* **%f** - decimal point but no exponent, e.g. 123.456. You can specify the width and the precision like *%\[width].\[precision]f* - *%8.2f, %.3f, %7f*.
* **%g** - %e for large exponents, %f otherwise. Precision is discussed below. This is the default format for *float*.

#### str

* **%s** - the default format for strings
* **%x** - base 16, lower-case, two characters per byte
* **%X** - base 16, upper-case, two characters per byte

You can specify i-th argument in the format string like this - *Format("%d %\[1]d %\[1]d", 10)*

```
arr.int mya = {1,2,3}
time t
Format(`%s %v %v %g %6.2[4]f`, `ok`, mya, Now(t), 99.0 + 1.)
```

### HasPrefix(str s, str prefix) bool

The *HasPrefix* function returns *true* if the string *s* begins with *prefix*.

### HasSuffix(str s, str suffix) bool

The *HasSuffix* function returns *true* if the string *s* ends with *suffix*.

### Left(str s, int i) str

The *Left* function extracts a given number of characters from the left side of the string *s*.

### Lines(str s) arr.str

The *Lines* function slices *s* multi-line string into all substrings separated by new line. All substrings are returned as an array of strings.

### Lower(str s) str

The *Lower* function converts a copy of *s* string to lower case and returns it.

### Repeat(str s, int count) str

The *Repeat* function returns a new string consisting of *count* copies of the string *s*.

### Replace(str s, str old, str new) str

The *Replace* function returns a copy of the string *s* with all *old* strings replaced by *new* string.

### Right(str s, int i) str

The *Right* function returns a substring of the last *i* characters of the *s* string.

### Size(int size, str format) str

The *Size* function returns the rounded size as a string. In the *format* parameter specify an output pattern for a decimal floating-point number and a string. If *format* is an empty string, the format *%.2f%s* is used.

```go
Print( Size(956348901, `%.1f %s `) + Size(62, `%[2]s%.2[1]f `) + Size(123789, ``))
// 912.0 MB B62 120.89KB
```

### Split(str s, str sep) arr.str

The *Split* function slices *s* string into all substrings separated by *sep* string. All substrings are returned as an array of strings.

### Substr(str s, int off, int length) str

The *Substr* function returns a substring of the string *s* with the specified offset and length.

### Trim(str s, str cutset) str

The *Trim* function returns a substring of the string *s*, with all leading and trailing Unicode code points contained in *cutset* removed.

### TrimLeft(str s, str cutset) str

The *TrimLeft* function returns a substring of the string *s*, with all leading Unicode code points contained in *cutset* removed.

### TrimRight(str s, str cutset) str

The *TrimRight* function returns a substring of the string *s*, with all trailing Unicode code points contained in *cutset* removed.

### TrimSpace(str s) str

The *TrimSpace* function returns a substring of the string *s*, with all leading and trailing white space removed.

### Upper(str s) str

The *Upper* function converts a copy of *s* string to upper case and returns it.