# class StringPool

- StringPool
- Reference
- Object

##
Overview

A string pool is a collection of strings. It allows a runtime to save memory by preserving strings in a pool, allowing to reuse an instance of a common string instead of creating a new one.

NOTE To use `StringPool`, you must explicitly import it with `require "string_pool"`

    require "string_pool"

    pool = StringPool.new
    a = "foo" + "bar"
    b = "foo" + "bar"
    a.object_id # => 136294360
    b.object_id # => 136294336
    a = pool.get(a)
    b = pool.get(b)
    a.object_id # => 136294312
    b.object_id # => 136294312

##
Defined in:

string_pool.cr

##
Constructors

- .new(initial_capacity = 8)

  Creates a new empty string pool.

##
Instance Method Summary

- #empty? : Bool

  Returns `true` if the `StringPool` has no element otherwise returns `false`.

- #get(str : Pointer(UInt8), len) : String

  Returns a `String` with the contents given by the pointer str of size len.

- #get(slice : Bytes) : String

  Returns a `String` with the contents of the given slice.

- #get(str : IO::Memory) : String

  Returns a `String` with the contents of the given `IO::Memory`.

- #get(str : String) : String

  Returns a `String` with the contents of the given string.

- #get?(str : Pointer(UInt8), len) : String | Nil

  Returns a `String` with the contents given by the pointer str of size len, or `nil` if no such string exists in the pool.

- #get?(slice : Bytes) : String | Nil

  Returns a `String` with the contents of the given slice, or `nil` if no such string exists in the pool.

- #get?(str : IO::Memory) : String | Nil

  Returns a `String` with the contents of the given `IO::Memory`, or `nil` if no such string exists in the pool.

- #get?(str : String) : String | Nil

  Returns a `String` with the contents of the given string, or `nil` if no such string exists in the pool.

- #rehash : Nil

  Rebuilds the hash based on the current hash values for each key, if values of key objects have changed since they were inserted.

- #size : Int32

  Returns the size

### Instance methods inherited from class `Reference`

==(other : self)
==(other : JSON::Any)
==(other : YAML::Any)
==(other) ==, dup dup, hash(hasher) hash, initialize initialize, inspect(io : IO) : Nil inspect, object_id : UInt64 object_id, pretty_print(pp) : Nil pretty_print, same?(other : Reference) : Bool
same?(other : Nil) same?, to_s(io : IO) : Nil to_s

### Constructor methods inherited from class `Reference`

new new, unsafe_construct(address : Pointer, *args, **opts) : self unsafe_construct

### Class methods inherited from class `Reference`

pre_initialize(address : Pointer) pre_initialize

### Instance methods inherited from class `Object`

! : Bool !, !=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other) ===, =~(other) =~, as(type : Class) as, as?(type : Class) as?, class class, dup dup, hash(hasher)
hash hash, in?(collection : Object) : Bool
in?(*values : Object) : Bool in?, inspect(io : IO) : Nil
inspect : String inspect, is_a?(type : Class) : Bool is_a?, itself itself, nil? : Bool nil?, not_nil!(message)
not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, responds_to?(name : Symbol) : Bool responds_to?, tap(&) tap, to_json(io : IO) : Nil
to_json : String to_json, to_pretty_json(indent : String = " ") : String
to_pretty_json(io : IO, indent : String = " ") : Nil to_pretty_json, to_s(io : IO) : Nil
to_s : String to_s, to_yaml(io : IO) : Nil
to_yaml : String to_yaml, try(&) try, unsafe_as(type : T.class) forall T unsafe_as

### Class methods inherited from class `Object`

from_json(string_or_io, root : String)
from_json(string_or_io) from_json, from_yaml(string_or_io : String | IO) from_yaml

### Macros inherited from class `Object`

class_getter(*names, &block) class_getter, class_getter!(*names) class_getter!, class_getter?(*names, &block) class_getter?, class_property(*names, &block) class_property, class_property!(*names) class_property!, class_property?(*names, &block) class_property?, class_setter(*names) class_setter, def_clone def_clone, def_equals(*fields) def_equals, def_equals_and_hash(*fields) def_equals_and_hash, def_hash(*fields) def_hash, delegate(*methods, to object) delegate, forward_missing_to(delegate) forward_missing_to, getter(*names, &block) getter, getter!(*names) getter!, getter?(*names, &block) getter?, property(*names, &block) property, property!(*names) property!, property?(*names, &block) property?, setter(*names) setter

##
Constructor Detail

def self.new(initial_capacity = 8) #

Creates a new empty string pool.

The initial_capacity is useful to avoid unnecessary reallocations of the internal buffers in case of growth. If you have an estimate of the maximum number of elements the pool will hold it should be initialized with that capacity for improved performance. Inputs lower than 8 are ignored.

    pool = StringPool.new(256)
    pool.size # => 0

##
Instance Method Detail

def empty? : Bool #

Returns `true` if the `StringPool` has no element otherwise returns `false`.

    require "string_pool"

    pool = StringPool.new
    pool.empty? # => true
    pool.get("crystal")
    pool.empty? # => false

def get(str : Pointer(UInt8), len) : String #

Returns a `String` with the contents given by the pointer str of size len.

If a string with those contents was already present in the pool, that one is returned. Otherwise a new string is created, put in the pool and returned.

    require "string_pool"

    pool = StringPool.new
    pool.get("hey".to_unsafe, 3)
    pool.size # => 1

def get(slice : Bytes) : String #

Returns a `String` with the contents of the given slice.

If a string with those contents was already present in the pool, that one is returned. Otherwise a new string is created, put in the pool and returned.

    require "string_pool"

    pool = StringPool.new
    ptr = Pointer.malloc(9) { |i| ('a'.ord + i).to_u8 }
    slice = Slice.new(ptr, 3)
    pool.empty? # => true
    pool.get(slice)
    pool.empty? # => false

def get(str : IO::Memory) : String #

Returns a `String` with the contents of the given `IO::Memory`.

If a string with those contents was already present in the pool, that one is returned. Otherwise a new string is created, put in the pool and returned.

    require "string_pool"

    pool = StringPool.new
    io = IO::Memory.new "crystal"
    pool.empty? # => true
    pool.get(io)
    pool.empty? # => false

def get(str : String) : String #

Returns a `String` with the contents of the given string.

If a string with those contents was already present in the pool, that one is returned. Otherwise a new string is created, put in the pool and returned.

    require "string_pool"

    pool = StringPool.new
    string = "crystal"
    pool.empty? # => true
    pool.get(string)
    pool.empty? # => false

def get?(str : Pointer(UInt8), len) : String | Nil #

Returns a `String` with the contents given by the pointer str of size len, or `nil` if no such string exists in the pool.

    require "string_pool"

    pool = StringPool.new
    pool.get?("hey".to_unsafe, 3) # => nil
    pool.empty?                   # => true
    pool.get("hey".to_unsafe, 3)  # => "hey"
    pool.empty?                   # => false
    pool.get?("hey".to_unsafe, 3) # => "hey"

def get?(slice : Bytes) : String | Nil #

Returns a `String` with the contents of the given slice, or `nil` if no such string exists in the pool.

    require "string_pool"

    pool = StringPool.new
    bytes = "abc".to_slice
    pool.get?(bytes) # => nil
    pool.empty?      # => true
    pool.get(bytes)  # => "abc"
    pool.empty?      # => false
    pool.get?(bytes) # => "abc"

def get?(str : IO::Memory) : String | Nil #

Returns a `String` with the contents of the given `IO::Memory`, or `nil` if no such string exists in the pool.

    require "string_pool"

    pool = StringPool.new
    io = IO::Memory.new "crystal"
    pool.get?(io) # => nil
    pool.empty?   # => true
    pool.get(io)  # => "crystal"
    pool.empty?   # => false
    pool.get?(io) # => "crystal"

def get?(str : String) : String | Nil #

Returns a `String` with the contents of the given string, or `nil` if no such string exists in the pool.

    require "string_pool"

    pool = StringPool.new
    string = "crystal"
    pool.get?(string) # => nil
    pool.empty?       # => true
    pool.get(string)  # => "crystal"
    pool.empty?       # => false
    pool.get?(string) # => "crystal"

def rehash : Nil #

Rebuilds the hash based on the current hash values for each key, if values of key objects have changed since they were inserted.

Call this method if you modified a string submitted to the pool.

def size : Int32 #

Returns the size

    require "string_pool"

    pool = StringPool.new
    pool.size # => 0