# Package: Collections-Strings

## Class: String

### Introduction

**Environment: `container`** **Super class**: `Array`

A String is an indexed collection of Characters.

A String is a sequence of characters. It is a subclass of Array, and therefore inherits all the Array operations.

You can compare strings using the operator `=`, `>=,` >', `<`, `<=`. For example:

```smalltalk
'a' < 'b'.
'a' = 'a'.
'b' >= 'a'.
```

You can also concatenate strings using the `,` operator. For example:

```smalltalk
"It concatenates them as 'This is a string.'"
'This is', ' a string.'.
```

Actually you can concatenate any two objects to a string. For example:

```smalltalk
10, ' is a number.'. "10 is a number."
```

To concatenate strings with new line, you can use `String crlf` or `String lf`. For example:

```smalltalk
lines := 'This is a string.', String crlf, 'This is another string.'.
```

### Class Method

#### Category: instance creation

* **`cr`** - Answer a string containing a single carriage return character.

  ```smalltalk
  aStringWithCR := 'a string' , String cr , 'with a carriage return'.
  ```
* **`crlf`** - Answer a string containing a carriage return and a linefeed.

  ```smalltalk
  aStringWithCRLF := 'a string' , String crlf , 'with a carriage return and a linefeed'.
  ```
* **`lf`** - Answer a string containing a linefeed character.

  ```smalltalk
  aStringWithLF := 'a string' , String lf , 'with a linefeed'.
  ```
* **`tab`** - Answer a string containing a single tab character.

  ```smalltalk
  aStringWithTAB := 'a string' , String tab , 'with a tab'.
  ```

### Instance Method

#### Category: accessing

* **`replaceAll:with:`** - replace all occurrences of a substring with another string

  For example:

  ```smalltalk
  "newString = Thwas was a string"
  newString := 'This is a string' replaceAll: 'is' with: 'was' .
  " replace ' with ", we need to double the ' in the string to represent a single '.
   newString = There"s a problem"
  newString := 'There''s a problem' replaceAll: '''' with: '"'.
  ```

#### Category: combining

* **`+`** - Concatenate two strings.

#### Category: comparing

* **`<`** - answer whether the receiver sorts before aString. The collation order is simple ascii (with case differences)

  It compares two strings lexicographically, which means that it compares the strings character by character, according to the Unicode value of each character. If the first string is lexicographically less than the second string, the method answers true, otherwise it answers false.

  For example:

  ```smalltalk
  ('a' < 'a') = false.
  ('a' < 'b') = true.
  ('aaa' < 'aab') = true.
  ('c' < 'b') = false.
  ```
* **`<=`** - answer whether the receiver sorts before or equal to aString. The collation order is simple ascii (with case differences).

  It compares two strings lexicographically, which means that it compares the strings character by character, according to the Unicode value of each character. If the first string is lexicographically less than or equal with the second string, the method answers true, otherwise it answers false.

  For example:

  ```smalltalk
  ('a' <= 'a') = true.
  ('a' <= 'b') = true.
  ('aaa' <= 'aab') = true.
  ('c' <= 'b') = false.
  ```
* **`=`** - answer whether the receiver sorts equally as aString. The collation order is simple ascii (with case differences).

  For exmaple:

  ```smalltalk
  ('aa' = 'bb') = false.
  ('aa' = 'aa') = true.
  ```
* **`>`** - answer whether the receiver sorts after aString. The collation order is simple ascii (with case differences).

  It compares two strings lexicographically, which means that it compares the strings character by character, according to the Unicode value of each character. If the first string is lexicographically greater than the second string, the method answers true, otherwise it answers false.

  For example:

  ```smalltalk
  ('a' > 'a') = false.
  ('a' > 'b') = false.
  ('aab' > 'aaa') = true.
  ('c' > 'b') = true.
  ```
* **`>=`** - answer whether the receiver sorts after or equal to aString. The collation order is simple ascii (with case differences).

  It compares two strings lexicographically, which means that it compares the strings character by character, according to the Unicode value of each character. If the first string is lexicographically greater than or equal with the second string, the method answers true, otherwise it answers false.

  For example:

  ```smalltalk
  ('a' >= 'a') = true.
  ('a' >= 'b') = false.
  ('aab' >= 'aaa') = true.
  ('c' >= 'b') = true.
  ```
* **`isLowercase`** - Test if the receiver is lower case.

  For example:

  ```smalltalk
  'aa' isLowercase = true.
  '2' isLowercase = true.
  'Aa' isLowercase = false.
  ```
* **`isUppercase`** - Test if the receiver is upper case.

  For example:

  ```smalltalk
  'AA' isUppercase = true.
  '2' isUppercase = true.
  'Aa' isUppercase = false.
  ```

#### Category: convenience

* **`langCode`** - answer the language code of the string.

  For example:

  ```smalltalk
  'Abc' langCode = #:en.
  '您好' langCode = #:zh_CN
  ```

#### Category: converting

* **`asInteger`** - return the integer present in the receiver, or nil. In case of float, returns the integer part.

  For example:

  ```smalltalk
  '120' asInteger = 120.
  ```

  If the string contains an illegal character, an exception will be triggered.

  We also support to parse a string including a comma to separate groups of thousands, for example:

  ```smalltalk
  '120,120,120' asInteger = 120120120
  ```
* **`asIntegerIgnoreJunk`** - return the integer present in the receiver, or nil. In case of float, returns the integer part.

  The junk in string will be ignored. If no integer is identified, it returns nil. For example:

  ```smalltalk
  '120 years old' asIntegerIgnoreJunk = 120.
  '120,120,120' asInteger = 120120120
  ```
* **`asLowercase`** - answer a String made up from the receiver whose characters are all lowercase.

  For example:

  ```smalltalk
  'Abc' asLowercase = 'abc'.
  ```
* **`asNumber`** - return the number present in the receiver, or raise an exception if there are illegal characters inside the string.

  For example:

  ```smalltalk
  aNumber := '123.3' asNumber 



  ```
* **`asNumberIgnoreJunk`** - return the number present in the receiver by removing junk in string. If no number is identified, it returns nil.

  For example:

  ```smalltalk
  aNumber := '123.3 degree' asNumberIgnoreJunk 



  ```
* **`asString`** - return a copy of the original string in the receiver
* **`asURLPath`** - Convert the given text into a URL-encoded string suitable for inclusion in a URL path.

  For example:

  ```smalltalk
  'a b' asURLPath = 'a%20b'.
  ```
* **`asUppercase`** - answer a String made up from the receiver whose characters are all uppercase.

  For example:

  ```smalltalk
  'Abc' asUppercase = 'ABC'.
  ```
* **`splitOn:`** - split the string by specified separator and answer an array for splitted items.

  For example:

  ```smalltalk
  'a,b' splitOn: $, = {'a'. 'b'}.
  ```

#### Category: copying

* **`copyFrom:to:`** - answer a copied subrange of the receiver..

  For example:

  ```smalltalk
  ('salkjsdlkgfeesd' copyFrom: 1 to: 3) = 'sal'
  ('salkjsdlkgfeesd' copyFrom: 2 to: 3) = 'al'
  ```
* **`left:`** - answer a copied subrange of the receiver from left with specified size.

  For example:

  ```smalltalk
  ('salkjsdlkgfeesd' left: 3) = 'sal'
  ('salkjsdlkgfeesd' left: 2 ) = 'sa'
  ```
* **`right:`** - answer a copied subrange of the receiver from right with specified size.

  For example:

  ```smalltalk
  ('salkjsdlkgfeesd' right: 3) = 'esd'
  ('salkjsdlkgfeesd' right: 2 ) = 'sd'
  ```
* **`trimLeft`** - Trim whitespaces from the left side of the receiving string.

  For example:

  ```smalltalk
  ('  abc' trimLeft) = 'abc'
  ```
* **`trimRight`** - Trim whitespaces from the right side of the receiving string.

  For example:

  ```smalltalk
  ('abc  ' trimRight) = 'abc'
  ```

#### Category: date-time

* **`dateAdd:as:format:`** - adds time/date interval to a date and then returns the date

  The following category can be used in second argument for `as:`

  * `#year` the difference in years
  * `#month` the difference in months
  * `#day` the difference in days.
  * `#hour` the difference in hours.
  * `#minute` the difference in minutes.
  * `#second` the difference in seconds.

  For example:

  ```smalltalk
  " date = 2019/08/25"
  date := ('2017/08/25' dateAdd: 2 as: #year format: 'YYYY/MM/DD')
  " date = 2015/08/25"
  date := ('2017/08/25' dateAdd: -2 as: #year format: 'YYYY/MM/DD')

  " date = 2017/10/25"
  date := ('2017/08/25' dateAdd: 2 as: #month format: 'YYYY/MM/DD')
  " date = 2017/06/25"
  date := ('2017/08/25' dateAdd: -2 as: #month format: 'YYYY/MM/DD')

  " date = 2017/08/27"
  date := ('2017/08/25' dateAdd: 2 as: #day format: 'YYYY/MM/DD')
  " date = 2017/08/23"
  date := ('2017/08/25' dateAdd: -2 as: #day format: 'YYYY/MM/DD')

  " time = 2017/08/25 14:00"
  time := ('2017/08/25 12:00' dateAdd: 2 as: #hour format: 'YYYY/MM/DD hh:mm')
  " time = 2017/08/25 10:00"
  time := ('2017/08/25 12:00' dateAdd: -2 as: #hour format: 'YYYY/MM/DD hh:mm')

  " time = 2017/08/25 12:02"
  time := ('2017/08/25 12:00' dateAdd: 2 as: #minute format: 'YYYY/MM/DD hh:mm')
  " time = 2017/08/25 11:58"
  time := ('2017/08/25 12:00' dateAdd: -2 as: #minute format: 'YYYY/MM/DD hh:mm')

  " time = 2017/08/25 12:00:02"
  time := ('2017/08/25 12:00:00' dateAdd: 2 as: #second format: 'YYYY/MM/DD hh:mm:ss')
  " time = 2017/08/25 11:59:58"
  time := ('2017/08/25 12:00:00' dateAdd: -2 as: #second format: 'YYYY/MM/DD hh:mm:ss')

  ```
* **`dateDiff:as:`** - find the difference between two dates string.

  The following category can be used in second argument for `as:`

  * `#year` the difference in years
  * `#month` the difference in months
  * `#day` the difference in days.
  * `#hour` the difference in hours.
  * `#minute` the difference in minutes.
  * `#second` the difference in seconds.

  For example:

  ```smalltalk
  " dy = 2"
  dy := ('2017/08/25' dateDiff: '2019/08/25' as: #year)
  " dy = -6"
  dy := ('2017/08/25' dateDiff: '2011/08/25' as: #year)

  " dm = 24"
  dm := ('2017/08/25' dateDiff: '2019/08/25' as: #month)
  " dm = -72"
  dm := ('2017/08/25' dateDiff: '2011/08/25' as: #month)

  " dd = 730"
  dd := ('2017/08/25' dateDiff: '2019/08/25' as: #day)
  " dd = -2192"
  dd := ('2017/08/25' dateDiff: '2011/08/25' as: #day)

  " dh = 17520"
  dh := ('2017/08/25' dateDiff: '2019/08/25' as: #hour)
  " dh = -52608"
  dh := ('2017/08/25' dateDiff: '2011/08/25' as: #hour)

  " dj = 1051200"
  dm := ('2017/08/25' dateDiff: '2019/08/25' as: #minute)
  " dm = -3156480"
  dm := ('2017/08/25' dateDiff: '2011/08/25' as: #minute)

  " ds = 63072000"
  ds := ('2017/08/25' dateDiff: '2019/08/25' as: #second)
  " ds = -189388800"
  ds := ('2017/08/25' dateDiff: '2011/08/25' as: #second)

  ```
* **`dateFormat:`** - Format the date time string with the given format. The valid format control strings are:

  * `YYYY` Four-digit year
  * `MM` Two-digit month (01=January, etc.)
  * `M` One or two-digit month
  * `DD` Two-digit day of month (01 through 31)
  * `D` One or two-digit day of month
  * `hh` Two digits of hour (00 through 23) (am/pm NOT allowed)
  * `h` One or two digits of hour (0 through 23) (am/pm NOT allowed)
  * `mm` Two digits of minute (00 through 59)
  * `m` One or two digits of minute (0 through 59)
  * `ss` Two digits of second (00 through 59)
  * `s` One or two digits of second (0 through 59)

  For example:

  ```smalltalk
  date := '2022-09-12'.
  date dateFormat: 'MM/DD/YYYY'. "09/12/2022"
  ```

  And to get the previous year.

  ```smalltalk
  year := (date dateFormat: 'YYYY') asInteger.
  year - 1
  ```

#### Category: finding/searching

* **`findString:`** - answer the index of the first substring within the receiver.

  If the receiver does not contain substring, answer 0.

  For example:

  ```smalltalk
  ('salkjsdlkgfeesd' findString: 'sd') "returns 6"
  ('salkjsdlkgfeeal' findString: 'al') "returns 2"
  ```
* **`findString:startingAt:`** - answers the index of the first substring within the receiver from the start. If the receiver does not contain a substring, the answer is 0.

  For example:

  ```smalltalk
  ('salkjsdlkgfee' findString: 'ee' startingAt: 3) "returns 12"
  ('salkjsdlkgfee' findString: 'al' startingAt: 3) "returns 0"
  ('salkjsdlkgfeeal' findString: 'al' startingAt: 1) "returns 2"
  ```

#### Category: instance creation

* **`new`** - Create a new string object by copy current string.

#### Category: testing

* **`isSequenceable`** - Answer whether the receiver can be accessed by a numeric index with #at:/#at:put:.
