Symbol

Symbol objects represent names and some strings 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.

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

Public Class Methods

all_symbols => array click to toggle source

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, :$>]

 
               VALUE
rb_sym_all_symbols(void)
{
    VALUE ary = rb_ary_new2(global_symbols.sym_id->num_entries);

    st_foreach(global_symbols.sym_id, symbols_i, ary);
    return ary;
}

Public Instance Methods

str <=> other → -1, 0, +1 or nil click to toggle source

Compares sym with other in string form.

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

sym == obj → true or false click to toggle source

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

 
               static VALUE
sym_equal(VALUE sym1, VALUE sym2)
{
    if (sym1 == sym2) return Qtrue;
    return Qfalse;
}

sym == obj → true or false click to toggle source

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

 
               static VALUE
sym_equal(VALUE sym1, VALUE sym2)
{
    if (sym1 == sym2) return Qtrue;
    return Qfalse;
}

sym =~ obj → fixnum or nil click to toggle source

Returns sym.to_s =~ obj.

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

sym[idx] → char click to toggle source

sym[b, n] → char

Returns sym.to_s[].

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

capitalize → symbol click to toggle source

Same as sym.to_s.capitalize.intern.

 
               static VALUE
sym_capitalize(VALUE sym)
{
    return rb_str_intern(rb_str_capitalize(rb_id2str(SYM2ID(sym))));
}

casecmp(other) → -1, 0, +1 or nil click to toggle source

Case-insensitive version of Symbol#<=>.

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

downcase → symbol click to toggle source

Same as sym.to_s.downcase.intern.

 
               static VALUE
sym_downcase(VALUE sym)
{
    return rb_str_intern(rb_str_downcase(rb_id2str(SYM2ID(sym))));
}

empty? → true or false click to toggle source

Returns that sym is :“” or not.

 
               static VALUE
sym_empty(VALUE sym)
{
    return rb_str_empty(rb_id2str(SYM2ID(sym)));
}

encoding → encoding click to toggle source

Returns the Encoding object that represents the encoding of sym.

 
               static VALUE
sym_encoding(VALUE sym)
{
    return rb_obj_encoding(rb_id2str(SYM2ID(sym)));
}

id2name → string click to toggle source

Returns the name or string corresponding to sym.

:fred.id2name   #=> "fred"

 
               VALUE
rb_sym_to_s(VALUE sym)
{
    ID id = SYM2ID(sym);

    return str_new3(rb_cString, rb_id2str(id));
}

inspect → string click to toggle source

Returns the representation of sym as a symbol literal.

:fred.inspect   #=> ":fred"

 
               static VALUE
sym_inspect(VALUE sym)
{
    VALUE str;
    ID id = SYM2ID(sym);
    rb_encoding *enc;
    const char *ptr;
    long len;
    char *dest;
    rb_encoding *resenc = rb_default_internal_encoding();

    if (resenc == NULL) resenc = rb_default_external_encoding();
    sym = rb_id2str(id);
    enc = STR_ENC_GET(sym);
    ptr = RSTRING_PTR(sym);
    len = RSTRING_LEN(sym);
    if ((resenc != enc && !rb_str_is_ascii_only_p(sym)) || len != (long)strlen(ptr) ||
        !rb_enc_symname_p(ptr, enc) || !sym_printable(ptr, ptr + len, enc)) {
        str = rb_str_inspect(sym);
        len = RSTRING_LEN(str);
        rb_str_resize(str, len + 1);
        dest = RSTRING_PTR(str);
        memmove(dest + 1, dest, len);
        dest[0] = ':';
    }
    else {
        char *dest;
        str = rb_enc_str_new(0, len + 1, enc);
        dest = RSTRING_PTR(str);
        dest[0] = ':';
        memcpy(dest + 1, ptr, len);
    }
    return str;
}

intern → sym click to toggle source

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

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

length → integer click to toggle source

Same as sym.to_s.length.

 
               static VALUE
sym_length(VALUE sym)
{
    return rb_str_length(rb_id2str(SYM2ID(sym)));
}

sym =~ obj → fixnum or nil click to toggle source

Returns sym.to_s =~ obj.

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

succ click to toggle source

Same as sym.to_s.succ.intern.

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

length → integer click to toggle source

Same as sym.to_s.length.

 
               static VALUE
sym_length(VALUE sym)
{
    return rb_str_length(rb_id2str(SYM2ID(sym)));
}

sym[idx] → char click to toggle source

sym[b, n] → char

Returns sym.to_s[].

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

succ click to toggle source

Same as sym.to_s.succ.intern.

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

swapcase → symbol click to toggle source

Same as sym.to_s.swapcase.intern.

 
               static VALUE
sym_swapcase(VALUE sym)
{
    return rb_str_intern(rb_str_swapcase(rb_id2str(SYM2ID(sym))));
}

to_proc click to toggle source

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

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

 
               static VALUE
sym_to_proc(VALUE sym)
{
    static VALUE sym_proc_cache = Qfalse;
    enum {SYM_PROC_CACHE_SIZE = 67};
    VALUE proc;
    long id, index;
    VALUE *aryp;

    if (!sym_proc_cache) {
        sym_proc_cache = rb_ary_tmp_new(SYM_PROC_CACHE_SIZE * 2);
        rb_gc_register_mark_object(sym_proc_cache);
        rb_ary_store(sym_proc_cache, SYM_PROC_CACHE_SIZE*2 - 1, Qnil);
    }

    id = SYM2ID(sym);
    index = (id % SYM_PROC_CACHE_SIZE) << 1;

    aryp = RARRAY_PTR(sym_proc_cache);
    if (aryp[index] == sym) {
        return aryp[index + 1];
    }
    else {
        proc = rb_proc_new(sym_call, (VALUE)id);
        aryp[index] = sym;
        aryp[index + 1] = proc;
        return proc;
    }
}

to_s → string click to toggle source

Returns the name or string corresponding to sym.

:fred.id2name   #=> "fred"

 
               VALUE
rb_sym_to_s(VALUE sym)
{
    ID id = SYM2ID(sym);

    return str_new3(rb_cString, rb_id2str(id));
}

to_sym → sym click to toggle source

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

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

upcase → symbol click to toggle source

Same as sym.to_s.upcase.intern.

 
               static VALUE
sym_upcase(VALUE sym)
{
    return rb_str_intern(rb_str_upcase(rb_id2str(SYM2ID(sym))));
}

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please visit Documenting-ruby.org.

Home Classes Methods

In Files

Parent

Methods

Included Modules

Files

Class/Module Index

Symbol

Public Class Methods

Public Instance Methods