Skip to content

Commit ef3ac3e

Browse files
zverokzverok
authored
Adjust Set documentation (ruby#15547)
1 parent 839410f commit ef3ac3e

File tree

2 files changed

+84
-54
lines changed

2 files changed

+84
-54
lines changed

‎.rdoc_options‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ rdoc_include:
1010

1111
exclude:
1212
- \.gemspec\z
13+
- lib/set/subclass_compatible.rb
1314

1415
generator_name: aliki
1516

‎set.c‎

Lines changed: 83 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -495,11 +495,11 @@ set_initialize_with_block(RB_BLOCK_CALL_FUNC_ARGLIST(i, set))
495495
* If a block is given, the elements of enum are preprocessed by the
496496
* given block.
497497
*
498-
* Set.new([1, 2]) #=> #<Set: {1, 2}>
499-
* Set.new([1, 2, 1]) #=> #<Set: {1, 2}>
500-
* Set.new([1, 'c', :s]) #=> #<Set: {1, "c", :s}>
501-
* Set.new(1..5) #=> #<Set: {1, 2, 3, 4, 5}>
502-
* Set.new([1, 2, 3]) { |x| x * x } #=> #<Set: {1, 4, 9}>
498+
* Set.new([1, 2]) #=> Set[1, 2]
499+
* Set.new([1, 2, 1]) #=> Set[1, 2]
500+
* Set.new([1, 'c', :s]) #=> Set[1, "c", :s]
501+
* Set.new(1..5) #=> Set[1, 2, 3, 4, 5]
502+
* Set.new([1, 2, 3]) { |x| x * x } #=> Set[1, 4, 9]
503503
*/
504504
static VALUE
505505
set_i_initialize(int argc, VALUE *argv, VALUE set)
@@ -595,11 +595,11 @@ set_inspect(VALUE set, VALUE dummy, int recur)
595595
* Returns a new string containing the set entries:
596596
*
597597
* s = Set.new
598-
* s.inspect # => "#<Set: {}>"
598+
* s.inspect # => "Set[]"
599599
* s.add(1)
600-
* s.inspect # => "#<Set: {1}>"
600+
* s.inspect # => "Set[1]"
601601
* s.add(2)
602-
* s.inspect # => "#<Set: {1, 2}>"
602+
* s.inspect # => "Set[1, 2]"
603603
*
604604
* Related: see {Methods for Converting}[rdoc-ref:Set@Methods+for+Converting].
605605
*/
@@ -650,11 +650,11 @@ set_i_to_a(VALUE set)
650650
* call-seq:
651651
* to_set(klass = Set, *args, &block) -> self or new_set
652652
*
653-
* Returns self if receiver is an instance of +Set+ and no arguments or
654-
* block are given. Otherwise, converts the set to another with
655-
* <tt>klass.new(self, *args, &block)</tt>.
653+
* Without arguments, returns +self+ (for duck-typing in methods that
654+
* accept "set, or set-convertible" arguments).
656655
*
657-
* In subclasses, returns `klass.new(self, *args, &block)` unless overridden.
656+
* A form with arguments is _deprecated_. It converts the set to another
657+
* with <tt>klass.new(self, *args, &block)</tt>.
658658
*/
659659
static VALUE
660660
set_i_to_set(int argc, VALUE *argv, VALUE set)
@@ -700,9 +700,9 @@ set_i_join(int argc, VALUE *argv, VALUE set)
700700
* Adds the given object to the set and returns self. Use `merge` to
701701
* add many elements at once.
702702
*
703-
* Set[1, 2].add(3) #=> #<Set: {1, 2, 3}>
704-
* Set[1, 2].add([3, 4]) #=> #<Set: {1, 2, [3, 4]}>
705-
* Set[1, 2].add(2) #=> #<Set: {1, 2}>
703+
* Set[1, 2].add(3) #=> Set[1, 2, 3]
704+
* Set[1, 2].add([3, 4]) #=> Set[1, 2, [3, 4]]
705+
* Set[1, 2].add(2) #=> Set[1, 2]
706706
*/
707707
static VALUE
708708
set_i_add(VALUE set, VALUE item)
@@ -726,8 +726,8 @@ set_i_add(VALUE set, VALUE item)
726726
* Adds the given object to the set and returns self. If the object is
727727
* already in the set, returns nil.
728728
*
729-
* Set[1, 2].add?(3) #=> #<Set: {1, 2, 3}>
730-
* Set[1, 2].add?([3, 4]) #=> #<Set: {1, 2, [3, 4]}>
729+
* Set[1, 2].add?(3) #=> Set[1, 2, 3]
730+
* Set[1, 2].add?([3, 4]) #=> Set[1, 2, [3, 4]]
731731
* Set[1, 2].add?(2) #=> nil
732732
*/
733733
static VALUE
@@ -856,9 +856,9 @@ set_classify_i(st_data_t key, st_data_t tmp)
856856
*
857857
* files = Set.new(Dir.glob("*.rb"))
858858
* hash = files.classify { |f| File.mtime(f).year }
859-
* hash #=> {2000 => #<Set: {"a.rb", "b.rb"}>,
860-
* # 2001 => #<Set: {"c.rb", "d.rb", "e.rb"}>,
861-
* # 2002 => #<Set: {"f.rb"}>}
859+
* hash #=> {2000 => Set["a.rb", "b.rb"],
860+
* # 2001 => Set["c.rb", "d.rb", "e.rb"],
861+
* # 2002 => Set["f.rb"]}
862862
*
863863
* Returns an enumerator if no block is given.
864864
*/
@@ -959,10 +959,10 @@ static void set_merge_enum_into(VALUE set, VALUE arg);
959959
*
960960
* numbers = Set[1, 3, 4, 6, 9, 10, 11]
961961
* set = numbers.divide { |i,j| (i - j).abs == 1 }
962-
* set #=> #<Set: {#<Set: {1}>,
963-
* # #<Set: {3, 4}>,
964-
* # #<Set: {6}>}>
965-
* # #<Set: {9, 10, 11}>,
962+
* set #=> Set[Set[1],
963+
* # Set[3, 4],
964+
* # Set[6],
965+
* # Set[9, 10, 11]]
966966
*
967967
* Returns an enumerator if no block is given.
968968
*/
@@ -993,9 +993,9 @@ set_clear_i(st_data_t key, st_data_t dummy)
993993
*
994994
* Removes all elements and returns self.
995995
*
996-
* set = Set[1, 'c', :s] #=> #<Set: {1, "c", :s}>
997-
* set.clear #=> #<Set: {}>
998-
* set #=> #<Set: {}>
996+
* set = Set[1, 'c', :s] #=> Set[1, "c", :s]
997+
* set.clear #=> Set[]
998+
* set #=> Set[]
999999
*/
10001000
static VALUE
10011001
set_i_clear(VALUE set)
@@ -1043,8 +1043,8 @@ set_intersection_block(RB_BLOCK_CALL_FUNC_ARGLIST(i, data))
10431043
* Returns a new set containing elements common to the set and the given
10441044
* enumerable object.
10451045
*
1046-
* Set[1, 3, 5] & Set[3, 2, 1] #=> #<Set: {3, 1}>
1047-
* Set['a', 'b', 'z'] & ['a', 'b', 'c'] #=> #<Set: {"a", "b"}>
1046+
* Set[1, 3, 5] & Set[3, 2, 1] #=> Set[3, 1]
1047+
* Set['a', 'b', 'z'] & ['a', 'b', 'c'] #=> Set["a", "b"]
10481048
*/
10491049
static VALUE
10501050
set_i_intersection(VALUE set, VALUE other)
@@ -1285,8 +1285,8 @@ set_xor_i(st_data_t key, st_data_t data)
12851285
* given enumerable object. <tt>(set ^ enum)</tt> is equivalent to
12861286
* <tt>((set | enum) - (set & enum))</tt>.
12871287
*
1288-
* Set[1, 2] ^ Set[2, 3] #=> #<Set: {3, 1}>
1289-
* Set[1, 'b', 'c'] ^ ['b', 'd'] #=> #<Set: {"d", 1, "c"}>
1288+
* Set[1, 2] ^ Set[2, 3] #=> Set[3, 1]
1289+
* Set[1, 'b', 'c'] ^ ['b', 'd'] #=> Set["d", 1, "c"]
12901290
*/
12911291
static VALUE
12921292
set_i_xor(VALUE set, VALUE other)
@@ -1312,8 +1312,8 @@ set_i_xor(VALUE set, VALUE other)
13121312
* Returns a new set built by merging the set and the elements of the
13131313
* given enumerable object.
13141314
*
1315-
* Set[1, 2, 3] | Set[2, 4, 5] #=> #<Set: {1, 2, 3, 4, 5}>
1316-
* Set[1, 5, 'z'] | (1..6) #=> #<Set: {1, 5, "z", 2, 3, 4, 6}>
1315+
* Set[1, 2, 3] | Set[2, 4, 5] #=> Set[1, 2, 3, 4, 5]
1316+
* Set[1, 5, 'z'] | (1..6) #=> Set[1, 5, "z", 2, 3, 4, 6]
13171317
*/
13181318
static VALUE
13191319
set_i_union(VALUE set, VALUE other)
@@ -1371,8 +1371,8 @@ set_i_subtract(VALUE set, VALUE other)
13711371
* Returns a new set built by duplicating the set, removing every
13721372
* element that appears in the given enumerable object.
13731373
*
1374-
* Set[1, 3, 5] - Set[1, 5] #=> #<Set: {3}>
1375-
* Set['a', 'b', 'z'] - ['a', 'c'] #=> #<Set: {"b", "z"}>
1374+
* Set[1, 3, 5] - Set[1, 5] #=> Set[3]
1375+
* Set['a', 'b', 'z'] - ['a', 'c'] #=> Set["b", "z"]
13761376
*/
13771377
static VALUE
13781378
set_i_difference(VALUE set, VALUE other)
@@ -1488,9 +1488,9 @@ set_i_select(VALUE set)
14881488
* Replaces the contents of the set with the contents of the given
14891489
* enumerable object and returns self.
14901490
*
1491-
* set = Set[1, 'c', :s] #=> #<Set: {1, "c", :s}>
1492-
* set.replace([1, 2]) #=> #<Set: {1, 2}>
1493-
* set #=> #<Set: {1, 2}>
1491+
* set = Set[1, 'c', :s] #=> Set[1, "c", :s]
1492+
* set.replace([1, 2]) #=> Set[1, 2]
1493+
* set #=> Set[1, 2]
14941494
*/
14951495
static VALUE
14961496
set_i_replace(VALUE set, VALUE other)
@@ -1992,10 +1992,10 @@ rb_set_size(VALUE set)
19921992
* duplicates. It is a hybrid of Array's intuitive inter-operation
19931993
* facilities and Hash's fast lookup.
19941994
*
1995-
* Set is easy to use with Enumerable objects (implementing `each`).
1995+
* Set is easy to use with Enumerable objects (implementing #each).
19961996
* Most of the initializer methods and binary operators accept generic
19971997
* Enumerable objects besides sets and arrays. An Enumerable object
1998-
* can be converted to Set using the `to_set` method.
1998+
* can be converted to Set using the +to_set+ method.
19991999
*
20002000
* Set uses a data structure similar to Hash for storage, except that
20012001
* it only has keys and no values.
@@ -2019,21 +2019,51 @@ rb_set_size(VALUE set)
20192019
*
20202020
* == Example
20212021
*
2022-
* s1 = Set[1, 2] #=> #<Set: {1, 2}>
2023-
* s2 = [1, 2].to_set #=> #<Set: {1, 2}>
2022+
* s1 = Set[1, 2] #=> Set[1, 2]
2023+
* s2 = [1, 2].to_set #=> Set[1, 2]
20242024
* s1 == s2 #=> true
2025-
* s1.add("foo") #=> #<Set: {1, 2, "foo"}>
2026-
* s1.merge([2, 6]) #=> #<Set: {1, 2, "foo", 6}>
2025+
* s1.add("foo") #=> Set[1, 2, "foo"]
2026+
* s1.merge([2, 6]) #=> Set[1, 2, "foo", 6]
20272027
* s1.subset?(s2) #=> false
20282028
* s2.subset?(s1) #=> true
20292029
*
20302030
* == Contact
20312031
*
20322032
* - Akinori MUSHA <[email protected]> (current maintainer)
20332033
*
2034-
* == What's Here
2034+
* == Inheriting from \Set
20352035
*
2036-
* First, what's elsewhere. \Class \Set:
2036+
* Before Ruby 4.0 (released December 2025), \Set had a different, less
2037+
* efficient implementation. It was reimplemented in C, and the behavior
2038+
* of some of the core methods were adjusted.
2039+
*
2040+
* To keep backward compatibility, when a class is inherited from \Set,
2041+
* additional module +Set::SubclassCompatible+ is included, which makes
2042+
* the inherited class behavior, as well as internal method names,
2043+
* closer to what it was before Ruby 4.0.
2044+
*
2045+
* It can be easily seen, for example, in the #inspect method behavior:
2046+
*
2047+
* p Set[1, 2, 3]
2048+
* # prints "Set[1, 2, 3]"
2049+
*
2050+
* class MySet < Set
2051+
* end
2052+
* p MySet[1, 2, 3]
2053+
* # prints "#<MySet: {1, 2, 3}>", like it was in Ruby 3.4
2054+
*
2055+
* For new code, if backward compatibility is not necessary,
2056+
* it is recommended to instead inherit from +Set::CoreSet+, which
2057+
* avoids including the "compatibility" layer:
2058+
*
2059+
* class MyCoreSet < Set::CoreSet
2060+
* end
2061+
* p MyCoreSet[1, 2, 3]
2062+
* # prints "MyCoreSet[1, 2, 3]"
2063+
*
2064+
* == Set's methods
2065+
*
2066+
* First, what's elsewhere. \Class \Set:
20372067
*
20382068
* - Inherits from {class Object}[rdoc-ref:Object@What-27s+Here].
20392069
* - Includes {module Enumerable}[rdoc-ref:Enumerable@What-27s+Here],
@@ -2045,16 +2075,15 @@ rb_set_size(VALUE set)
20452075
*
20462076
* Here, class \Set provides methods that are useful for:
20472077
*
2048-
* - {Creating an Array}[rdoc-ref:Array@Methods+for+Creating+an+Array]
20492078
* - {Creating a Set}[rdoc-ref:Set@Methods+for+Creating+a+Set]
20502079
* - {Set Operations}[rdoc-ref:Set@Methods+for+Set+Operations]
2051-
* - {Comparing}[rdoc-ref:Array@Methods+for+Comparing]
2052-
* - {Querying}[rdoc-ref:Array@Methods+for+Querying]
2053-
* - {Assigning}[rdoc-ref:Array@Methods+for+Assigning]
2054-
* - {Deleting}[rdoc-ref:Array@Methods+for+Deleting]
2055-
* - {Converting}[rdoc-ref:Array@Methods+for+Converting]
2056-
* - {Iterating}[rdoc-ref:Array@Methods+for+Iterating]
2057-
* - {And more....}[rdoc-ref:Array@Other+Methods]
2080+
* - {Comparing}[rdoc-ref:Set@Methods+for+Comparing]
2081+
* - {Querying}[rdoc-ref:Set@Methods+for+Querying]
2082+
* - {Assigning}[rdoc-ref:Set@Methods+for+Assigning]
2083+
* - {Deleting}[rdoc-ref:Set@Methods+for+Deleting]
2084+
* - {Converting}[rdoc-ref:Set@Methods+for+Converting]
2085+
* - {Iterating}[rdoc-ref:Set@Methods+for+Iterating]
2086+
* - {And more....}[rdoc-ref:Set@Other+Methods]
20582087
*
20592088
* === Methods for Creating a \Set
20602089
*

0 commit comments

Comments
 (0)