Symbol

Symbol objects represent named identifiers inside the Ruby interpreter.

You can create a Symbol object explicitly with:

• A symbol literal.

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
  end
  $f1 = :Fred
end
module Two
  Fred = 1
  $f2 = :Fred
end
def Fred()
end
$f3 = :Fred
$f1.object_id   #=> 2514190
$f2.object_id   #=> 2514190
$f3.object_id   #=> 2514190

Constant, method, and variable names are returned as symbols:

module One
  Two = 2
  def three; 3 end
  @four = 4
  @@five = 5
  $six = 6
end
seven = 7

One.constants
# => [:Two]
One.instance_methods(true)
# => [:three]
One.instance_variables
# => [:@four]
One.class_variables
# => [:@@five]
global_variables.grep(/six/)
# => [:$six]
local_variables
# => [:seven]

Symbol objects are different from String objects in that Symbol objects represent identifiers, while String objects represent text or data.

What’s Here

First, what’s elsewhere. Class Symbol:

• Inherits from class Object.

• Includes module Comparable.

Here, class Symbol provides methods that are useful for:

• Querying

• Comparing

• Converting

Methods for Querying

• ::all_symbols

  Returns an array of the symbols currently in Ruby’s symbol table.

• #=~

  Returns the index of the first substring in symbol that matches a given Regexp or other object; returns nil if no match is found.

• [], slice

  Returns a substring of symbol determined by a given index, start/length, or range, or string.

• empty?

  Returns true if self.length is zero; false otherwise.

• encoding

  Returns the Encoding object that represents the encoding of symbol.

• end_with?

  Returns true if symbol ends with any of the given strings.

• match

  Returns a MatchData object if symbol matches a given Regexp; nil otherwise.

• match?

  Returns true if symbol matches a given Regexp; false otherwise.

• length, size

  Returns the number of characters in symbol.

• start_with?

  Returns true if symbol starts with any of the given strings.

Methods for Comparing

• #<=>

  Returns -1, 0, or 1 as a given symbol is smaller than, equal to, or larger than symbol.

• #==, #===

  Returns true if a given symbol has the same content and encoding.

• casecmp

  Ignoring case, returns -1, 0, or 1 as a given symbol is smaller than, equal to, or larger than symbol.

• casecmp?

  Returns true if symbol is equal to a given symbol after Unicode case folding; false otherwise.

Methods for Converting

• capitalize

  Returns symbol with the first character upcased and all other characters downcased.

• downcase

  Returns symbol with all characters downcased.

• inspect

  Returns the string representation of self as a symbol literal.

• name

  Returns the frozen string corresponding to symbol.

• succ, next

  Returns the symbol that is the successor to symbol.

• swapcase

  Returns symbol with all upcase characters downcased and all downcase characters upcased.

• to_proc

  Returns a Proc object which responds to the method named by symbol.

• to_s, id2name

  Returns the string corresponding to self.

• to_sym, intern

  Returns self.

• upcase

  Returns symbol with all characters upcased.