Skip to content

Commit 7be4d90

Browse files
BurdetteLamarBurdetteLamar
authored
[DOC] Enhanced RDoc for String (#5751)
 Adds to doc for String.new, also making it compliant with documentation_guide.rdoc. Fixes some broken links in io.c (that I failed to correct yesterday).
1 parent 4d2623e commit 7be4d90

File tree

4 files changed

+53
-41
lines changed

4 files changed

+53
-41
lines changed

‎doc/string/new.rdoc

Lines changed: 40 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,50 @@
11
Returns a new \String that is a copy of +string+.
22

33
With no arguments, returns the empty string with the Encoding <tt>ASCII-8BIT</tt>:
4+
45
s = String.new
56
s # => ""
67
s.encoding # => #<Encoding:ASCII-8BIT>
78

8-
With the single \String argument +string+, returns a copy of +string+
9-
with the same encoding as +string+:
10-
s = String.new('Que veut dire ça?')
11-
s # => "Que veut dire ça?"
12-
s.encoding # => #<Encoding:UTF-8>
13-
14-
Literal strings like <tt>""</tt> or here-documents always use
15-
{script encoding}[rdoc-ref:Encoding@Script+Encoding], unlike String.new.
16-
17-
With keyword +encoding+, returns a copy of +str+
18-
with the specified encoding:
19-
s = String.new(encoding: 'ASCII')
20-
s.encoding # => #<Encoding:US-ASCII>
21-
s = String.new('foo', encoding: 'ASCII')
22-
s.encoding # => #<Encoding:US-ASCII>
23-
24-
Note that these are equivalent:
25-
s0 = String.new('foo', encoding: 'ASCII')
26-
s1 = 'foo'.force_encoding('ASCII')
27-
s0.encoding == s1.encoding # => true
28-
29-
With keyword +capacity+, returns a copy of +str+;
30-
the given +capacity+ may set the size of the internal buffer,
31-
which may affect performance:
32-
String.new(capacity: 1) # => ""
33-
String.new(capacity: 4096) # => ""
9+
With optional argument +string+ and no keyword arguments,
10+
returns a copy of +string+ with the same encoding:
11+
12+
String.new('foo') # => "foo"
13+
String.new('тест') # => "тест"
14+
String.new('こんにちは') # => "こんにちは"
15+
16+
(Unlike \String.new,
17+
a {string literal}[rdoc-ref:syntax/literals.rdoc@String+Literals] like <tt>''</tt> or a
18+
{here document literal}[rdoc-ref:syntax/literals.rdoc@Here+Document+Literals]
19+
always has {script encoding}[rdoc-ref:encodings.rdoc@Script+Encoding].)
20+
21+
With optional keyword argument +encoding+, returns a copy of +string+
22+
with the specified encoding;
23+
the +encoding+ may be an Encoding object, an encoding name,
24+
or an encoding name alias:
25+
26+
String.new('foo', encoding: Encoding::US_ASCII).encoding # => #<Encoding:US-ASCII>
27+
String.new('foo', encoding: 'US-ASCII').encoding # => #<Encoding:US-ASCII>
28+
String.new('foo', encoding: 'ASCII').encoding # => #<Encoding:US-ASCII>
29+
30+
The given encoding need not be valid for the string's content,
31+
and that validity is not checked:
32+
33+
s = String.new('こんにちは', encoding: 'ascii')
34+
s.valid_encoding? # => false
35+
36+
But the given +encoding+ itself is checked:
37+
38+
String.new('foo', encoding: 'bar') # Raises ArgumentError.
39+
40+
With optional keyword argument +capacity+, returns a copy of +string+
41+
(or an empty string, if +string+ is not given);
42+
the given +capacity+ is advisory only,
43+
and may or may not set the size of the internal buffer,
44+
which may in turn affect performance:
45+
46+
String.new(capacity: 1)
47+
String.new('foo', capacity: 4096)
3448

3549
The +string+, +encoding+, and +capacity+ arguments may all be used together:
3650

‎doc/transcode.rdoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ class String
4444
# t.encoding # => #<Encoding:UTF-8>
4545
#
4646
# Optional keyword arguments +enc_opts+ specify encoding options;
47-
# see {Encoding Options}[rdoc-ref:Encoding@Encoding+Options].
47+
# see {Encoding Options}[rdoc-ref:encodings.rdoc@Encoding+Options].
4848
def encode(dst_encoding = Encoding.default_internal, **enc_opts)
4949
# Pseudo code
5050
Primitive.str_encode(...)

‎io.c

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -7458,7 +7458,7 @@ static VALUE popen_finish(VALUE port, VALUE klass);
74587458
* Optional keyword arguments +opts+ specify:
74597459
*
74607460
* - {Open options}[rdoc-ref:IO@Open+Options].
7461-
* - {Encoding options}[rdoc-ref:Encoding@Encoding+Options].
7461+
* - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options].
74627462
* - Options for Kernel#spawn.
74637463
*
74647464
* <b>Forked \Process</b>
@@ -8080,7 +8080,7 @@ rb_freopen(VALUE fname, const char *mode, FILE *fp)
80808080
* Optional keyword arguments +opts+ specify:
80818081
*
80828082
* - {Open Options}[rdoc-ref:IO@Open+Options].
8083-
* - {Encoding options}[rdoc-ref:Encoding@Encoding+Options].
8083+
* - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options].
80848084
*
80858085
*/
80868086

@@ -9012,7 +9012,7 @@ rb_io_make_open_file(VALUE obj)
90129012
* Optional keyword arguments +opts+ specify:
90139013
*
90149014
* - {Open Options}[rdoc-ref:IO@Open+Options].
9015-
* - {Encoding options}[rdoc-ref:Encoding@Encoding+Options].
9015+
* - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options].
90169016
*
90179017
* Examples:
90189018
*
@@ -9156,7 +9156,7 @@ rb_io_set_encoding_by_bom(VALUE io)
91569156
* Optional keyword arguments +opts+ specify:
91579157
*
91589158
* - {Open Options}[rdoc-ref:IO@Open+Options].
9159-
* - {Encoding options}[rdoc-ref:Encoding@Encoding+Options].
9159+
* - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options].
91609160
*
91619161
* Examples:
91629162
*
@@ -9835,7 +9835,7 @@ static VALUE argf_readlines(int, VALUE *, VALUE);
98359835
* For all forms above, optional keyword arguments specify:
98369836
*
98379837
* - {Line Options}[rdoc-ref:IO@Line+Options].
9838-
* - {Encoding options}[rdoc-ref:Encoding@Encoding+Options].
9838+
* - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options].
98399839
*
98409840
* Examples:
98419841
*
@@ -11100,7 +11100,7 @@ pipe_pair_close(VALUE rw)
1110011100
* Optional keyword arguments +opts+ specify:
1110111101
*
1110211102
* - {Open Options}[rdoc-ref:IO@Open+Options].
11103-
* - {Encoding Options}[rdoc-ref:Encoding@Encoding+Options].
11103+
* - {Encoding Options}[rdoc-ref:encodings.rdoc@Encoding+Options].
1110411104
*
1110511105
* With no block given, returns the two endpoints in an array:
1110611106
*
@@ -11362,7 +11362,7 @@ io_s_foreach(VALUE v)
1136211362
* Optional keyword arguments +opts+ specify:
1136311363
*
1136411364
* - {Open Options}[rdoc-ref:IO@Open+Options].
11365-
* - {Encoding options}[rdoc-ref:Encoding@Encoding+Options].
11365+
* - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options].
1136611366
* - {Line Options}[rdoc-ref:IO@Line+Options].
1136711367
*
1136811368
* Returns an Enumerator if no block is given.
@@ -11460,7 +11460,7 @@ io_s_readlines(VALUE v)
1146011460
* Optional keyword arguments +opts+ specify:
1146111461
*
1146211462
* - {Open Options}[rdoc-ref:IO@Open+Options].
11463-
* - {Encoding options}[rdoc-ref:Encoding@Encoding+Options].
11463+
* - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options].
1146411464
* - {Line Options}[rdoc-ref:IO@Line+Options].
1146511465
*
1146611466
*/
@@ -11550,7 +11550,7 @@ seek_before_access(VALUE argp)
1155011550
* Optional keyword arguments +opts+ specify:
1155111551
*
1155211552
* - {Open Options}[rdoc-ref:IO@Open+Options].
11553-
* - {Encoding options}[rdoc-ref:Encoding@Encoding+Options].
11553+
* - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options].
1155411554
*
1155511555
*/
1155611556

@@ -11741,7 +11741,7 @@ io_s_write(int argc, VALUE *argv, VALUE klass, int binary)
1174111741
* Optional keyword arguments +opts+ specify:
1174211742
*
1174311743
* - {Open Options}[rdoc-ref:IO@Open+Options].
11744-
* - {Encoding options}[rdoc-ref:Encoding@Encoding+Options].
11744+
* - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options].
1174511745
*
1174611746
*/
1174711747

@@ -12825,7 +12825,7 @@ rb_io_internal_encoding(VALUE io)
1282512825
* and internal encodings for the stream.
1282612826
*
1282712827
* Optional keyword arguments +enc_opts+ specify
12828-
* {Encoding options}[rdoc-ref:Encoding@Encoding+Options].
12828+
* {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options].
1282912829
*
1283012830
*/
1283112831

‎string.c

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1813,9 +1813,7 @@ rb_ec_str_resurrect(struct rb_execution_context_struct *ec, VALUE str)
18131813
/*
18141814
*
18151815
* call-seq:
1816-
* String.new(string = '') -> new_string
1817-
* String.new(string = '', encoding: encoding) -> new_string
1818-
* String.new(string = '', capacity: size) -> new_string
1816+
* String.new(string = '', **opts) -> new_string
18191817
*
18201818
* :include: doc/string/new.rdoc
18211819
*

0 commit comments

Comments
 (0)