Symbol

Class

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.

Class Methods

Symbol.all_symbols => array

string.c View on GitHub

          
            static VALUE
sym_all_symbols(VALUE _)
{
    return rb_sym_all_symbols();
}

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

Symbol.all_symbols.size    #=> 903
Symbol.all_symbols[1,20]   #=> [:floor, :ARGV, :Binding, :symlink,
                                :chown, :EOFError, :$;, :String,
                                :LOCK_SH, :"setuid?", :$<,
                                :default_proc, :compact, :extend,
                                :Tms, :getwd, :$=, :ThreadGroup,
                                :wait2, :$>]

json_create(o)

ext/json/lib/json/add/symbol.rb View on GitHub

          
            # File tmp/rubies/ruby-3.1.2/ext/json/lib/json/add/symbol.rb, line 22
def self.json_create(o)
  o['s'].to_sym
end

Deserializes JSON string by converting the string value stored in the object to a Symbol

Instance Methods

symbol <=> other_symbol → -1, 0, +1, or nil

string.c View on GitHub

          
            static VALUE
sym_cmp(VALUE sym, VALUE other)
{
    if (!SYMBOL_P(other)) {
        return Qnil;
    }
    return rb_str_cmp_m(rb_sym2str(sym), rb_sym2str(other));
}

Compares symbol with other_symbol after calling to_s on each of the symbols. Returns -1, 0, +1, or nil depending on whether symbol is less than, equal to, or greater than other_symbol.

nil is returned if the two values are incomparable.

See String#<=> for more information.

sym == obj → true or false

string.c View on GitHub

          
            #define sym_equal rb_obj_equal

Equality—If sym and obj are exactly the same symbol, returns true.

===(p1)

string.c View on GitHub

An alias for ==

sym =~ obj → integer or nil

string.c View on GitHub

          
            static VALUE
sym_match(VALUE sym, VALUE other)
{
    return rb_str_match(rb_sym2str(sym), other);
}

Returns sym.to_s =~ obj.

sym[idx] → char

sym[b, n] → string

string.c View on GitHub

          
            static VALUE
sym_aref(int argc, VALUE *argv, VALUE sym)
{
    return rb_str_aref_m(argc, argv, rb_sym2str(sym));
}

Returns sym.to_s[].

as_json(*)

ext/json/lib/json/add/symbol.rb View on GitHub

          
            # File tmp/rubies/ruby-3.1.2/ext/json/lib/json/add/symbol.rb, line 9
def as_json(*)
  {
    JSON.create_id => self.class.name,
    's'            => to_s,
  }
end

Returns a hash, that will be turned into a JSON object and represent this object.

capitalize(*options) → symbol

string.c View on GitHub

          
            static VALUE
sym_capitalize(int argc, VALUE *argv, VALUE sym)
{
    return rb_str_intern(rb_str_capitalize(argc, argv, rb_sym2str(sym)));
}

Equivalent to sym.to_s.capitalize.to_sym.

See String#capitalize.

casecmp(other_symbol) → -1, 0, 1, or nil

string.c View on GitHub

          
            static VALUE
sym_casecmp(VALUE sym, VALUE other)
{
    if (!SYMBOL_P(other)) {
        return Qnil;
    }
    return str_casecmp(rb_sym2str(sym), rb_sym2str(other));
}

Case-insensitive version of Symbol#<=>:

:aBcDeF.casecmp(:abcde)   # => 1
:aBcDeF.casecmp(:abcdef)  # => 0
:aBcDeF.casecmp(:abcdefg) # => -1
:abcdef.casecmp(:ABCDEF)  # => 0

Returns nil if the two symbols have incompatible encodings, or if other_symbol is not a symbol:

sym = "\u{e4 f6 fc}".encode("ISO-8859-1").to_sym
other_sym = :"\u{c4 d6 dc}"
sym.casecmp(other_sym) # => nil
:foo.casecmp(2)        # => nil

Currently, case-insensitivity only works on characters A-Z/a-z, not all of Unicode. This is different from Symbol#casecmp?.

Related: Symbol#casecmp?.

casecmp?(other_symbol) → true, false, or nil

string.c View on GitHub

          
            static VALUE
sym_casecmp_p(VALUE sym, VALUE other)
{
    if (!SYMBOL_P(other)) {
        return Qnil;
    }
    return str_casecmp_p(rb_sym2str(sym), rb_sym2str(other));
}

Returns true if sym and other_symbol are equal after Unicode case folding, false if they are not equal:

:aBcDeF.casecmp?(:abcde)                  # => false
:aBcDeF.casecmp?(:abcdef)                 # => true
:aBcDeF.casecmp?(:abcdefg)                # => false
:abcdef.casecmp?(:ABCDEF)                 # => true
:"\u{e4 f6 fc}".casecmp?(:"\u{c4 d6 dc}") #=> true

Returns nil if the two symbols have incompatible encodings, or if other_symbol is not a symbol:

sym = "\u{e4 f6 fc}".encode("ISO-8859-1").to_sym
other_sym = :"\u{c4 d6 dc}"
sym.casecmp?(other_sym) # => nil
:foo.casecmp?(2)        # => nil

See Case Mapping.

Related: Symbol#casecmp.

downcase(*options) → symbol

string.c View on GitHub

          
            static VALUE
sym_downcase(int argc, VALUE *argv, VALUE sym)
{
    return rb_str_intern(rb_str_downcase(argc, argv, rb_sym2str(sym)));
}

Equivalent to sym.to_s.downcase.to_sym.

See String#downcase.

Related: Symbol#upcase.

sym.empty? → true or false

string.c View on GitHub

          
            static VALUE
sym_empty(VALUE sym)
{
    return rb_str_empty(rb_sym2str(sym));
}

Returns whether sym is :“” or not.

sym.encoding → encoding

string.c View on GitHub

          
            static VALUE
sym_encoding(VALUE sym)
{
    return rb_obj_encoding(rb_sym2str(sym));
}

Returns the Encoding object that represents the encoding of sym.

sym.end_with?([suffixes]+) → true or false

string.c View on GitHub

          
            static VALUE
sym_end_with(int argc, VALUE *argv, VALUE sym)
{
    return rb_str_end_with(argc, argv, rb_sym2str(sym));
}

Returns true if sym ends with one of the suffixes given.

:hello.end_with?("ello")               #=> true

# returns true if one of the +suffixes+ matches.
:hello.end_with?("heaven", "ello")     #=> true
:hello.end_with?("heaven", "paradise") #=> false

sym.id2name → string

string.c View on GitHub

An alias for to_s

sym.inspect → string

string.c View on GitHub

          
            static VALUE
sym_inspect(VALUE sym)
{
    VALUE str = rb_sym2str(sym);
    const char *ptr;
    long len;
    char *dest;

    if (!rb_str_symname_p(str)) {
        str = rb_str_inspect(str);
        len = RSTRING_LEN(str);
        rb_str_resize(str, len + 1);
        dest = RSTRING_PTR(str);
        memmove(dest + 1, dest, len);
    }
    else {
        rb_encoding *enc = STR_ENC_GET(str);
        RSTRING_GETMEM(str, ptr, len);
        str = rb_enc_str_new(0, len + 1, enc);
        dest = RSTRING_PTR(str);
        memcpy(dest + 1, ptr, len);
    }
    dest[0] = ':';
    return str;
}

Returns the representation of sym as a symbol literal.

:fred.inspect   #=> ":fred"

sym.intern → sym

string.c View on GitHub

          
            static VALUE
sym_to_sym(VALUE sym)
{
    return sym;
}

In general, to_sym returns the Symbol corresponding to an object. As sym is already a symbol, self is returned in this case.

sym.length → integer

string.c View on GitHub

          
            static VALUE
sym_length(VALUE sym)
{
    return rb_str_length(rb_sym2str(sym));
}

Same as sym.to_s.length.

sym.match(pattern) → matchdata or nil

sym.match(pattern, pos) → matchdata or nil

string.c View on GitHub

          
            static VALUE
sym_match_m(int argc, VALUE *argv, VALUE sym)
{
    return rb_str_match_m(argc, argv, rb_sym2str(sym));
}

Returns sym.to_s.match.

sym.match?(pattern) → true or false

sym.match?(pattern, pos) → true or false

string.c View on GitHub

          
            static VALUE
sym_match_m_p(int argc, VALUE *argv, VALUE sym)
{
    return rb_str_match_m_p(argc, argv, sym);
}

Returns sym.to_s.match?.

sym.name → string

string.c View on GitHub

          
            VALUE
rb_sym2str(VALUE sym)
{

}

Returns the name or string corresponding to sym. Unlike to_s, the returned string is frozen.

:fred.name         #=> "fred"
:fred.name.frozen? #=> true
:fred.to_s         #=> "fred"
:fred.to_s.frozen? #=> false

string.c View on GitHub

An alias for succ

          
            static VALUE
sym_start_with(int argc, VALUE *argv, VALUE sym)
{
    return rb_str_start_with(argc, argv, rb_sym2str(sym));
}

Returns true if sym starts with one of the prefixes given. Each of the prefixes should be a String or a Regexp.

:hello.start_with?("hell")               #=> true
:hello.start_with?(/H/i)                 #=> true

# returns true if one of the prefixes matches.
:hello.start_with?("heaven", "hell")     #=> true
:hello.start_with?("heaven", "paradise") #=> false

sym.succ

string.c View on GitHub

          
            static VALUE
sym_succ(VALUE sym)
{
    return rb_str_intern(rb_str_succ(rb_sym2str(sym)));
}

Same as sym.to_s.succ.intern.

swapcase(*options) → symbol

string.c View on GitHub

          
            static VALUE
sym_swapcase(int argc, VALUE *argv, VALUE sym)
{
    return rb_str_intern(rb_str_swapcase(argc, argv, rb_sym2str(sym)));
}

Equivalent to sym.to_s.swapcase.to_sym.

See String#swapcase.

to_json(*a)

ext/json/lib/json/add/symbol.rb View on GitHub

          
            # File tmp/rubies/ruby-3.1.2/ext/json/lib/json/add/symbol.rb, line 17
def to_json(*a)
  as_json.to_json(*a)
end

Stores class name (Symbol) with String representation of Symbol as a JSON string.

sym.to_proc

string.c View on GitHub

          
            VALUE
rb_sym_to_proc(VALUE sym)
{
}

Returns a Proc object which responds to the given method by sym.

(1..3).collect(&:to_s)  #=> ["1", "2", "3"]

sym.to_s → string

string.c View on GitHub

          
            VALUE
rb_sym_to_s(VALUE sym)
{
    return str_new_shared(rb_cString, rb_sym2str(sym));
}

Returns the name or string corresponding to sym.

:fred.id2name   #=> "fred"
:ginger.to_s    #=> "ginger"

Note that this string is not frozen (unlike the symbol itself). To get a frozen string, use name.

sym.to_sym → sym

string.c View on GitHub

An alias for intern

upcase(*options) → symbol

string.c View on GitHub

          
            static VALUE
sym_upcase(int argc, VALUE *argv, VALUE sym)
{
    return rb_str_intern(rb_str_upcase(argc, argv, rb_sym2str(sym)));
}

Equivalent to sym.to_s.upcase.to_sym.

See String#upcase.

Symbol

What’s Here

Methods for Querying

Methods for Comparing

Methods for Converting

Symbol.all_symbols => array

json_create(o)

symbol <=> other_symbol → -1, 0, +1, or nil

sym == obj → true or false

===(p1)

sym =~ obj → integer or nil

sym[idx] → char

sym[b, n] → string

as_json(*)

capitalize(*options) → symbol

casecmp(other_symbol) → -1, 0, 1, or nil

casecmp?(other_symbol) → true, false, or nil

downcase(*options) → symbol

sym.empty? → true or false

sym.encoding → encoding

sym.end_with?([suffixes]+) → true or false

sym.id2name → string

sym.inspect → string

sym.intern → sym

sym.length → integer

sym.match(pattern) → matchdata or nil

sym.match(pattern, pos) → matchdata or nil

sym.match?(pattern) → true or false

sym.match?(pattern, pos) → true or false

sym.name → string

next

sym.size → integer

sym.slice(idx) → char

sym.slice(b, n) → string

sym.start_with?([prefixes]+) → true or false

sym.succ

swapcase(*options) → symbol

to_json(*a)

sym.to_proc

sym.to_s → string

sym.to_sym → sym

upcase(*options) → symbol