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 {symbol 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 <code>Fred</code> is a constant in one context, a method in
another, and a class in a third, the +Symbol+ <code>:Fred</code>
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 {class Object}[rdoc-ref:Object@What-27s+Here].
- Includes {module 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) # => [:!, :"\"", :"#"]



12498
12499
12500
12501
12502
 
# File 'string.c', line 12498

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) 


12208
12209
12210
12211
12212
12213
12214
12215
 
# File 'string.c', line 12208

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:



12261
12262
12263
12264
12265
 
# File 'string.c', line 12261

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:



12311
12312
12313
12314
12315
 
# File 'string.c', line 12311

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.



12388
12389
12390
12391
12392
 
# File 'string.c', line 12388

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) 


12225
12226
12227
12228
12229
12230
12231
12232
 
# File 'string.c', line 12225

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) 


12242
12243
12244
12245
12246
12247
12248
12249
 
# File 'string.c', line 12242

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.



12372
12373
12374
12375
12376
 
# File 'string.c', line 12372

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) 


12338
12339
12340
12341
12342
 
# File 'string.c', line 12338

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:



12447
12448
12449
12450
12451
 
# File 'string.c', line 12447

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) 


12433
12434
12435
12436
12437
 
# File 'string.c', line 12433

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:



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
12148
12149
12150
12151
 
# File 'string.c', line 12117

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:



12324
12325
12326
12327
12328
 
# File 'string.c', line 12324

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:



12278
12279
12280
12281
12282
 
# File 'string.c', line 12278

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) 


12293
12294
12295
12296
12297
 
# File 'string.c', line 12293

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.



12184
12185
12186
12187
12188
 
# File 'string.c', line 12184

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:



12324
12325
12326
12327
12328
 
# File 'string.c', line 12324

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:



12311
12312
12313
12314
12315
 
# File 'string.c', line 12311

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) 


12418
12419
12420
12421
12422
 
# File 'string.c', line 12418

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.



12184
12185
12186
12187
12188
 
# File 'string.c', line 12184

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.



12404
12405
12406
12407
12408
 
# File 'string.c', line 12404

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"]



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
1541
1542
 
# File 'proc.c', line 1515

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.



12354
12355
12356
12357
12358
 
# File 'string.c', line 12354

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