Class: String

Inherits:
Object
  • Object
show all
Includes:
Comparable
Defined in:
mrblib/string.rb,
mrbgems/mruby-sprintf/mrblib/string.rb,
mrbgems/mruby-string-ext/mrblib/string.rb

Overview

String

ISO 15.2.10

Instance Method Summary collapse

Methods included from Comparable

#<, #<=, #==, #>, #>=, #between?, #clamp

Instance Method Details

#%(args) ⇒ Object 



2
3
4
5
6
7
8
 
# File 'mrbgems/mruby-sprintf/mrblib/string.rb', line 2

def %(args)
  if args.is_a? Array
    sprintf(self, *args)
  else
    sprintf(self, args)
  end
end

#__upto_endless(&block) ⇒ Object 



442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
 
# File 'mrbgems/mruby-string-ext/mrblib/string.rb', line 442

def __upto_endless(&block)
  len = self.length
  # both edges are all digits
  bi = self.to_i(10)
  if bi > 0 or bi == "0"*len
    while true
      s = bi.to_s
      s = s.rjust(len, "0") if s.length < len
      yield s
      bi += 1
    end
    return self
  end
  bs = self
  while true
    yield bs
    bs = bs.succ
  end
  self
end

#center(width, padstr = ' ') ⇒ Object

call-seq: str.center(width, padstr=' ') -> new_str

Centers str in width. If width is greater than the length of str, returns a new String of length width with str centered and padded with padstr; otherwise, returns str.

"hello".center(4)         #=> "hello"
"hello".center(20)        #=> "       hello        "
"hello".center(20, '123') #=> "1231231hello12312312"

Raises:



283
284
285
286
287
288
289
290
 
# File 'mrbgems/mruby-string-ext/mrblib/string.rb', line 283

def center(width, padstr = ' ')
  raise ArgumentError, 'zero width padding' if padstr == ''
  return self if width <= self.size
  width -= self.size
  pad1 = width / 2
  pad2 = width - pad1
  (padstr*pad1)[0,pad1] + self + (padstr*pad2)[0,pad2]
end

#chars(&block) ⇒ Object 



292
293
294
295
296
297
298
299
300
301
 
# File 'mrbgems/mruby-string-ext/mrblib/string.rb', line 292

def chars(&block)
  if block_given?
    self.split('').each do |i|
      block.call(i)
    end
    self
  else
    self.split('')
  end
end

#clear ⇒ Object

call-seq: string.clear -> string

Makes string empty.

a = "abcde"
a.clear    #=> ""


12
13
14
 
# File 'mrbgems/mruby-string-ext/mrblib/string.rb', line 12

def clear
  self.replace("")
end

#codepoints(&block) ⇒ Object Also known as: each_codepoint 



316
317
318
319
320
321
322
323
324
325
326
 
# File 'mrbgems/mruby-string-ext/mrblib/string.rb', line 316

def codepoints(&block)
  cp = __codepoints()
  if block_given?
    cp.each do|x|
      block.call(x)
    end
    self
  else
    cp
  end
end

#each_byte(&block) ⇒ Object

Call the given block for each byte of self.



151
152
153
154
155
156
157
158
159
 
# File 'mrblib/string.rb', line 151

def each_byte(&block)
  return to_enum(:each_byte, &block) unless block
  pos = 0
  while pos < bytesize
    block.call(getbyte(pos))
    pos += 1
  end
  self
end

#each_char(&block) ⇒ Object

Call the given block for each character of self.



306
307
308
309
310
311
312
313
314
 
# File 'mrbgems/mruby-string-ext/mrblib/string.rb', line 306

def each_char(&block)
  return to_enum :each_char unless block
  pos = 0
  while pos < self.size
    block.call(self[pos])
    pos += 1
  end
  self
end

#each_line(separator = "\n", &block) ⇒ Object

Calls the given block for each line and pass the respective line.

ISO 15.2.10.5.15

Raises:



14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
 
# File 'mrblib/string.rb', line 14

def each_line(separator = "\n", &block)
  return to_enum(:each_line, separator) unless block

  if separator.nil?
    block.call(self)
    return self
  end
  raise TypeError unless separator.is_a?(String)

  paragraph_mode = false
  if separator.empty?
    paragraph_mode = true
    separator = "\n\n"
  end
  start = 0
  string = dup
  self_len = self.bytesize
  sep_len = separator.bytesize

  while (pointer = string.byteindex(separator, start))
    pointer += sep_len
    pointer += 1 while paragraph_mode && string.getbyte(pointer) == 10 # 10 == \n
    block.call(string.byteslice(start, pointer - start))
    start = pointer
  end
  return self if start == self_len

  block.call(string.byteslice(start, self_len - start))
  self
end

#gsub(*args, &block) ⇒ Object

Replace all matches of pattern with replacement. Call block (if given) for each match and replace pattern with the value of the block. Return the final value.

ISO 15.2.10.5.18

Raises:



52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'mrblib/string.rb', line 52

def gsub(*args, &block)
  return to_enum(:gsub, *args) if args.length == 1 && !block
  raise ArgumentError, "wrong number of arguments (given #{args.length}, expected 1..2)" unless (1..2).include?(args.length)

  pattern, replace = *args
  plen = pattern.length
  if args.length == 2 && block
    block = nil
  end
  offset = 0
  result = []
  while found = self.byteindex(pattern, offset)
    result << self.byteslice(offset, found - offset)
    offset = found + plen
    result << if block
      block.call(pattern).to_s
    else
      self.__sub_replace(replace, pattern, found)
    end
    if plen == 0
      result << self.byteslice(offset, 1)
      offset += 1
    end
  end
  result << self.byteslice(offset..-1) if offset < length
  result.join
end

#gsub!(*args, &block) ⇒ Object

Replace all matches of pattern with replacement. Call block (if given) for each match and replace pattern with the value of the block. Modify self with the final value.

ISO 15.2.10.5.19

Raises:



87
88
89
90
91
92
93
 
# File 'mrblib/string.rb', line 87

def gsub!(*args, &block)
  raise FrozenError, "can't modify frozen String" if frozen?
  return to_enum(:gsub!, *args) if args.length == 1 && !block
  str = self.gsub(*args, &block)
  return nil unless self.index(args[0])
  self.replace(str)
end

#insert(idx, str) ⇒ Object

call-seq: str.insert(index, other_str) -> str

Inserts other_str before the character at the given index, modifying str. Negative indices count from the end of the string, and insert after the given character. The intent is insert aString so that it starts at the given index.

"abcd".insert(0, 'X')    #=> "Xabcd"
"abcd".insert(3, 'X')    #=> "abcXd"
"abcd".insert(4, 'X')    #=> "abcdX"
"abcd".insert(-3, 'X')   #=> "abXcd"
"abcd".insert(-1, 'X')   #=> "abcdX"


224
225
226
227
228
229
230
231
232
 
# File 'mrbgems/mruby-string-ext/mrblib/string.rb', line 224

def insert(idx, str)
  if idx == -1
    return self << str
  elsif idx < 0
    idx += 1
  end
  self[idx, 0] = str
  self
end

#lines(&blk) ⇒ Object

call-seq: string.lines -> array of string string.lines {|s| block} -> array of string

Returns strings per line;

a = "abc\ndef"
a.lines    #=> ["abc\n", "def"]

If a block is given, it works the same as each_line.



358
359
360
361
362
363
364
365
366
 
# File 'mrbgems/mruby-string-ext/mrblib/string.rb', line 358

def lines(&blk)
  lines = self.__lines
  if blk
    lines.each do |line|
      blk.call(line)
    end
  end
  lines
end

#ljust(idx, padstr = ' ') ⇒ Object

call-seq: str.ljust(integer, padstr=' ') -> new_str

If integer is greater than the length of str, returns a new String of length integer with str left justified and padded with padstr; otherwise, returns str.

"hello".ljust(4)            #=> "hello"
"hello".ljust(20)           #=> "hello               "
"hello".ljust(20, '1234')   #=> "hello123412341234123"

Raises:



245
246
247
248
249
250
251
 
# File 'mrbgems/mruby-string-ext/mrblib/string.rb', line 245

def ljust(idx, padstr = ' ')
  raise ArgumentError, 'zero width padding' if padstr == ''
  return self if idx <= self.size
  pad_repetitions = idx / padstr.size
  padding = (padstr * pad_repetitions)[0, idx-self.size]
  self + padding
end

#lstrip ⇒ Object

call-seq: str.lstrip -> new_str

Returns a copy of str with leading whitespace removed. See also String#rstrip and String#strip.

"  hello  ".lstrip   #=> "hello  "
"hello".lstrip       #=> "hello"


26
27
28
29
30
31
 
# File 'mrbgems/mruby-string-ext/mrblib/string.rb', line 26

def lstrip
  a = 0
  z = self.size - 1
  a += 1 while a <= z and " \f\n\r\t\v".include?(self[a])
  (z >= 0) ? self[a..z] : ""
end

#lstrip! ⇒ Object

call-seq: str.lstrip! -> self or nil

Removes leading whitespace from str, returning nil if no change was made. See also String#rstrip! and String#strip!.

"  hello  ".lstrip   #=> "hello  "
"hello".lstrip!      #=> nil

Raises:



78
79
80
81
82
 
# File 'mrbgems/mruby-string-ext/mrblib/string.rb', line 78

def lstrip!
  raise FrozenError, "can't modify frozen String" if frozen?
  s = self.lstrip
  (s == self) ? nil : self.replace(s)
end

#partition(sep) ⇒ Object

Raises:



114
115
116
117
118
119
120
121
122
123
 
# File 'mrbgems/mruby-string-ext/mrblib/string.rb', line 114

def partition(sep)
  raise TypeError, "type mismatch: #{sep.class} given" unless sep.is_a? String
  n = index(sep)
  unless n.nil?
    m = n + sep.size
    [ slice(0, n), sep, slice(m, size - m) ]
  else
    [ self[0..-1], "", "" ]
  end
end

#prepend(*args) ⇒ Object

call-seq: str.prepend(other_str) -> str

Prepend---Prepend the given string to str.

a = "world"
a.prepend("hello ") #=> "hello world"
a                   #=> "hello world"


338
339
340
341
342
343
344
345
 
# File 'mrbgems/mruby-string-ext/mrblib/string.rb', line 338

def prepend(*args)
  len = args.size
  while len > 0
    len -= 1
    self[0, 0] = args[len]
  end
  self
end

#rjust(idx, padstr = ' ') ⇒ Object

call-seq: str.rjust(integer, padstr=' ') -> new_str

If integer is greater than the length of str, returns a new String of length integer with str right justified and padded with padstr; otherwise, returns str.

"hello".rjust(4)            #=> "hello"
"hello".rjust(20)           #=> "               hello"
"hello".rjust(20, '1234')   #=> "123412341234123hello"

Raises:



264
265
266
267
268
269
270
 
# File 'mrbgems/mruby-string-ext/mrblib/string.rb', line 264

def rjust(idx, padstr = ' ')
  raise ArgumentError, 'zero width padding' if padstr == ''
  return self if idx <= self.size
  pad_repetitions = idx / padstr.size
  padding = (padstr * pad_repetitions)[0, idx-self.size]
  padding + self
end

#rpartition(sep) ⇒ Object

Raises:



125
126
127
128
129
130
131
132
133
134
 
# File 'mrbgems/mruby-string-ext/mrblib/string.rb', line 125

def rpartition(sep)
  raise TypeError, "type mismatch: #{sep.class} given" unless sep.is_a? String
  n = rindex(sep)
  unless n.nil?
    m = n + sep.size
    [ slice(0, n), sep, slice(m, size - m) ]
  else
    [ "", "", self ]
  end
end

#rstrip ⇒ Object

call-seq: str.rstrip -> new_str

Returns a copy of str with trailing whitespace removed. See also String#lstrip and String#strip.

"  hello  ".rstrip   #=> "  hello"
"hello".rstrip       #=> "hello"


43
44
45
46
47
48
 
# File 'mrbgems/mruby-string-ext/mrblib/string.rb', line 43

def rstrip
  a = 0
  z = self.size - 1
  z -= 1 while a <= z and " \f\n\r\t\v\0".include?(self[z])
  (z >= 0) ? self[a..z] : ""
end

#rstrip! ⇒ Object

call-seq: str.rstrip! -> self or nil

Removes trailing whitespace from str, returning nil if no change was made. See also String#lstrip! and String#strip!.

"  hello  ".rstrip   #=> "  hello"
"hello".rstrip!      #=> nil

Raises:



95
96
97
98
99
 
# File 'mrbgems/mruby-string-ext/mrblib/string.rb', line 95

def rstrip!
  raise FrozenError, "can't modify frozen String" if frozen?
  s = self.rstrip
  (s == self) ? nil : self.replace(s)
end

#slice!(arg1, arg2 = nil) ⇒ Object

call-seq: str.slice!(fixnum) -> new_str or nil str.slice!(fixnum, fixnum) -> new_str or nil str.slice!(range) -> new_str or nil str.slice!(other_str) -> new_str or nil

Deletes the specified portion from str, and returns the portion deleted.

string = "this is a string"
string.slice!(2)        #=> "i"
string.slice!(3..6)     #=> " is "
string.slice!("r")      #=> "r"
string                  #=> "thsa sting"

Raises:



152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
 
# File 'mrbgems/mruby-string-ext/mrblib/string.rb', line 152

def slice!(arg1, arg2=nil)
  raise FrozenError, "can't modify frozen String" if frozen?
  raise ArgumentError, "wrong number of arguments (expected 1..2)" if arg1.nil? && arg2.nil?

  if !arg1.nil? && !arg2.nil?
    idx = arg1
    idx += self.size if arg1 < 0
    if idx >= 0 && idx <= self.size && arg2 > 0
      str = self[idx, arg2]
    else
      return nil
    end
  else
    validated = false
    if arg1.kind_of?(Range)
      beg = arg1.begin
      ed = arg1.end
      beg += self.size if beg < 0
      ed += self.size if ed < 0
      ed -= 1 if arg1.exclude_end?
      validated = true
    elsif arg1.kind_of?(String)
      validated = true
    else
      idx = arg1
      idx += self.size if arg1 < 0
      validated = true if idx >=0 && arg1 < self.size
    end
    if validated
      str = self[arg1]
    else
      return nil
    end
  end
  unless str.nil? || str == ""
    if !arg1.nil? && !arg2.nil?
      idx = arg1 >= 0 ? arg1 : self.size+arg1
      str2 = self[0...idx] + self[idx+arg2..-1].to_s
    else
      if arg1.kind_of?(Range)
        idx = beg >= 0 ? beg : self.size+beg
        idx2 = ed>= 0 ? ed : self.size+ed
        str2 = self[0...idx] + self[idx2+1..-1].to_s
      elsif arg1.kind_of?(String)
        idx = self.index(arg1)
        str2 = self[0...idx] + self[idx+arg1.size..-1] unless idx.nil?
      else
        idx = arg1 >= 0 ? arg1 : self.size+arg1
        str2 = self[0...idx] + self[idx+1..-1].to_s
      end
    end
    self.replace(str2) unless str2.nil?
  end
  str
end

#strip ⇒ Object

call-seq: str.strip -> new_str

Returns a copy of str with leading and trailing whitespace removed.

"    hello    ".strip   #=> "hello"
"\tgoodbye\r\n".strip   #=> "goodbye"


59
60
61
62
63
64
65
 
# File 'mrbgems/mruby-string-ext/mrblib/string.rb', line 59

def strip
  a = 0
  z = self.size - 1
  a += 1 while a <= z and " \f\n\r\t\v".include?(self[a])
  z -= 1 while a <= z and " \f\n\r\t\v\0".include?(self[z])
  (z >= 0) ? self[a..z] : ""
end

#strip! ⇒ Object

call-seq: str.strip! -> str or nil

Removes leading and trailing whitespace from str. Returns nil if str was not altered.

Raises:



108
109
110
111
112
 
# File 'mrbgems/mruby-string-ext/mrblib/string.rb', line 108

def strip!
  raise FrozenError, "can't modify frozen String" if frozen?
  s = self.strip
  (s == self) ? nil : self.replace(s)
end

#sub(*args, &block) ⇒ Object

Replace only the first match of pattern with replacement. Call block (if given) for each match and replace pattern with the value of the block. Return the final value.

ISO 15.2.10.5.36



112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
 
# File 'mrblib/string.rb', line 112

def sub(*args, &block)
  unless (1..2).include?(args.length)
    raise ArgumentError, "wrong number of arguments (given #{args.length}, expected 2)"
  end

  pattern, replace = *args
  if args.length == 2 && block
    block = nil
  end
  result = []
  found = self.index(pattern)
  return self.dup unless found
  result << self.byteslice(0, found)
  offset = found + pattern.length
  result << if block
    block.call(pattern).to_s
  else
    self.__sub_replace(replace, pattern, found)
  end
  result << self.byteslice(offset..-1) if offset < length
  result.join
end

#sub!(*args, &block) ⇒ Object

Replace only the first match of pattern with replacement. Call block (if given) for each match and replace pattern with the value of the block. Modify self with the final value.

ISO 15.2.10.5.37

Raises:



142
143
144
145
146
147
 
# File 'mrblib/string.rb', line 142

def sub!(*args, &block)
  raise FrozenError, "can't modify frozen String" if frozen?
  str = self.sub(*args, &block)
  return nil unless self.index(args[0])
  self.replace(str)
end

#upto(max, exclusive = false, &block) ⇒ Object

call-seq: str.upto(other_str, exclusive=false) {|s| block } -> str str.upto(other_str, exclusive=false) -> an_enumerator

Iterates through successive values, starting at str and ending at other_str inclusive, passing each value in turn to the block. The String#succ method is used to generate each value. If optional second argument exclusive is omitted or is false, the last value will be included; otherwise it will be excluded.

If no block is given, an enumerator is returned instead.

"a8".upto("b6") {|s| print s, ' ' }
for s in "a8".."b6"
  print s, ' '
end

produces:

a8 a9 b0 b1 b2 b3 b4 b5 b6
a8 a9 b0 b1 b2 b3 b4 b5 b6

If str and other_str contains only ascii numeric characters, both are recognized as decimal numbers. In addition, the width of string (e.g. leading zeros) is handled appropriately.

"9".upto("11").to_a   #=> ["9", "10", "11"]
"25".upto("5").to_a   #=> []
"07".upto("11").to_a  #=> ["07", "08", "09", "10", "11"]

Raises:



398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
 
# File 'mrbgems/mruby-string-ext/mrblib/string.rb', line 398

def upto(max, exclusive=false, &block)
  return to_enum(:upto, max, exclusive) unless block
  raise TypeError, "no implicit conversion of #{max.class} into String" unless max.kind_of? String

  len = self.length
  maxlen = max.length
  # single character
  if len == 1 and maxlen == 1
    c = self.ord
    e = max.ord
    while c <= e
      break if exclusive and c == e
      yield c.chr(__ENCODING__)
      c += 1
    end
    return self
  end
  # both edges are all digits
  bi = self.to_i(10)
  ei = max.to_i(10)
  if (bi > 0 or bi == "0"*len) and (ei > 0 or ei == "0"*maxlen)
    while bi <= ei
      break if exclusive and bi == ei
      s = bi.to_s
      s = s.rjust(len, "0") if s.length < len
      yield s
      bi += 1
    end
    return self
  end
  bs = self
  while true
    n = (bs <=> max)
    break if n > 0
    break if exclusive and n == 0
    yield bs
    break if n == 0
    bsiz = bs.size
    break if bsiz > max.size || bsiz == 0
    bs = bs.succ
  end
  self
end