diff --git a/array.c b/array.c index 240fb7e0f5..8becdbbc91 100644 --- a/array.c +++ b/array.c @@ -7843,13 +7843,20 @@ rb_ary_deconstruct(VALUE ary) * * == Creating Arrays * - * A new array can be created by using the literal constructor - * []. Arrays can contain different types of objects. For + * You can create an \Array object explicitly with: + * + * - An {array literal}[doc/syntax/literals_rdoc.html#label-Array+Literals]. + * + * You can convert certain objects to Arrays with: + * + * - \Method {Array}[Kernel.html#method-i-Array]. + * + * An \Array can contain different types of objects. For * example, the array below contains an Integer, a String and a Float: * * ary = [1, "two", 3.0] #=> [1, "two", 3.0] * - * An array can also be created by explicitly calling Array.new with zero, one + * An array can also be created by calling Array.new with zero, one * (the initial size of the Array) or two arguments (the initial size and a * default object). * diff --git a/complex.c b/complex.c index 3b4b05a2bb..a3dda4d0e1 100644 --- a/complex.c +++ b/complex.c @@ -2267,6 +2267,14 @@ float_arg(VALUE self) * and i is imaginary unit. Real a equals complex a+0i * mathematically. * + * You can create a \Complex object explicitly with: + * + * - A {complex literal}[doc/syntax/literals_rdoc.html#label-Complex+Literals]. + * + * You can convert certain objects to \Complex objects with: + * + * - \Method {Complex}[Kernel.html#method-i-Complex]. + * * Complex object can be created as literal, and also by using * Kernel#Complex, Complex::rect, Complex::polar or to_c method. * diff --git a/doc/syntax/literals.rdoc b/doc/syntax/literals.rdoc index b663f27816..45d3d90c58 100644 --- a/doc/syntax/literals.rdoc +++ b/doc/syntax/literals.rdoc @@ -9,10 +9,10 @@ Literals create objects you can use in your program. Literals include: * Arrays * Hashes * Ranges -* Regular Expressions -* Procs +* Regexps +* Lambda Procs -== Booleans and nil +== Boolean and Nil Literals +nil+ and +false+ are both false values. +nil+ is sometimes used to indicate "no value" or "unknown" but evaluates to +false+ in conditional expressions. @@ -61,7 +61,7 @@ Examples: All these numbers have the same decimal value, 170. Like integers and floats you may use an underscore for readability. -=== Floating-Point Literals +=== \Float Literals Floating-point numbers may be written as follows: @@ -72,35 +72,37 @@ Floating-point numbers may be written as follows: These numbers have the same value, 12.34. You may use underscores in floating point numbers as well. -=== Rational Numbers +=== \Rational Literals -Numbers suffixed by +r+ are Rational numbers. +You can write a Rational number as follows (suffixed +r+): 12r #=> (12/1) 12.3r #=> (123/10) -Rational numbers are exact, whereas Float numbers are inexact. +A \Rational number is exact, whereas a \Float number may be inexact. 0.1r + 0.2r #=> (3/10) 0.1 + 0.2 #=> 0.30000000000000004 -=== Complex numbers +=== \Complex Literals -Numbers suffixed by +i+ are Complex (or imaginary) numbers. +You can write a Complex number as follows (suffixed +i+): 1i #=> (0+1i) 1i * 1i #=> (-1+0i) -Also Rational numbers may be imaginary numbers. +Also \Rational numbers may be imaginary numbers. 12.3ri #=> (0+(123/10)*i) -+i+ must be placed after +r+, the opposite is not allowed. ++i+ must be placed after +r+; the opposite is not allowed. - 12.3ir #=> syntax error + 12.3ir #=> Syntax error == Strings +=== \String Literals + The most common way of writing strings is using ": "This is a string." @@ -198,7 +200,7 @@ a single codepoint in the script encoding: ?\C-\M-a #=> "\x81", same as above ?あ #=> "あ" -=== Here Documents (heredocs) +=== Here Document Literals If you are writing a large block of text you may use a "here document" or "heredoc": @@ -278,7 +280,7 @@ read: content for heredoc two TWO -== Symbols +== \Symbol Literals A Symbol represents a name inside the ruby interpreter. See Symbol for more details on what symbols are and when ruby creates them internally. @@ -297,7 +299,7 @@ Like strings, a single-quote may be used to disable interpolation: When creating a Hash, there is a special syntax for referencing a Symbol as well. -== Arrays +== \Array Literals An array is created using the objects between [ and ]: @@ -310,7 +312,7 @@ You may place expressions inside the array: See Array for the methods you may use with an array. -== Hashes +== \Hash Literals A hash is created using key-value pairs between { and }: @@ -334,7 +336,7 @@ is equal to See Hash for the methods you may use with a hash. -== Ranges +== \Range Literals A range represents an interval of values. The range may include or exclude its ending value. @@ -347,7 +349,7 @@ its ending value. You may create a range of any object. See the Range documentation for details on the methods you need to implement. -== Regular Expressions +== \Regexp Literals A regular expression is created using "/": @@ -365,7 +367,7 @@ characters than a string. See Regexp for a description of the syntax of regular expressions. -== Procs +== Lambda Proc Literals A lambda proc can be created with ->: @@ -379,13 +381,13 @@ You can require arguments for the proc as follows: This proc will add one to its argument. -== Percent Strings +== Percent Literals Besides %(...) which creates a String, the % may create other types of object. As with strings, an uppercase letter allows interpolation and escaped characters while a lowercase letter disables them. -These are the types of percent strings in ruby: +These are the types of percent literals: %i :: Array of Symbols %q :: String diff --git a/hash.c b/hash.c index aee671da34..270ddfb522 100644 --- a/hash.c +++ b/hash.c @@ -6598,13 +6598,13 @@ env_dup(VALUE obj) * * === Creating a \Hash * - * Here are three ways to create a \Hash: + * You can create a \Hash object explicitly with: * - * - \Method Hash.new - * - \Method Hash[] - * - Literal form: {}. + * - A {hash literal}[doc/syntax/literals_rdoc.html#label-Hash+Literals]. * - * --- + * You can convert certain objects to Hashes with: + * + * - \Method {Hash}[Kernel.html#method-i-Hash]. * * You can create a \Hash by calling method Hash.new. * @@ -6614,8 +6614,6 @@ env_dup(VALUE obj) * h # => {} * h.class # => Hash * - * --- - * * You can create a \Hash by calling method Hash.[]. * * Create an empty Hash: @@ -6628,8 +6626,6 @@ env_dup(VALUE obj) * h = Hash[foo: 0, bar: 1, baz: 2] * h # => {:foo=>0, :bar=>1, :baz=>2} * - * --- - * * You can create a \Hash by using its literal form (curly braces). * * Create an empty \Hash: diff --git a/numeric.c b/numeric.c index d126e16d29..28b68a71fb 100644 --- a/numeric.c +++ b/numeric.c @@ -948,8 +948,11 @@ num_negative_p(VALUE num) * * You can create a \Float object explicitly with: * - * - Global method {Float}[Kernel.html#method-i-Float]. - * - A {floating-point literal}[doc/syntax/literals_rdoc.html#label-Floating-Point+Literals]. + * - A {floating-point literal}[doc/syntax/literals_rdoc.html#label-Float+Literals]. + * + * You can convert certain objects to Floats with: + * + * - \Method {Float}[Kernel.html#method-i-Float]. * * == What's Here * @@ -3479,9 +3482,12 @@ rb_num2ull(VALUE val) * * You can create an \Integer object explicitly with: * - * - Global method {Integer}[Kernel.html#method-i-Integer]. * - An {integer literal}[doc/syntax/literals_rdoc.html#label-Integer+Literals]. * + * You can convert certain objects to Integers with: + * + * - \Method {Integer}[Kernel.html#method-i-Integer]. + * * An attempt to add a singleton method to an instance of this class * causes an exception to be raised. * diff --git a/proc.c b/proc.c index 13996b102a..94b269d694 100644 --- a/proc.c +++ b/proc.c @@ -3845,7 +3845,8 @@ proc_ruby2_keywords(VALUE procval) * * lambda1 = lambda {|x| x**2 } * - * * Use the Lambda literal syntax (also constructs a proc with lambda semantics): + * * Use the {Lambda proc literal}[doc/syntax/literals_rdoc.html#label-Lambda+Proc+Literals] syntax + * (also constructs a proc with lambda semantics): * * lambda2 = ->(x) { x**2 } * diff --git a/range.c b/range.c index 6ac7d794c6..6eb7842313 100644 --- a/range.c +++ b/range.c @@ -2050,14 +2050,16 @@ range_count(int argc, VALUE *argv, VALUE range) /* A \Range object represents a collection of values * that are between given begin and end values. * - * A range may be created using a literal: + * You can create an \Range object explicitly with: * - * # Ranges that use '..' to include the given end value. - * (1..4).to_a # => [1, 2, 3, 4] - * ('a'..'d').to_a # => ["a", "b", "c", "d"] - * # Ranges that use '...' to exclude the given end value. - * (1...4).to_a # => [1, 2, 3] - * ('a'...'d').to_a # => ["a", "b", "c"] + * - A {range literal}[doc/syntax/literals_rdoc.html#label-Range+Literals]: + * + * # Ranges that use '..' to include the given end value. + * (1..4).to_a # => [1, 2, 3, 4] + * ('a'..'d').to_a # => ["a", "b", "c", "d"] + * # Ranges that use '...' to exclude the given end value. + * (1...4).to_a # => [1, 2, 3] + * ('a'...'d').to_a # => ["a", "b", "c"] * * A range may be created using method Range.new: * diff --git a/rational.c b/rational.c index b903decaf6..7817bdbcef 100644 --- a/rational.c +++ b/rational.c @@ -2715,13 +2715,19 @@ nurat_s_convert(int argc, VALUE *argv, VALUE klass) * a/b (b>0), where a is the numerator and b is the denominator. * Integer a equals rational a/1 mathematically. * - * In Ruby, you can create rational objects with the Kernel#Rational, - * to_r, or rationalize methods or by suffixing +r+ to a literal. - * The return values will be irreducible fractions. + * You can create a \Rational object explicitly with: + * + * - A {rational literal}[doc/syntax/literals_rdoc.html#label-Rational+Literals]. + * + * You can convert certain objects to Rationals with: + * + * - \Method {Rational}[Kernel.html#method-i-Rational]. + * + * Examples * * Rational(1) #=> (1/1) * Rational(2, 3) #=> (2/3) - * Rational(4, -6) #=> (-2/3) + * Rational(4, -6) #=> (-2/3) # Reduced. * 3.to_r #=> (3/1) * 2/3r #=> (2/3) * diff --git a/re.c b/re.c index cccedc9869..d91909a743 100644 --- a/re.c +++ b/re.c @@ -4082,6 +4082,10 @@ re_warn(const char *s) * and %r{...} literals, and by the Regexp::new * constructor. * + * You can create a \Regexp object explicitly with: + * + * - A {regexp literal}[doc/syntax/literals_rdoc.html#label-Regexp+Literals]. + * * :include: doc/regexp.rdoc */ diff --git a/string.c b/string.c index 303cd9b98b..9dcc8282c5 100644 --- a/string.c +++ b/string.c @@ -11152,15 +11152,18 @@ rb_str_unicode_normalized_p(int argc, VALUE *argv, VALUE str) /********************************************************************** * Document-class: Symbol * - * Symbol objects represent named identifiers inside the Ruby interpreter. They - * are generated using the :name and - * :"string" literals syntax, and by the various - * to_sym methods. The same Symbol object will be - * created for a given name or string for the duration of a program's - * execution, regardless of the context or meaning of that name. Thus - * if Fred is a constant in one context, a method in - * another, and a class in a third, the Symbol :Fred - * will be the same object in all three contexts. + * Symbol objects represent named identifiers inside the Ruby interpreter. + * + * You can create a \Symbol object explicitly with: + * + * - A {symbol literal}[doc/syntax/literals_rdoc.html#label-Symbol+Literals]. + * + * The same Symbol object will be + * created for a given name or string for the duration of a program's + * execution, regardless of the context or meaning of that name. Thus + * if Fred is a constant in one context, a method in + * another, and a class in a third, the Symbol :Fred + * will be the same object in all three contexts. * * module One * class Fred @@ -11795,6 +11798,15 @@ rb_enc_interned_str_cstr(const char *ptr, rb_encoding *enc) * String objects differ from Symbol objects in that Symbol objects are * designed to be used as identifiers, instead of text or data. * + * You can create a \String object explicitly with: + * + * - A {string literal}[doc/syntax/literals_rdoc.html#label-String+Literals]. + * - A {heredoc literal}[doc/syntax/literals_rdoc.html#label-Here+Document+Literals]. + * + * You can convert certain objects to Strings with: + * + * - \Method {String}[Kernel.html#method-i-String]. + * * Some \String methods modify +self+. * Typically, a method whose name ends with ! modifies +self+ * and returns +self+;