Built-in Functions

Strictly speaking, Ruby does not have functions, but since methods defined in the Kernel module can be called from anywhere, they can be used like functions are in other languages. Carefully consider the repercussions of redefining the methods here.

block_given?

Returns true if the method has been supplied with a block; otherwise, returns false. See Iterators for more information.

catch(tag) {|tag| .... }

Executes the block and returns its value. If a throw with the same name as tag takes place while the block is running, the return value will be that throw's second argument.

break cannot break out of all nested loops at once. Use catch in these circumstances.

catch(:loop1) {
  for i in 1..2
    for j in 1..2
      throw :loop1, j
    end
  end
}

eval(expr)

Evaluates the string expr as a Ruby program and returns the result.

exit

Exits a running Ruby program.

exit throws a SystemExit exception to terminate the program, so it can be trapped by a rescue clause where necessary.

loop { ... }

Evaluates a block in an infinite loop (until explicitly terminated).

open(file[, mode])

open(file[, mode]) {|io| ... }

Opens file and returns a File object. mode specifies one of the following strings. When mode is omitted, the default is "r".

• "r": Opens the file in read mode.
• "w": Opens the file in write mode. If a file already exists when file is opened, the previous file's contents will be deleted.
• "a": Opens file in write mode. Output will always be appended to the end of the file.

Using "+" opens the file in read-write mode (RDWR):

• "r+": Sets the read-write position to the beginning of the file.
• "w+": The same as "r+", but if a file already exists when file is opened, the previous file's contents will be deleted.
• "a+": The same as "r+", but if a file already exists when file is opened, the read-write position will be set to the end of the file.

The "b" flag can also be added to any of these (in the format "r+b") to open the file in binary mode.

When open is called along with a block, it opens the file, executes the block, then closes the file when execution is complete. The result of the block evaluation is returned in that case. See the following code sample.

open(path, mode) do |f|
   ...
end

# almost identical to the above
f = open(path, mode)
begin
   ...
ensure
  f.close
end

p(obj, [obj2, ...])

Outputs obj in a human-readable format. Identical to the following code (see Object#inspect):

print obj.inspect, "\n", obj2.inspect, "\n", ...

Returns nil.

print(arg[, ...])

Prints the arguments in order. If a non-string object has been supplied as an argument, it will be converted into a string with to_s and printed. However, if the argument is nil, it will print the string "nil".

Returns nil.

printf(format[, arg[, ...]])

Converts arguments to text according to format and outputs them, just like with printf in C. If no arguments are specified, does nothing.

See the sprintf Format page for more information on format string extension in Ruby.

Returns nil.

putc(ch)

Outputs the text ch. Outputs a string between 0 and 255 if ch is a number. Outputs the text at the beginning if ch is a text string.

Returns ch.

putc("ch")
putc(?c)
putc(99)
# => ccc

puts([obj[, obj2[, ....]]] )

Outputs obj and a line feed in that order. Outputs only a line feed if there are no arguments.

If the argument is an array, its elements and a line feed are output in that order. If an object other than an array or a character string is given as an argument, an attempt is made to first convert it to an array with to-ary and then to a character string with the to_s method. For nil, however, the string "nil" is output.

For arguments that end with a line feed, puts itself does not output a line feed.

puts "foo", "bar\n", "baz"
puts ""    # Only outputs a line feed
puts       # Only outputs a line feed
puts "foo"
=> foo
   bar
   baz


   foo

Returns nil.

raise

raise(message)

raise(exception)

raise(error_type, message)

Throws an exception. See raise for more information.

rand([max=0])

Creates a random integer in the range 0 ≤ integer < max. Automatically calls srand if it hasn't already been called.

If max is nil or 0, uses Float to return a random number in the range 0 ≤ real number < 1.

sprintf(format[, arg[, ...]])

Interprets the string format as does C's sprintf, returning a string of formatted arguments.

See sprintf Format for more information.

srand([seed])

Sets the rand random number seed and returns the old initial value. If seed is omitted, uses the current time (or a similar value) as the seed.

throw(tag[, value])

Escapes (across methods) to the end of a catch block with the same tag. If there is no catch with the same tag, the thread terminates with NameError. tag is a character string or symbol. value will be the return value of the catch.