struct Pf::StringSeln

Overview

A string selection type whose indivisible unit is the character (Char).

See also: GraphemeSeln.

StringSeln is most useful for lexical analysis/parsing and similar. Do not use it as a general-purpose replacement for strings: string selections do not play well with the GC since they keep the whole string in memory even if all you have at that point is its tiny (or even empty) fragment.

Defined in:

permafrost/string_seln.cr:1
permafrost/string_seln.cr:141

Constructors

Class Method Summary

Instance Method Summary

Constructor Detail

def self.between(a : StringSeln, b : StringSeln) : StringSeln #

[View source]
def self.chain(a : StringSeln, b : StringSeln) : StringSeln #

Joins two contiguous selections a, b. a must end exactly where b begins.


[View source]
def self.extend(a : StringSeln, b : StringSeln) : StringSeln #

[View source]
def self.new(string : String) : StringSeln #

Constructs a string selection from the given string.

This forces an encoding check on string. This method requires string to be a valid UTF-8 string.

If you want to scrub, use .new_scrub instead to skip the check.


[View source]
def self.new_scrub(string : String, replacement : Char = Char::REPLACEMENT) : StringSeln #

Constructs a string selection from the given string, replacing invalid bytes (according to UTF-8) with replacement.

See also: String#scrub.

Prefer this method over .new(string.scrub) to avoid the overhead of validating the encoding.


[View source]
def self.span(a : StringSeln, b : StringSeln) : StringSeln #

[View source]

Class Method Detail

def self.contiguous?(a : StringSeln, b : StringSeln) : Bool #

[View source]
def self.new?(string : String) : StringSeln | Nil #

[View source]
def self.siblings?(seln ref : StringSeln, *selns : StringSeln) : Bool #

Returns true if seln, selns are all of common descent, pointing to the same trunk.


[View source]
def self.unsafe_gte?(bytes : Bytes, size : Int32) : Bool #

[View source]

Instance Method Detail

def &+(other : StringSeln) : StringSeln #

[View source]
def <=>(other : StringSeln) : Int32 #

[View source]
def ==(other : StringSeln) : Bool #

[View source]
def ==(other : String) : Bool #

[View source]
def ==(other : Char) : Bool #

[View source]
def after_end : StringSeln #

Returns an empty selection pointing after the end of this one. Imagine this this as placing an "I-beam" after the last character in this selection (if any).


[View source]
def all_after_end : StringSeln #

Selects all characters in the trunk string after the end of this selection.


[View source]
def all_before_begin : StringSeln #

Selects all characters in the trunk string before the start of this selection.


[View source]
def before_begin : StringSeln #

Returns an empty selection pointing before the beginning of this one. Imagine this as placing an "I-beam" before the first character in this selection (if any).


[View source]
def blank? : Bool #

Returns true if this selection is empty or contains exclusively whitespace (see Char#whitespace?).


[View source]
def byte_end : UInt32 #

Returns the ending byte of this selection (exclusive).


[View source]
def byte_range : Range(UInt32, UInt32) #

[View source]
def byte_start : UInt32 #

Returns the starting byte of this selection (inclusive).


[View source]
def bytesize : UInt32 #

Returns the number of selected bytes.


[View source]
def char_end : UInt32 #

Returns the index of the last selected character.


[View source]
def char_start : UInt32 #

Returns the index of the first selected character.


[View source]
def chomp : StringSeln #

[View source]
def chop?(l, r) : StringSeln | Nil #

[View source]
def clone : StringSeln #

[View source]
def count(pattern : Char) : Int32 #

A hand-optimized alternative to ee.count. This is about a hundred times faster than ee.count on my machine for basic tasks such as counting newlines, due to vectorization-friendliness in the single-byte fast path.


[View source]
def covers_fully? : Bool #

[View source]
def each_before_and_after(& : StringSeln, StringSeln -> ) : Nil #

[View source]
def each_char(& : Char -> ) : Nil #

Yields selected characters.


[View source]
def each_char_seln(& : StringSeln -> ) : Nil #

[View source]
def each_char_with_abs_byte_index(& : Char, Int32 -> ) : Nil #

Yields selected characters along with their absolute byte index.


[View source]
def each_char_with_index(& : Char, Int32 -> ) : Nil #

[View source]
def each_line(& : StringSeln -> ) #

[View source]
def each_line_with_index(& : StringSeln, Int32 -> ) #

[View source]
def each_partition(& : StringSeln, StringSeln, StringSeln -> ) : Nil #

[View source]
def each_split(& : StringSeln, StringSeln, StringSeln -> ) : Nil #

[View source]
def each_word(& : StringSeln -> ) : Nil #

Yields each word in this selection.

This method never consumes any characters. All trailing and leading whitespaces are kept (if any) -- attached either to the left- or the right-hand side word.


[View source]
def each_word_with_index(& : StringSeln, Int32 -> ) : Nil #

Yields each word in this selection along with its index.

See also: #each_word.


[View source]
def ee : Enumerable(Char) #

[View source]
def empty? : Bool #

Returns true if this selection contains zero characters.


[View source]
def ends_with?(suffix : Char) : Bool #

[View source]
def ends_with?(suffix : String) : Bool #

[View source]
def expand : StringSeln #

Expands this selection to enclose the entire trunk string.


[View source]
def extend(*, exclusive = true, & : Char -> Bool) : StringSeln #

[View source]
def find(pattern) : StringSeln #

[View source]
def first : StringSeln #

Selects the first character if there are one or more characters. If there are zero characters, the returned selection is empty.


[View source]
def first_and_rest : Tuple(StringSeln, StringSeln) #

Splits this selection into two: the first selection contains the first character, and the second one contains the rest of characters. If this selection is empty, returns two empty selections.


[View source]
def first_char : Char #

Returns the first character in this selection. Raises IndexError if this selection is empty.


[View source]
def first_char? : Char | Nil #

Returns the first character in this selection. Returns nil if this selection is empty.


[View source]
def hash(hasher) #
Description copied from struct Struct

See Object#hash(hasher)


[View source]
def highlight(io, marker : String = "⏏") #

[View source]
def includes?(object : Char) : Bool #

[View source]
def inspect(io) #

[View source]
def last : StringSeln #

Selects the last character if there is one or more characters. If there are zero characters, the returned selection is empty.


[View source]
def last_char : Char #

Returns the last character in this selection. Raises IndexError if this selection is empty.


[View source]
def last_char? : Char | Nil #

Returns the last character in this selection. Returns nil if this selection is empty.


[View source]
def lchop(chr : Char) : StringSeln #

Skips one leading character chr from this selection, if present.


[View source]
def lchop : StringSeln #

Returns a selection that excludes the first selected character.


[View source]
def lchop?(pattern : Char) : StringSeln | Nil #

Skips one leading character chr from this selection, if present. Returns nil if chr is absent.


[View source]
def lchop?(pattern : String) : StringSeln | Nil #

[View source]
def lskip(nchars : Int) : StringSeln #

Skips a number of characters from the left.


[View source]
def lstrip(charset : String = "\n") : StringSeln #

[View source]
def ltake?(pattern) : StringSeln | Nil #

[View source]
def nonempty? : Bool #

Returns true if this selection contains one or more characters.


[View source]
def partition(& : Char -> Bool) : Tuple(StringSeln, StringSeln, StringSeln) #

[View source]
def partition(pattern : Char) : Tuple(StringSeln, StringSeln, StringSeln) #

[View source]
def partition(index needle : Int) : Tuple(StringSeln, StringSeln, StringSeln) #

[View source]
def postfixed_by?(r : Char | String) : Bool #

[View source]
def prefixed_by?(l : Char | String) : Bool #

[View source]
def prior : StringSeln #

Selects characters before the last character in this selection. If there are zero characters, the returned selection is empty.


[View source]
def prior_and_last : Tuple(StringSeln, StringSeln) #

Splits this selection into two: the first selection contains characters before the last character, and the second selection contains the last character.


[View source]
def rchop(chr : Char) : StringSeln #

Skips one trailing character chr from this selection, if present.


[View source]
def rchop : StringSeln #

Returns a selection that excludes the last selected character.


[View source]
def rchop?(chr : Char) : StringSeln | Nil #

[View source]
def rchop?(pattern : String) : StringSeln | Nil #

[View source]
def rest : StringSeln #

Selects characters after the first character in this selection. If there are zero characters, the returned selection is empty.


[View source]
def reverse_each_before_and_after(& : StringSeln, StringSeln -> ) : Nil #

[View source]
def reverse_each_char(& : Char -> ) : Nil #

Yields selected characters in reverse.


[View source]
def reverse_each_char_seln(& : StringSeln -> ) : Nil #

[View source]
def reverse_each_partition(& : StringSeln, StringSeln, StringSeln -> ) : Nil #

[View source]
def reverse_each_split(& : StringSeln, StringSeln, StringSeln -> ) : Nil #

[View source]
def reverse_extend(*, exclusive = true, & : Char -> Bool) : StringSeln #

[View source]
def rpartition(& : Char -> Bool) : Tuple(StringSeln, StringSeln, StringSeln) #

[View source]
def rpartition(pattern : Char) : Tuple(StringSeln, StringSeln, StringSeln) #

[View source]
def rskip_thru(charset : String) : Tuple(StringSeln, StringSeln) #

[View source]
def rskip_to(charset : String) : Tuple(StringSeln, StringSeln) #

[View source]
def rstrip(charset : String = "\n") : StringSeln #

[View source]
def size : Int32 #

Returns the number of selected characters.

NOTE Unlike String, this method does not cache the size -- since StringSeln is located entirely on the stack (minus the trunk string), there's nowhere for the size to go.

However, I tried to optimize this method well. In fact, due to the invariants of StringSeln, it runs about 10x faster than uncached String#size on my machine (the example I used was a 20MiB string; the results were: Crystal ~11ms, StringSeln ~1.25ms).

The design is that you aren't expected to call this method very often. If you do end up doing that, we try really hard to remain fast, but ultimately, this is still worst-case O(N).


[View source]
def skip_thru(charset : String) : Tuple(StringSeln, StringSeln) #

[View source]
def skip_thru_seq(*, limit : UInt32 = UInt32::MAX, & : Char -> T | Nil) : Tuple(StringSeln, Array(T), StringSeln) forall T #

[View source]
def skip_to(charset : String) : Tuple(StringSeln, StringSeln) #

[View source]
def span(other : StringSeln) : StringSeln #

[View source]
def split(sep : Char, **kwargs) : Array(StringSeln) #

[View source]
def split(sep : Char, **kwargs, &) : Nil #

[View source]
def split_and_rest(sep : Char, *, allow_empty : Bool = true, & : StringSeln, StringSeln -> ) : Nil #

[View source]
def starts_with?(prefix : Char) : Bool #

[View source]
def starts_with?(prefix : String) : Bool #

[View source]
def strip(charset : String = "\n") : StringSeln #

[View source]
def surrounded_by?(l : Char | String, r : Char | String) : Bool #

[View source]
def to_s(io) #

[View source]
def to_s : String #
Description copied from class Object

Returns a nicely readable and concise string representation of this object, typically intended for users.

This method should usually not be overridden. It delegates to #to_s(IO) which can be overridden for custom implementations.

Also see #inspect.


[View source]
def to_slice : Bytes #

Returns the underlying bytes. The returned slice is read-only. It is guaranteed to contain valid UTF-8 encoded bytes. It is guaranteed to start and end at a UTF-8 character boundary.


[View source]
def upto(other : StringSeln) : StringSeln #

[View source]