mirror of
https://github.com/ruby/ruby.git
synced 2025-08-15 13:39:04 +02:00
[DOC] Tweaks for String#bytesplice
This commit is contained in:
parent
456f6f3f83
commit
35feaee917
3 changed files with 72 additions and 16 deletions
66
doc/string/bytesplice.rdoc
Normal file
66
doc/string/bytesplice.rdoc
Normal file
|
@ -0,0 +1,66 @@
|
|||
Replaces <i>target bytes</i> in +self+ with <i>source bytes</i> from the given string +str+;
|
||||
returns +self+.
|
||||
|
||||
In the first form, arguments +offset+ and +length+ determine the target bytes,
|
||||
and the source bytes are all of the given +str+:
|
||||
|
||||
'0123456789'.bytesplice(0, 3, 'abc') # => "abc3456789"
|
||||
'0123456789'.bytesplice(3, 3, 'abc') # => "012abc6789"
|
||||
'0123456789'.bytesplice(0, 50, 'abc') # => "abc"
|
||||
'0123456789'.bytesplice(50, 3, 'abc') # Raises IndexError.
|
||||
|
||||
The counts of the target bytes and source source bytes may be different:
|
||||
|
||||
'0123456789'.bytesplice(0, 6, 'abc') # => "abc6789" # Shorter source.
|
||||
'0123456789'.bytesplice(0, 1, 'abc') # => "abc123456789" # Shorter target.
|
||||
|
||||
And either count may be zero (i.e., specifying an empty string):
|
||||
|
||||
'0123456789'.bytesplice(0, 3, '') # => "3456789" # Empty source.
|
||||
'0123456789'.bytesplice(0, 0, 'abc') # => "abc0123456789" # Empty target.
|
||||
|
||||
In the second form, just as in the first,
|
||||
arugments +offset+ and +length+ determine the target bytes;
|
||||
argument +str+ _contains_ the source bytes,
|
||||
and the additional arguments +str_offset+ and +str_length+
|
||||
determine the actual source bytes:
|
||||
|
||||
'0123456789'.bytesplice(0, 3, 'abc', 0, 3) # => "abc3456789"
|
||||
'0123456789'.bytesplice(0, 3, 'abc', 1, 1) # => "b3456789" # Shorter source.
|
||||
'0123456789'.bytesplice(0, 1, 'abc', 0, 3) # => "abc123456789" # Shorter target.
|
||||
'0123456789'.bytesplice(0, 3, 'abc', 1, 0) # => "3456789" # Empty source.
|
||||
'0123456789'.bytesplice(0, 0, 'abc', 0, 3) # => "abc0123456789" # Empty target.
|
||||
|
||||
In the third form, argument +range+ determines the target bytes
|
||||
and the source bytes are all of the given +str+:
|
||||
|
||||
'0123456789'.bytesplice(0..2, 'abc') # => "abc3456789"
|
||||
'0123456789'.bytesplice(3..5, 'abc') # => "012abc6789"
|
||||
'0123456789'.bytesplice(0..5, 'abc') # => "abc6789" # Shorter source.
|
||||
'0123456789'.bytesplice(0..0, 'abc') # => "abc123456789" # Shorter target.
|
||||
'0123456789'.bytesplice(0..2, '') # => "3456789" # Empty source.
|
||||
'0123456789'.bytesplice(0...0, 'abc') # => "abc0123456789" # Empty target.
|
||||
|
||||
In the fourth form, just as in the third,
|
||||
arugment +range+ determines the target bytes;
|
||||
argument +str+ _contains_ the source bytes,
|
||||
and the additional argument +str_range+
|
||||
determines the actual source bytes:
|
||||
|
||||
'0123456789'.bytesplice(0..2, 'abc', 0..2) # => "abc3456789"
|
||||
'0123456789'.bytesplice(3..5, 'abc', 0..2) # => "012abc6789"
|
||||
'0123456789'.bytesplice(0..2, 'abc', 0..1) # => "ab3456789" # Shorter source.
|
||||
'0123456789'.bytesplice(0..1, 'abc', 0..2) # => "abc23456789" # Shorter target.
|
||||
'0123456789'.bytesplice(0..2, 'abc', 0...0) # => "3456789" # Empty source.
|
||||
'0123456789'.bytesplice(0...0, 'abc', 0..2) # => "abc0123456789" # Empty target.
|
||||
|
||||
In any of the forms, the beginnings and endings of both source and target
|
||||
must be on character boundaries.
|
||||
|
||||
In these examples, +self+ has five 3-byte characters,
|
||||
and so has character boundaries at offsets 0, 3, 6, 9, 12, and 15.
|
||||
|
||||
'こんにちは'.bytesplice(0, 3, 'abc') # => "abcんにちは"
|
||||
'こんにちは'.bytesplice(1, 3, 'abc') # Raises IndexError.
|
||||
'こんにちは'.bytesplice(0, 2, 'abc') # Raises IndexError.
|
||||
|
21
string.c
21
string.c
|
@ -6913,23 +6913,12 @@ str_check_beg_len(VALUE str, long *beg, long *len)
|
|||
|
||||
/*
|
||||
* call-seq:
|
||||
* bytesplice(index, length, str) -> string
|
||||
* bytesplice(index, length, str, str_index, str_length) -> string
|
||||
* bytesplice(range, str) -> string
|
||||
* bytesplice(range, str, str_range) -> string
|
||||
* bytesplice(offset, length, str) -> self
|
||||
* bytesplice(offset, length, str, str_offset, str_length) -> self
|
||||
* bytesplice(range, str) -> self
|
||||
* bytesplice(range, str, str_range) -> self
|
||||
*
|
||||
* Replaces some or all of the content of +self+ with +str+, and returns +self+.
|
||||
* The portion of the string affected is determined using
|
||||
* the same criteria as String#byteslice, except that +length+ cannot be omitted.
|
||||
* If the replacement string is not the same length as the text it is replacing,
|
||||
* the string will be adjusted accordingly.
|
||||
*
|
||||
* If +str_index+ and +str_length+, or +str_range+ are given, the content of +self+ is replaced by str.byteslice(str_index, str_length) or str.byteslice(str_range); however the substring of +str+ is not allocated as a new string.
|
||||
*
|
||||
* The form that take an Integer will raise an IndexError if the value is out
|
||||
* of range; the Range form will raise a RangeError.
|
||||
* If the beginning or ending offset does not land on character (codepoint)
|
||||
* boundary, an IndexError will be raised.
|
||||
* :include: doc/string/bytesplice.rdoc
|
||||
*/
|
||||
|
||||
static VALUE
|
||||
|
|
|
@ -391,6 +391,7 @@
|
|||
#
|
||||
# _Substitution_
|
||||
#
|
||||
# - #bytesplice: Replaces bytes of +self+ with bytes from a given string; returns +self+.
|
||||
# - #sub!: Replaces the first substring that matches a given pattern with a given replacement string;
|
||||
# returns +self+ if any changes, +nil+ otherwise.
|
||||
# - #gsub!: Replaces each substring that matches a given pattern with a given replacement string;
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue