where is the documentation for Array()?

Question

Browsing the ruleby source code, I noticed that they were calling Container(:and), which is something I rarely see. In fact, the only other place I've seen it is in the fabrication gem

A quick look showed that Container subclasses Array, and a quick hop into Pry showed that Array(:anything) #=> [:anything].

Another quick look at the ruby documentation for Array doesn't shed much light on to this question.

What method is being called by Array(), where is it documented, how can one define a method like this, and is it considered "bad form" in ruby?

Answer 1

I don't know if it is really it, but made some tests with iurb and I guess it is only a helper funcion to create a new Array.

Given I have this class

class MyClass
  def initialize(arg)
    puts "Initialized with #{arg.to_s}"
  end
end

then I can define a helper function like

def MyClass(arg)
  MyClass.new(arg)
end

and here you go

irb(main):009:0> MyClass(1)
Initialized with 1
=> #<MyClass:0x4770e10>

Answer 2

For your first question, the answer is that it makes an array of its parameters.

For your second, I have no clue, but it's simple enough.

For your third, here it is: In Ruby, defining a global method with the same name as the class is considered good form only when used to construct or convert from object of that type of a more fundamental type. You should not define this method unless you are creating some sort of low type. You could define this for some class like BigInt128 but you shouldn't for ObscureOrSpecializedType678. There is also a design for these methods.

If the data that you are passed is of the returned type, return it. If the data is of a directly related type, perform obvious conversions (Fixnum to BigInt128). If the data passed in can be converted and is somewhat related (String to Fixnum) convert it (this conversion is usually only for String). If the data can not be converted, throw an exception. You should NEVER return a "magic value".

The other use of this method is to create a semi-literal syntax for non-literal types. The best examples of this are Rational() and Complex(). These functions, in addition to doing conversions, allow you to create rations and complex numbers in a more natural way (Rational(1, 2) vs. Rational.new(1, 2)). If there is a certain argument list that is simpler to the literal representation of a type, you would define a Classname() method.

For the most part, these methods are only part of the core language, and unless you are making a class like BigInt128 or FancyString or NaturalNumber, you should not define these methods.

---

From what I know the defined of these are:

• Array(*args) -- Returns arguments as an array
• Complex(real, complex) -- Create a complex number with given real and complex parts
• Float(arg) -- Returns arg converted to a float (takes things like strings too)
• Integer(arg) -- Same as Float(), but converts to an integer(floats are truncated)
• Rational(numerator, denominator=1) -- Creates a Rational number with the given parts
• String(arg) -- Converts argument to string by calling to_s

Also, some classes define [] as a class method, which is used for more complex initialization from basic data types (usual initialization only, not conversion) such as Hash[].

Answer 3

uhhhh, since you're in Pry why not ask Pry to show you the documentation?!?!

[25] (pry) main: 0> show-doc Array

From: object.c in Ruby Core (C Method):
Number of lines: 4
Owner: Kernel
Visibility: private
Signature: Array(arg1)

Returns arg as an Array. First tries to call
arg.to_ary, then arg.to_a.

   Array(1..5)   #=> [1, 2, 3, 4, 5]
[26] (pry) main: 0> show-method Array

From: object.c in Ruby Core (C Method):
Number of lines: 5
Owner: Kernel
Visibility: private

static VALUE
rb_f_array(VALUE obj, VALUE arg)
{
    return rb_Array(arg);
}
[27] (pry) main: 0>