Skip to content

Commit ff332ab

Browse files
BurdetteLamarkou
andauthored
[DOC] Tweaks for StringIO#each_line (#165)
Adds to "Position": pos inside a character. Makes a couple of minor corrections. --------- Co-authored-by: Sutou Kouhei <kou@cozmixng.org>
1 parent 95c2a0c commit ff332ab

File tree

2 files changed

+190
-163
lines changed

2 files changed

+190
-163
lines changed

doc/stringio/each_line.md

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
With a block given calls the block with each remaining line (see "Position" below) in the stream;
2+
returns `self`.
3+
4+
Leaves stream position at end-of-stream.
5+
6+
**No Arguments**
7+
8+
With no arguments given,
9+
reads lines using the default record separator
10+
(global variable `$/`, whose initial value is `"\n"`).
11+
12+
```ruby
13+
strio = StringIO.new(TEXT)
14+
strio.each_line {|line| p line }
15+
strio.eof? # => true
16+
```
17+
18+
Output:
19+
20+
```
21+
"First line\n"
22+
"Second line\n"
23+
"\n"
24+
"Fourth line\n"
25+
"Fifth line\n"
26+
```
27+
28+
**Argument `sep`**
29+
30+
With only string argument `sep` given,
31+
reads lines using that string as the record separator:
32+
33+
```ruby
34+
strio = StringIO.new(TEXT)
35+
strio.each_line(' ') {|line| p line }
36+
```
37+
38+
Output:
39+
40+
```
41+
"First "
42+
"line\nSecond "
43+
"line\n\nFourth "
44+
"line\nFifth "
45+
"line\n"
46+
```
47+
48+
**Argument `limit`**
49+
50+
With only integer argument `limit` given,
51+
reads lines using the default record separator;
52+
also limits the size (in characters) of each line to the given limit:
53+
54+
```ruby
55+
strio = StringIO.new(TEXT)
56+
strio.each_line(10) {|line| p line }
57+
```
58+
59+
Output:
60+
61+
```
62+
"First line"
63+
"\n"
64+
"Second lin"
65+
"e\n"
66+
"\n"
67+
"Fourth lin"
68+
"e\n"
69+
"Fifth line"
70+
"\n"
71+
```
72+
73+
**Arguments `sep` and `limit`**
74+
75+
With arguments `sep` and `limit` both given,
76+
honors both:
77+
78+
```ruby
79+
strio = StringIO.new(TEXT)
80+
strio.each_line(' ', 10) {|line| p line }
81+
```
82+
83+
Output:
84+
85+
```
86+
"First "
87+
"line\nSecon"
88+
"d "
89+
"line\n\nFour"
90+
"th "
91+
"line\nFifth"
92+
" "
93+
"line\n"
94+
```
95+
96+
**Position**
97+
98+
As stated above, method `each` _remaining_ line in the stream.
99+
100+
In the examples above each `strio` object starts with its position at beginning-of-stream;
101+
but in other cases the position may be anywhere (see StringIO#pos):
102+
103+
```ruby
104+
strio = StringIO.new(TEXT)
105+
strio.pos = 30 # Set stream position to character 30.
106+
strio.each_line {|line| p line }
107+
```
108+
109+
Output:
110+
111+
```
112+
" line\n"
113+
"Fifth line\n"
114+
```
115+
116+
In all the examples above, the stream position is at the beginning of a character;
117+
in other cases, that need not be so:
118+
119+
```ruby
120+
s = 'こんにちは' # Five 3-byte characters.
121+
strio = StringIO.new(s)
122+
strio.pos = 3 # At beginning of second character.
123+
strio.each_line {|line| p line }
124+
strio.pos = 4 # At second byte of second character.
125+
strio.each_line {|line| p line }
126+
strio.pos = 5 # At third byte of second character.
127+
strio.each_line {|line| p line }
128+
```
129+
130+
Output:
131+
132+
```
133+
"んにちは"
134+
"\x82\x93にちは"
135+
"\x93にちは"
136+
```
137+
138+
**Special Record Separators**
139+
140+
Like some methods in class `IO`, StringIO.each honors two special record separators;
141+
see {Special Line Separators}[https://docs.ruby-lang.org/en/master/IO.html#class-IO-label-Special+Line+Separator+Values].
142+
143+
```ruby
144+
strio = StringIO.new(TEXT)
145+
strio.each_line('') {|line| p line } # Read as paragraphs (separated by blank lines).
146+
```
147+
148+
Output:
149+
150+
```
151+
"First line\nSecond line\n\n"
152+
"Fourth line\nFifth line\n"
153+
```
154+
155+
```ruby
156+
strio = StringIO.new(TEXT)
157+
strio.each_line(nil) {|line| p line } # "Slurp"; read it all.
158+
```
159+
160+
Output:
161+
162+
```
163+
"First line\nSecond line\n\nFourth line\nFifth line\n"
164+
```
165+
166+
**Keyword Argument `chomp`**
167+
168+
With keyword argument `chomp` given as `true` (the default is `false`),
169+
removes trailing newline (if any) from each line:
170+
171+
```ruby
172+
strio = StringIO.new(TEXT)
173+
strio.each_line(chomp: true) {|line| p line }
174+
```
175+
176+
Output:
177+
178+
```
179+
"First line"
180+
"Second line"
181+
""
182+
"Fourth line"
183+
"Fifth line"
184+
```
185+
186+
With no block given, returns a new {Enumerator}[https://docs.ruby-lang.org/en/master/Enumerator.html].
187+
188+
189+
Related: StringIO.each_byte, StringIO.each_char, StringIO.each_codepoint.

ext/stringio/stringio.c

Lines changed: 1 addition & 163 deletions
Original file line numberDiff line numberDiff line change
@@ -1473,170 +1473,8 @@ strio_readline(int argc, VALUE *argv, VALUE self)
14731473
* each_line(limit, chomp: false) {|line| ... } -> self
14741474
* each_line(sep, limit, chomp: false) {|line| ... } -> self
14751475
*
1476-
* With a block given calls the block with each remaining line (see "Position" below) in the stream;
1477-
* returns `self`.
1476+
* :include: stringio/each_line.md
14781477
*
1479-
* Leaves stream position as end-of-stream.
1480-
*
1481-
* **No Arguments**
1482-
*
1483-
* With no arguments given,
1484-
* reads lines using the default record separator global variable `$/`, whose initial value is `"\n"`.
1485-
*
1486-
* ```
1487-
* strio = StringIO.new(TEXT)
1488-
* strio.each_line {|line| p line }
1489-
* strio.eof? # => true
1490-
* ```
1491-
*
1492-
* Output:
1493-
*
1494-
* ```
1495-
* "First line\n"
1496-
* "Second line\n"
1497-
* "\n"
1498-
* "Fourth line\n"
1499-
* "Fifth line\n"
1500-
* ```
1501-
*
1502-
* **Argument `sep`**
1503-
*
1504-
* With only string argument `sep` given,
1505-
* reads lines using that string as the record separator:
1506-
*
1507-
* ```
1508-
* strio = StringIO.new(TEXT)
1509-
* strio.each_line(' ') {|line| p line }
1510-
* ```
1511-
*
1512-
* Output:
1513-
*
1514-
* ```
1515-
* "First "
1516-
* "line\nSecond "
1517-
* "line\n\nFourth "
1518-
* "line\nFifth "
1519-
* "line\n"
1520-
* ```
1521-
*
1522-
* **Argument `limit`**
1523-
*
1524-
* With only integer argument `limit` given,
1525-
* reads lines using the default record separator global variable `$/`, whose initial value is `"\n"`;
1526-
* also limits the size (in characters) of each line to the given limit:
1527-
*
1528-
* ```
1529-
* strio = StringIO.new(TEXT)
1530-
* strio.each_line(10) {|line| p line }
1531-
* ```
1532-
*
1533-
* Output:
1534-
*
1535-
* ```
1536-
* "First line"
1537-
* "\n"
1538-
* "Second lin"
1539-
* "e\n"
1540-
* "\n"
1541-
* "Fourth lin"
1542-
* "e\n"
1543-
* "Fifth line"
1544-
* "\n"
1545-
* ```
1546-
* **Arguments `sep` and `limit`**
1547-
*
1548-
* With arguments `sep` and `limit` both given,
1549-
* honors both:
1550-
*
1551-
* ```
1552-
* strio = StringIO.new(TEXT)
1553-
* strio.each_line(' ', 10) {|line| p line }
1554-
* ```
1555-
*
1556-
* Output:
1557-
*
1558-
* ```
1559-
* "First "
1560-
* "line\nSecon"
1561-
* "d "
1562-
* "line\n\nFour"
1563-
* "th "
1564-
* "line\nFifth"
1565-
* " "
1566-
* "line\n"
1567-
* ```
1568-
*
1569-
* **Position**
1570-
*
1571-
* As stated above, method `each` _remaining_ line in the stream.
1572-
*
1573-
* In the examples above each `strio` object starts with its position at beginning-of-stream;
1574-
* but in other cases the position may be anywhere (see StringIO#pos):
1575-
*
1576-
* ```
1577-
* strio = StringIO.new(TEXT)
1578-
* strio.pos = 30 # Set stream position to character 30.
1579-
* strio.each_line {|line| p line }
1580-
* ```
1581-
*
1582-
* Output:
1583-
*
1584-
* ```
1585-
* " line\n"
1586-
* "Fifth line\n"
1587-
* ```
1588-
*
1589-
* **Special Record Separators**
1590-
*
1591-
* Like some methds in class `IO`, StringIO.each honors two special record separators;
1592-
* see {Special Line Separators}[https://docs.ruby-lang.org/en/master/IO.html#class-IO-label-Special+Line+Separator+Values].
1593-
*
1594-
* ```
1595-
* strio = StringIO.new(TEXT)
1596-
* strio.each_line('') {|line| p line } # Read as paragraphs (separated by blank lines).
1597-
* ```
1598-
*
1599-
* Output:
1600-
*
1601-
* ```
1602-
* "First line\nSecond line\n\n"
1603-
* "Fourth line\nFifth line\n"
1604-
* ```
1605-
*
1606-
* ```
1607-
* strio = StringIO.new(TEXT)
1608-
* strio.each_line(nil) {|line| p line } # "Slurp"; read it all.
1609-
* ```
1610-
*
1611-
* Output:
1612-
*
1613-
* ```
1614-
* "First line\nSecond line\n\nFourth line\nFifth line\n"
1615-
* ```
1616-
*
1617-
* **Keyword Argument `chomp`**
1618-
*
1619-
* With keyword argument `chomp` given as `true` (the default is `false`),
1620-
* removes trailing newline (if any) from each line:
1621-
*
1622-
* ```
1623-
* strio = StringIO.new(TEXT)
1624-
* strio.each_line(chomp: true) {|line| p line }
1625-
* ```
1626-
*
1627-
* Output:
1628-
*
1629-
* ```
1630-
* "First line"
1631-
* "Second line"
1632-
* ""
1633-
* "Fourth line"
1634-
* "Fifth line"
1635-
* ```
1636-
*
1637-
* With no block given, returns a new {Enumerator}[https://docs.ruby-lang.org/en/master/Enumerator.html].
1638-
*
1639-
* Related: StringIO.each_byte, StringIO.each_char, StringIO.each_codepoint.
16401478
*/
16411479
static VALUE
16421480
strio_each(int argc, VALUE *argv, VALUE self)

0 commit comments

Comments
 (0)