Class: Symbol

Inherits:
Object show all
Includes:
Comparable
Defined in:
string.c,
string.c

Overview

A Symbol object represents a named identifier inside the Ruby interpreter.

You can create a Symbol object explicitly with:

  • A literal[rdoc-ref:syntax/literals.rdoc@Symbol+Literals].

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]

A Symbol object differs from a String object in that a Symbol object represents an identifier, while a String object represents text or data.

What's Here

First, what's elsewhere. Class Symbol:

  • Inherits from Object[rdoc-ref:Object@What-27s+Here].
  • Includes Comparable[rdoc-ref:Comparable@What-27s+Here].

Here, class Symbol provides methods that are useful for:

  • Querying[rdoc-ref:Symbol@Methods+for+Querying]
  • Comparing[rdoc-ref:Symbol@Methods+for+Comparing]
  • Converting[rdoc-ref:Symbol@Methods+for+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 Method Summary collapse

Instance Method Summary collapse

Methods included from Comparable

#<, #<=, #>, #>=, #between?, #clamp

Class Method Details

.all_symbols ⇒ Object

Returns an array of all symbols currently in Ruby's symbol table:

Symbol.all_symbols.size    # => 9334
Symbol.all_symbols.take(3) # => [:!, :"\"", :"#"]


12494
12495
12496
12497
12498
 
# File 'string.c', line 12494

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

Instance Method Details

#<=>(object) ⇒ -1, ...

If object is a symbol, returns the equivalent of symbol.to_s <=> object.to_s:

:bar <=> :foo # => -1
:foo <=> :foo # => 0
:foo <=> :bar # => 1

Otherwise, returns nil:

:foo <=> 'bar' # => nil

Related: String#<=>.

Returns:

  • (-1, 0, +1, nil) 


12204
12205
12206
12207
12208
12209
12210
12211
 
# File 'string.c', line 12204

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));
}

#== ⇒ Object

#=== ⇒ Object

#=~(object) ⇒ Integer?

Equivalent to symbol.to_s =~ object, including possible updates to global variables; see String#=~.

Returns:



12257
12258
12259
12260
12261
 
# File 'string.c', line 12257

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

#[](index) ⇒ String? #[](start, length) ⇒ String? #[](range) ⇒ String? #[](regexp, capture = 0) ⇒ String? #[](substring) ⇒ String?

Equivalent to symbol.to_s; see String#[].

Overloads:



12307
12308
12309
12310
12311
 
# File 'string.c', line 12307

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

#capitalize(*options) ⇒ Object

Equivalent to sym.to_s.capitalize.to_sym.

See String#capitalize.



12384
12385
12386
12387
12388
 
# File 'string.c', line 12384

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

#casecmp(object) ⇒ -1, ...

:include: doc/symbol/casecmp.rdoc

Returns:

  • (-1, 0, 1, nil) 


12221
12222
12223
12224
12225
12226
12227
12228
 
# File 'string.c', line 12221

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

#casecmp?(object) ⇒ true, ...

:include: doc/symbol/casecmp_p.rdoc

Returns:

  • (true, false, nil) 


12238
12239
12240
12241
12242
12243
12244
12245
 
# File 'string.c', line 12238

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));
}

#downcase(*options) ⇒ Object

Equivalent to sym.to_s.downcase.to_sym.

See String#downcase.

Related: Symbol#upcase.



12368
12369
12370
12371
12372
 
# File 'string.c', line 12368

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

#empty? ⇒ Boolean

Returns true if self is :'', false otherwise.

Returns:

  • (Boolean) 


12334
12335
12336
12337
12338
 
# File 'string.c', line 12334

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

#encoding ⇒ Encoding

Equivalent to self.to_s.encoding; see String#encoding.

Returns:



12443
12444
12445
12446
12447
 
# File 'string.c', line 12443

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

#end_with?(*strings) ⇒ Boolean

Equivalent to self.to_s.end_with?; see String#end_with?.

Returns:

  • (Boolean) 


12429
12430
12431
12432
12433
 
# File 'string.c', line 12429

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

#inspect ⇒ String

Returns a string representation of self (including the leading colon):

:foo.inspect # => ":foo"

Related: Symbol#to_s, Symbol#name.

Returns:



12113
12114
12115
12116
12117
12118
12119
12120
12121
12122
12123
12124
12125
12126
12127
12128
12129
12130
12131
12132
12133
12134
12135
12136
12137
12138
12139
12140
12141
12142
12143
12144
12145
12146
12147
 
# File 'string.c', line 12113

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);
        VALUE orig_str = str;

        len = RSTRING_LEN(orig_str);
        str = rb_enc_str_new(0, len + 1, enc);

        // Get data pointer after allocation
        ptr = RSTRING_PTR(orig_str);
        dest = RSTRING_PTR(str);
        memcpy(dest + 1, ptr, len);

        RB_GC_GUARD(orig_str);
    }
    dest[0] = ':';

    RUBY_ASSERT_BUILTIN_TYPE(str, T_STRING);

    return str;
}

#length ⇒ Integer

Equivalent to self.to_s.length; see String#length.

Returns:



12320
12321
12322
12323
12324
 
# File 'string.c', line 12320

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

#match(pattern, offset = 0) ⇒ MatchData? #match(pattern, offset = 0) {|matchdata| ... } ⇒ Object

Equivalent to self.to_s.match, including possible updates to global variables; see String#match.

Overloads:

  • #match(pattern, offset = 0) ⇒ MatchData?

    Returns:

  • #match(pattern, offset = 0) {|matchdata| ... } ⇒ Object

    Yields:

    • (matchdata)

    Returns:



12274
12275
12276
12277
12278
 
# File 'string.c', line 12274

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

#match?(pattern, offset) ⇒ Boolean

Equivalent to sym.to_s.match?; see String#match.

Returns:

  • (Boolean) 


12289
12290
12291
12292
12293
 
# File 'string.c', line 12289

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

#succ ⇒ Object

Equivalent to self.to_s.succ.to_sym:

:foo.succ # => :fop

Related: String#succ.



12180
12181
12182
12183
12184
 
# File 'string.c', line 12180

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

#length ⇒ Integer

Equivalent to self.to_s.length; see String#length.

Returns:



12320
12321
12322
12323
12324
 
# File 'string.c', line 12320

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

#[](index) ⇒ String? #[](start, length) ⇒ String? #[](range) ⇒ String? #[](regexp, capture = 0) ⇒ String? #[](substring) ⇒ String?

Equivalent to symbol.to_s; see String#[].

Overloads:



12307
12308
12309
12310
12311
 
# File 'string.c', line 12307

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

#start_with?(*string_or_regexp) ⇒ Boolean

Equivalent to self.to_s.start_with?; see String#start_with?.

Returns:

  • (Boolean) 


12414
12415
12416
12417
12418
 
# File 'string.c', line 12414

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

#succ ⇒ Object

Equivalent to self.to_s.succ.to_sym:

:foo.succ # => :fop

Related: String#succ.



12180
12181
12182
12183
12184
 
# File 'string.c', line 12180

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

#swapcase(*options) ⇒ Object

Equivalent to sym.to_s.swapcase.to_sym.

See String#swapcase.



12400
12401
12402
12403
12404
 
# File 'string.c', line 12400

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

#to_proc ⇒ Object

Returns a Proc object which calls the method with name of self on the first parameter and passes the remaining parameters to the method.

proc = :to_s.to_proc   # => #<Proc:0x000001afe0e48680(&:to_s) (lambda)>
proc.call(1000)        # => "1000"
proc.call(1000, 16)    # => "3e8"
(1..3).collect(&:to_s) # => ["1", "2", "3"]


1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
 
# File 'proc.c', line 1513

VALUE
rb_sym_to_proc(VALUE sym)
{
    static VALUE sym_proc_cache = Qfalse;
    enum {SYM_PROC_CACHE_SIZE = 67};
    VALUE proc;
    long index;
    ID id;

    if (!sym_proc_cache) {
        sym_proc_cache = rb_ary_hidden_new(SYM_PROC_CACHE_SIZE * 2);
        rb_vm_register_global_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;

    if (RARRAY_AREF(sym_proc_cache, index) == sym) {
        return RARRAY_AREF(sym_proc_cache, index + 1);
    }
    else {
        proc = sym_proc_new(rb_cProc, ID2SYM(id));
        RARRAY_ASET(sym_proc_cache, index, sym);
        RARRAY_ASET(sym_proc_cache, index + 1, proc);
        return proc;
    }
}

#upcase(*options) ⇒ Object

Equivalent to sym.to_s.upcase.to_sym.

See String#upcase.



12350
12351
12352
12353
12354
 
# File 'string.c', line 12350

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