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:

'a' < 'b'.
'a' = 'a'.
'b' >= 'a'.

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

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

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

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

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

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.

  aStringWithCR := 'a string' , String cr , 'with a carriage return'.

• crlf - Answer a string containing a carriage return and a linefeed.

  aStringWithCRLF := 'a string' , String crlf , 'with a carriage return and a linefeed'.

• lf - Answer a string containing a linefeed character.

  aStringWithLF := 'a string' , String lf , 'with a linefeed'.

• tab - Answer a string containing a single tab character.

  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:

  "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:

  ('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:

  ('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:

  ('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:

  ('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:

  ('a' >= 'a') = true.
  ('a' >= 'b') = false.
  ('aab' >= 'aaa') = true.
  ('c' >= 'b') = true.

• isLowercase - Test if the receiver is lower case.

  For example:

  'aa' isLowercase = true.
  '2' isLowercase = true.
  'Aa' isLowercase = false.

• isUppercase - Test if the receiver is upper case.

  For example:

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

Category: convenience

• langCode - answer the language code of the string.

  For example:

  '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:

  '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:

  '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:

  '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:

  '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:

  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:

  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:

  'a b' asURLPath = 'a%20b'.

• asUppercase - answer a String made up from the receiver whose characters are all uppercase.

  For example:

  'Abc' asUppercase = 'ABC'.

• splitOn: - split the string by specified separator and answer an array for splitted items.

  For example:

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

Category: copying

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

  For example:

  ('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:

  ('salkjsdlkgfeesd' left: 3) = 'sal'
  ('salkjsdlkgfeesd' left: 2 ) = 'sa'

• right: - answer a copied subrange of the receiver from right with specified size.

  For example:

  ('salkjsdlkgfeesd' right: 3) = 'esd'
  ('salkjsdlkgfeesd' right: 2 ) = 'sd'

• trimLeft - Trim whitespaces from the left side of the receiving string.

  For example:

  ('  abc' trimLeft) = 'abc'

• trimRight - Trim whitespaces from the right side of the receiving string.

  For example:

  ('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:

  " 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:

  " 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:

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

  And to get the previous year.

  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:

  ('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:

  ('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:.