=encoding utf8

=head1 NAME

Sidef::Types::String::String

=head1 DESCRIPTION

This class implements strings in Sidef. Strings are sequences of Unicode characters that can be manipulated in various ways, including concatenation, pattern matching, transformation, and encoding operations.

Sidef strings are Unicode-aware and support a rich set of operations including regular expression matching, case conversion, splitting, joining, and various encoding/decoding operations.

=head1 SYNOPSIS

    var str = String("hello")
    var str = "hello"                  # String literal

    # String operations
    say str.uc                          #=> "HELLO"
    say str * 3                         #=> "hellohellohello"
    say str + " world"                  #=> "hello world"
    say str.chars                       #=> ["h", "e", "l", "l", "o"]

    # Pattern matching
    str =~ /l+/ && say "Match found!"
    str.gsub(/l/, 'L')                  #=> "heLLo"

    # Encoding operations
    say str.encode_utf8.bytes_len       # Length in bytes

=head1 INHERITS

Inherits methods from:

       * Sidef::Object::Object

=head1 METHODS

=head2 %

    format_str % (args...)

Returns a string that is formatted according to a specified format string and arguments.

Parameters:

    format_str  : A string that specifies the format of the output string. It can contain placeholders that are replaced by the values of the arguments passed to the function.
    args...     : Any number of arguments that are used to replace the placeholders in the format string. The number of arguments must match the number of placeholders in the format string.

Example:

    say "Hello, %s! You have %d messages." % ("Alice", 5)
    #=> "Hello, Alice! You have 5 messages."

Aliases: I<sprintf>

=cut

=head2 &

    str1 & str2

Performs a bitwise B<AND> operation on two strings and returns the result as a new string. Each byte in the result is the bitwise AND of the corresponding bytes in the input strings.

Example:

    say ("abc" & "def")    # Bitwise AND of corresponding bytes

Aliases: I<and>

=cut

=head2 *

    str * n

Takes a string C<str> and a non-negative integer C<n> as input and returns a new string consisting of C<n> copies of C<str> concatenated together.

Example:

    say "ha" * 3           #=> "hahaha"
    say "x" * 0            #=> ""

Aliases: I<mul>, I<repeat>

=cut

=head2 +

    str1 + str2

Concatenates two strings into a single string.

Example:

    say "hello" + " " + "world"    #=> "hello world"

Aliases: I<add>, I<append>, I<concat>

=cut

=head2 ++

    a++

Increments an alphanumeric string to the next ASCIIbetical string. This is useful for generating sequences of strings.

Example:

    var s = "aa"
    say s++              #=> "aa"
    say s                #=> "ab"
    say "z"++            #=> "z" (returns current, then increments to "aa")

Aliases: I<inc>

=cut

=head2 -

    str - substr
    str - regex

Remove from C<str> the first occurrence of C<substr>:

    'foo boo' - 'o'    #=> 'fo boo'

When a regular expression is given, it removes all occurrences matched by the regex:

    'foo boo' - /o/     #=> 'f b'

Aliases: I<diff>

=cut

=head2 ..

    a .. b

Returns a RangeStr object: C<RangeStr(a, b)>. This creates a range that can iterate through strings.

Example:

    say ('a'..'e').to_a    #=> ["a", "b", "c", "d", "e"]
    say ('aa'..'ac').to_a  #=> ["aa", "ab", "ac"]

Aliases: I<to>, I<upto>

=cut

=head2 /

    str / n

Divide the C<str> into at least C<n> parts, returning an Array object. If the string doesn't divide evenly, the last parts will be shorter.

Example:

    'foobar' / 2   #=> ["foo", "bar"]
    'fooba' / 2    #=> ["fo", "ob", "a"]
    'abcde' / 3    #=> ["ab", "cd", "e"]

Aliases: I<÷>, I<div>

=cut

=head2 <

    str1 < str2

Returns true if C<str1> is lexicographically less than C<str2>.

Example:

    say ("abc" < "abd")    #=> true
    say ("z" < "a")        #=> false

Aliases: I<lt>

=cut

=head2 <<

    str << n

Returns a new string that is formed by dropping the first n characters from the input string.

Example:

    say ("hello" << 2)     #=> "llo"
    say ("test" << 5)      #=> ""

Aliases: I<drop_left>, I<shift_left>

=cut

=head2 <=>

    str1 <=> str2

Compares two strings lexicographically and returns an integer that represents their relative order.

If C<str1> is lexicographically less than C<str2>, the function returns a negative integer.

If C<str1> is lexicographically greater than C<str2>, the function returns a positive integer.

If the two strings are equal, the function returns C<0>.

Example:

    say ("abc" <=> "abd")  #=> -1
    say ("xyz" <=> "abc")  #=> 1
    say ("test" <=> "test") #=> 0

Aliases: I<cmp>

=cut

=head2 ==

    str1 == str2

Compares if the given two strings are equal to each other. If the two strings are equal, the function returns true.

Example:

    say ("hello" == "hello")    #=> true
    say ("hello" == "world")    #=> false

Aliases: I<eq>

=cut

=head2 =~

    str =~ regex
    str.match(regex, pos)

Searches for a match between a regular expression and a string, starting from a specified position in the string. It returns a match object if successful, or nil if no match is found.

Parameters:

    regex : A regular expression to be matched against the string.
    pos   : An integer that represents the position in the string where the search is to begin. The default value is 0, which means the search starts from the beginning of the string.

Example:

    var m = ("hello world" =~ /w\w+/)
    m && say m[0]                      #=> "world"

    "testing" =~ /(\w+)ing/ && say $1  #=> "test"

Aliases: I<match>

=cut

=head2 >

    str1 > str2

Returns true if C<str1> is lexicographically greater than C<str2>.

Example:

    say ("xyz" > "abc")    #=> true
    say ("aaa" > "zzz")    #=> false

Aliases: I<gt>

=cut

=head2 >>

    str >> n

Returns a new string that is formed by dropping the last n characters from the input string.

Example:

    say ("hello" >> 2)     #=> "hel"
    say ("test" >> 5)      #=> ""

Aliases: I<drop_right>, I<shift_right>

=cut

=head2 ^

    str1 ^ str2

Performs a bitwise B<XOR> operation on two strings and returns the result as a new string. Each byte in the result is the bitwise XOR of the corresponding bytes in the input strings.

Example:

    say ("abc" ^ "def")    # Bitwise XOR of corresponding bytes

Aliases: I<xor>

=cut

=head2 |

    str1 | str2

Performs a bitwise B<OR> operation on two strings and returns the result as a new string. Each byte in the result is the bitwise OR of the corresponding bytes in the input strings.

Example:

    say ("abc" | "def")    # Bitwise OR of corresponding bytes

Aliases: I<or>

=cut

=head2 ~

    ~str

Performs a bitwise unary B<NOT> operation on the given string and returns the result as a new string. Each byte in the result is the bitwise complement of the corresponding byte in the input string.

Example:

    say ~"abc"             # Bitwise NOT of each byte

Aliases: I<not>

=cut

=head2 ≠

    str1 ≠ str2

Compares if the given two strings are not equal to each other. If the two strings are different, the function returns true.

Example:

    say ("hello" ≠ "world")    #=> true
    say ("test" ≠ "test")      #=> false

Aliases: I<!=>, I<ne>

=cut

=head2 ≤

    str1 ≤ str2

Returns true if C<str1> is lexicographically less than or equal to C<str2>.

Example:

    say ("abc" ≤ "abc")    #=> true
    say ("abc" ≤ "abd")    #=> true

Aliases: I<E<lt>=>, I<le>

=cut

=head2 ≥

    str1 ≥ str2

Returns true if C<str1> is lexicographically greater than or equal to C<str2>.

Example:

    say ("xyz" ≥ "abc")    #=> true
    say ("abc" ≥ "abc")    #=> true

Aliases: I<E<gt>=>, I<ge>

=cut

=head2 apply_escapes

    str.apply_escapes

Interprets escape sequences in the string and returns a new string with the escapes applied. This processes backslash escape sequences like \n, \t, \r, etc.

Example:

    say "hello\\nworld".apply_escapes    #=> "hello\nworld" (with actual newline)

=cut

=head2 ascii2bin

    str.ascii2bin

Takes a string of ASCII characters as input and returns a string of binary digits representing the ASCII values of the characters. Each character is converted to its binary representation.

Example:

    say "Hi".ascii2bin    #=> "0100100001101001"

=cut

=head2 ascii2bits

    str.ascii2bits

Takes a string of ASCII characters as input and returns a string of bits representing the ASCII values of the characters. Each character is converted to its 8-bit binary representation.

Example:

    say "A".ascii2bits    #=> "01000001"

=cut

=head2 backtick

    str.backtick

Executes the string as a shell command and returns the output. This is equivalent to running the string in backticks or using qx{}.

Example:

    say "echo hello".backtick    #=> "hello\n"

Warning: Use with caution as it executes arbitrary shell commands.

=cut

=head2 base64_decode

    str.base64_decode

Decodes a base64 encoded string into its original form.

Base64 is a binary-to-text encoding scheme that represents binary data in an ASCII string format by translating it into a radix-64 representation. The encoded string can be safely transferred or stored without any data loss or corruption. The C<base64_decode()> method reverses the encoding process and converts the base64 string back to its original binary form.

Example:

    say "SGVsbG8gV29ybGQ=".base64_decode    #=> "Hello World"

Aliases: I<decode_base64>

=cut

=head2 base64_encode

    str.base64_encode

Encodes a string in base64 format. Base64 is a binary-to-text encoding scheme that represents binary data in an ASCII string format by translating it into a radix-64 representation. The encoded string can be safely transferred or stored without any data loss or corruption. The C<base64_encode()> method encodes the input string in base64 format.

Example:

    say "Hello World".base64_encode    #=> "SGVsbG8gV29ybGQ="

Aliases: I<encode_base64>

=cut

=head2 begins_with

    str.begins_with(prefix)

Check whether a string starts with a given prefix string or not. It takes a string as an input and checks whether the string starts with the prefix string specified as an argument. If the string starts with the specified prefix, it returns True, otherwise, it returns False.

Example:

    say "hello".begins_with("he")     #=> true
    say "hello".begins_with("lo")     #=> false

Aliases: I<starts_with>

=cut

=head2 bin

    str.bin

Converts a binary string (consisting of 0s and 1s) to a Number object. The string is interpreted as a base-2 number.

Example:

    say "1010".bin         #=> 10
    say "11111111".bin     #=> 255

=cut

=head2 bin2ascii

    str.bin2ascii

Converts a binary string into its equivalent ASCII string representation. It takes a binary string as an input and returns the equivalent ASCII string representation of the binary string.

Example:

    say "0100100001101001".bin2ascii    #=> "Hi"

=cut

=head2 byte

    str.byte(pos)

Returns the byte value at the specified position in the string. Position indexing starts at 0.

Example:

    say "hello".byte(0)    #=> 104 (ASCII value of 'h')
    say "hello".byte(1)    #=> 101 (ASCII value of 'e')

Aliases: I<byte_at>

=cut

=head2 bytes

    str.bytes

Convert a string into an Array of bytes, ranging from C<0> to C<255>. Each byte represents the numeric value of the corresponding byte in the string's encoding.

Example:

    say "Hi".bytes         #=> [72, 105]
    say "€".encode_utf8.bytes    #=> [226, 130, 172]

=cut

=head2 bytes_len

    str.bytes_len

Determine the length of a string in bytes. It takes a string as an input and returns the length of the string in bytes. For multi-byte characters, this may differ from the character count.

Example:

    say "hello".bytes_len    #=> 5
    say "€".encode_utf8.bytes_len    #=> 3

Aliases: I<bytes_length>

=head2 bwt_encode

    str.bwt_encode

Applies the Burrows–Wheeler transform (BWT) to the invocant string and returns a pair consisting of the transformed string and the primary index.

The primary index is required for decoding with C<bwt_decode>.

    var (bwt, idx) = "banana".bwt_encode

=cut

=head2 bwt_decode

    bwt.bwt_decode(idx)

Reverses the Burrows–Wheeler transform and reconstructs the original string.

This method takes a BWT-transformed string and its associated primary index (as returned by C<bwt_encode>) and reconstructs the original string using the standard LF-mapping technique.

    var original = bwt.bwt_decode(idx)

=cut

=head2 center

    str.center(width, padstr=" ")

Centers the string within a field of the given width, padding with the specified padding string (default is space). If the string is already longer than the width, it is returned unchanged.

Example:

    say "hi".center(10)         #=> "    hi    "
    say "test".center(10, "-")  #=> "---test---"

=cut

=head2 char

    str.char(pos)

Returns the character at the specified position in the string. Position indexing starts at 0. Returns nil if the position is out of bounds.

Example:

    say "hello".char(0)    #=> "h"
    say "hello".char(4)    #=> "o"

Aliases: I<char_at>

=cut

=head2 chars

    str.chars

Convert a string into an Array of characters.

Example:

    say "foo".chars     #=> ["f", "o", "o"]
    say "€".chars       #=> ["€"]

=cut

=head2 chomp

    str.chomp

Returns a copy of the string with the trailing newline (or record separator) removed. If there is no newline at the end, the string is returned unchanged.

Example:

    say "hello\n".chomp    #=> "hello"
    say "test".chomp       #=> "test"

=cut

=head2 chop

    str.chop

Returns a copy of the string with the last character removed. If the string is empty, returns an empty string.

Example:

    say "hello".chop    #=> "hell"
    say "a".chop        #=> ""

=cut

=head2 clear

    str.clear

Clears the content of the string, making it empty. Returns an empty string.

Example:

    var s = "hello"
    say s.clear         #=> ""

=cut

=head2 codes

    str.codes

Convert a string into an Array of Unicode code points. Each element is the numeric value of the corresponding character in Unicode.

Example:

    say "foo".codes   #=> [102, 111, 111]
    say "€".codes     #=> [8364]
    say "Hi".codes    #=> [72, 105]

Aliases: I<code_points>

=cut

=head2 collect

    str.collect(regex)

Collects all matches of the given regular expression in the string and returns them as an Array. This is similar to the global match operation.

Example:

    say "foo bar baz".collect(/b\w+/)    #=> ["bar", "baz"]
    say "123 456 789".collect(/\d+/)     #=> ["123", "456", "789"]

Aliases: I<find_all>, I<findall>

=cut

=head2 cons

    str.cons(n)

Returns an Array of all consecutive subsequences of length n from the string.

Example:

    say "abcde".cons(2)    #=> ["ab", "bc", "cd", "de"]
    say "test".cons(3)     #=> ["tes", "est"]

=cut

=head2 count

    str.count(substr)
    str.count(regex)

Returns the number of non-overlapping occurrences of the substring or pattern in the string.

Example:

    say "hello world".count("l")    #=> 3
    say "aaa".count("aa")           #=> 1 (non-overlapping)
    say "foo bar baz".count(/ba/)   #=> 2

=cut

=head2 crypt

    str.crypt(salt)

Encrypts the string using the crypt(3) function with the specified salt. This is typically used for password hashing. The salt determines the encryption algorithm used.

Example:

    say "password".crypt('$6$somesalt')    # SHA-512 based hash

=cut

=head2 decode

    str.decode(encoding)

Decodes a string using a specified character encoding and returns the corresponding Unicode string.

Parameters:

    encoding : A string that specifies the character encoding used to encode the input string (e.g., "utf8", "utf16", "latin1", etc.).

Example:

    var bytes = "café".encode("utf8")
    say bytes.decode("utf8")    #=> "café"

=cut

=head2 decode_utf8

    str.decode_utf8

Decodes a UTF-8 encoded string and returns the corresponding Unicode string. This is equivalent to decode("utf8").

Example:

    var utf8_bytes = "\xc3\xa9"    # UTF-8 bytes for "é"
    say utf8_bytes.decode_utf8     #=> "é"

=cut

=head2 deflate

    str.deflate

Compresses the string using the DEFLATE compression algorithm and returns the compressed data.

Example:

    var compressed = "hello world".deflate
    say compressed.len < "hello world".len    #=> true (usually)

=cut

=head2 die

    str.die

Prints the string to STDERR and terminates the program with a non-zero exit code.

Example:

    "Error: file not found".die    # Prints error and exits

=cut

=head2 digits

    str.digits

Returns an Array of the digit characters found in the string.

Example:

    say "abc123def456".digits    #=> ["1", "2", "3", "4", "5", "6"]
    say "no digits here".digits  #=> []

=cut

=head2 downto

    from.downto(to) { |str| ... }
    from.downto(to, step) { |str| ... }

Iterates from the string C<from> down to the string C<to>, executing the given block for each string in the sequence. The optional C<step> parameter controls the decrement.

Example:

    "c".downto("a", { |s| say s })    # Prints: c, b, a

=cut

=head2 dump

    str.dump

Returns a string representation of the string that shows its internal structure, with special characters escaped. Useful for debugging.

Example:

    say "hello\nworld".dump    #=> "hello\\nworld"
    say "test".dump            #=> "test"

Aliases: I<inspect>

=cut

=head2 each

    str.each { |char| ... }

Iterates through each character in the string and applies a given block of code to each character.

Example:

    "hello".each { |c| say c }    # Prints each character on a new line

Aliases: I<each_char>

=cut

=head2 each_byte

    str.each_byte { |byte| ... }

Iterates through each byte value in the string and applies a given block of code to each byte value.

Example:

    "Hi".each_byte { |b| say b }    # Prints: 72, 105

=cut

=head2 each_cons

    str.each_cons(n) { |substr| ... }

Iterates through each consecutive substring of length n and applies the given block to each one.

Example:

    "abcde".each_cons(2, { |s| say s })    # Prints: ab, bc, cd, de

=cut

=head2 each_graph

    str.each_graph { |grapheme| ... }

Iterates through each grapheme cluster in the string and applies a given block of code to each grapheme. A grapheme cluster represents a single user-perceived character.

Example:

    "hello".each_graph { |g| say g }    # Prints each grapheme

Aliases: I<each_grapheme>

=cut

=head2 each_kv

    str.each_kv { |index, char| ... }

Iterates through each character in the string along with its index, passing both the index and character to the given block.

Example:

    "abc".each_kv { |i, c| say "#{i}: #{c}" }    # Prints: 0: a, 1: b, 2: c

=cut

=head2 each_line

    str.each_line { |line| ... }

Iterates through each line in the string and applies a given block of code to each line. Lines are separated by newline characters.

Example:

    "line1\nline2\nline3".each_line { |line| say line }

=cut

=head2 each_num

    str.each_num { |num| ... }

Iterates through each word in the string, converts it to a number, and applies a given block of code to each number. Non-numeric words are skipped.

Example:

    "10 20 30".each_num { |n| say n * 2 }    # Prints: 20, 40, 60

Aliases: I<each_number>

=cut

=head2 each_slice

    str.each_slice(n) { |slice| ... }

Divides the string into slices of length n and applies the given block to each slice.

Example:

    "abcdef".each_slice(2, { |s| say s })    # Prints: ab, cd, ef

=cut

=head2 each_word

    str.each_word { |word| ... }

Iterates through each word in the string and applies a given block of code to each word. Words are separated by whitespace.

Example:

    "hello world test".each_word { |w| say w }    # Prints: hello, world, test

=cut

=head2 encode

    str.encode(encoding)

Encodes a string into a specified character encoding and returns a new string object.

Parameters:

    encoding : A string that specifies the character encoding to be used for encoding the input string (e.g., "utf8", "utf16", "latin1", etc.).

Example:

    say "café".encode("utf8").bytes    # Shows UTF-8 byte representation

=cut

=head2 encode_utf8

    str.encode_utf8

Encodes a Unicode string using the UTF-8 character encoding and returns a new string object.

Example:

    say "€".encode_utf8.bytes    #=> [226, 130, 172]

=cut

=head2 ends_with

    str.ends_with(suffix)

Checks if a string ends with a specified suffix and returns a boolean value.

Parameters:

    suffix : A string that represents the suffix to be searched for at the end of the input string.

Example:

    say "hello".ends_with("lo")    #=> true
    say "hello".ends_with("he")    #=> false

=cut

=head2 escape

    str.escape

Returns a copy of the input string with all non-word characters escaped using a backslash character. This is useful for preparing strings to be used in regular expressions.

Example:

    say "hello.world".escape    #=> "hello\\.world"
    say "(test)".escape         #=> "\\(test\\)"

Aliases: I<quotemeta>

=cut

=head2 esub

    str.esub(regex) { |match| ... }

Performs a substitution on the first match of the regular expression, evaluating the block for the match and replacing it with the block's return value.

Example:

    say "hello world".esub(/\w+/, { |m| m.uc })    #=> "HELLO world"

=cut

=head2 extract_bracketed

    str.extract_bracketed(brackets)

Extracts a bracketed substring from the string. The brackets parameter specifies which types of brackets to match (e.g., "(){}[]").

Example:

    say "text (inside) more".extract_bracketed("()")    #=> "(inside)"

=cut

=head2 extract_codeblock

    str.extract_codeblock(delim)

Extracts a code block from the string, using the specified delimiter to identify the block boundaries.

Example:

    say "code { block } end".extract_codeblock("{}")    #=> "{ block }"

=cut

=head2 extract_delimited

    str.extract_delimited(delim)

Extracts a delimited substring from the string using the specified delimiter.

Example:

    say 'text "quoted" more'.extract_delimited('"')    #=> '"quoted"'

=cut

=head2 extract_quotelike

    str.extract_quotelike

Extracts a quote-like expression from the string. This recognizes Perl-style quote operators.

Example:

    say "q{text} more".extract_quotelike    #=> "q{text}"

=cut

=head2 extract_tagged

    str.extract_tagged

Extracts a tagged region from the string, typically used for XML or HTML-style tags.

Example:

    say "<tag>content</tag>".extract_tagged    #=> "<tag>content</tag>"

=cut

=head2 fc

    str.fc

Returns a copy of the input string with all uppercase characters converted to their lowercase equivalents using casefolding.

Casefolding is the process of mapping strings to a form where case differences are erased; comparing two strings in their casefolded form is effectively a way of asking if two strings are equal, regardless of case.

Example:

    say "HELLO".fc == "hello".fc    #=> true
    say "Straße".fc                  #=> "strasse" (German ß folds to ss)

Aliases: I<foldcase>

=cut

=head2 first

    str.first(n)

Returns the first C<n> characters of the input string, where C<n> is an integer.

Parameters:

    n : An integer that represents the number of characters to be returned from the beginning of the input string.

Example:

    say "hello world".first(5)    #=> "hello"
    say "test".first(2)           #=> "te"

=cut

=head2 flip

    str.flip

Returns a copy of the input string with the order of its characters reversed.

Example:

    say "hello".flip    #=> "olleh"
    say "12345".flip    #=> "54321"

Aliases: I<reverse>

=cut

=head2 format

    format_str.format(args...)

Formats the string using the provided arguments. This is similar to sprintf-style formatting.

Example:

    say "%s has %d apples".format("Alice", 5)    #=> "Alice has 5 apples"

=cut

=head2 frequire

    str.frequire

Loads and executes a Sidef source file specified by the string. The 'f' stands for "file require". Returns true if successful.

Example:

    "mylib.sf".frequire    # Loads mylib.sf

=cut

=head2 gesub

    str.gesub(regex) { |match| ... }

Performs global substitution on all matches of the regular expression, evaluating the block for each match and replacing it with the block's return value.

Example:

    say "hello world".gesub(/\w+/, { |m| m.uc })    #=> "HELLO WORLD"

=cut

=head2 glob

    str.glob

Expands the string as a filename pattern and returns an Array of matching filenames. Uses shell-style wildcards.

Example:

    say "*.txt".glob    # Returns array of all .txt files in current directory

=cut

=head2 gmatch

    str.gmatch(regex, pos=0)

Performs a global match operation, finding all matches of the regular expression in the string starting from the specified position. Returns an Array of match objects.

Example:

    say "foo bar baz".gmatch(/\w+/)    #=> Returns array of all word matches

=cut

=head2 graphs

    str.graphs

Returns an Array of grapheme clusters in the input string. A grapheme cluster is a sequence of one or more Unicode code points that represents a single user-perceived character.

Example:

    say "hello".graphs    #=> ["h", "e", "l", "l", "o"]
    say "é".graphs        #=> ["é"] (even if composed of multiple code points)

Aliases: I<graphemes>

=cut

=head2 graphs_len

    str.graphs_len

Returns the number of grapheme clusters in the input string. This represents the number of user-perceived characters.

Example:

    say "hello".graphs_len    #=> 5
    say "café".graphs_len     #=> 4

Aliases: I<graphs_length>

=cut

=head2 gsub

    str.gsub(regex, replacement)

Performs global substitution, replacing all matches of the regular expression with the replacement string.

Example:

    say "hello world".gsub(/l/, "L")    #=> "heLLo worLd"
    say "foo bar".gsub(/o/, "0")        #=> "f00 bar"

Aliases: I<replace_all>

=cut

=head2 gunzip

    str.gunzip

Decompresses a gzip-compressed string and returns the original data.

Example:

    var original = "hello world"
    var compressed = original.gzip
    say compressed.gunzip    #=> "hello world"

=cut

=head2 gzip

    str.gzip

Compresses the string using gzip compression and returns the compressed data.

Example:

    var compressed = "hello world hello world".gzip
    say (compressed.len < "hello world hello world".len)    #=> true

=cut

=head2 has

    str.has(substr, pos=0)
    str.has(regex, pos=0)

Checks if a substring exists within the input string starting from a given position.

Parameters:

    substr  : A string that represents the substring to search for.
    pos     : An integer that represents the starting position from where to search for the substring. The default value is 0.

When a regular expression is given, it checks if the regular expression pattern matches within the input string starting from a given position.

Example:

    say "hello world".has("world")      #=> true
    say "hello world".has("world", 10)  #=> false
    say "testing".has(/\d+/)            #=> false

Aliases: I<contain>, I<include>, I<contains>, I<includes>

=cut

=head2 hex

    str.hex

Converts a hexadecimal string to a Number object. The string is interpreted as a base-16 number. The "0x" or "0X" prefix is optional.

Example:

    say "FF".hex         #=> 255
    say "0x1A".hex       #=> 26
    say "10".hex         #=> 16

=cut

=head2 hex2ascii

    str.hex2ascii

Decodes a hexadecimal string and returns its equivalent byte-string. The hexadecimal string should contain pairs of hex digits representing bytes.

Example:

    say "48656c6c6f".hex2ascii    #=> "Hello"

Aliases: I<unhexlify>

=cut

=head2 hexlify

    str.hexlify

Encodes the input string as a hexadecimal string. Each byte is converted to its two-digit hexadecimal representation.

Example:

    say "Hello".hexlify    #=> "48656c6c6f"

Aliases: I<ascii2hex>

=cut

=head2 index

    str.index(substr, pos=0)

Returns the index of the first occurrence of a substring in a given string starting from a specified position. Returns -1 if the substring is not found.

Parameters:

    str        : The original string in which the substring is to be searched.
    substring  : The substring to be searched in the original string.
    pos        : The position in the original string from where the search is to begin. The default value is 0.

Example:

    say "hello world".index("world")     #=> 6
    say "hello world".index("o")         #=> 4
    say "hello world".index("o", 5)      #=> 7
    say "hello world".index("xyz")       #=> -1

=cut

=head2 inflate

    str.inflate

Decompresses a DEFLATE-compressed string and returns the original uncompressed data. This is the reverse operation of the C<deflate> method.

Example:

    var original = "hello world"
    var compressed = original.deflate
    say compressed.inflate    #=> "hello world"

=cut

=head2 insert

    str.insert(substring, pos, len=0)

Inserts a substring into a given string at a specified position, optionally replacing C<len> characters.

Parameters:

    str        : The original string into which the substring is to be inserted.
    substring  : The substring to be inserted into the original string.
    pos        : The position in the original string where the insertion is to begin.
    len        : The length of the portion to replace. If 0, performs simple insertion without replacement. Default is 0.

Example:

    say "hello world".insert("beautiful ", 6)       #=> "hello beautiful world"
    say "hello world".insert("X", 6, 5)             #=> "hello X"

=cut

=head2 ints

    str.ints

Returns an Array of integers extracted from the string. This method finds all integer values (positive and negative) in the string.

Example:

    say "test 123 and -456".ints    #=> [123, -456]
    say "no numbers".ints           #=> []

Aliases: I<integers>

=cut

=head2 is_alnum

    str.is_alnum

Returns true if all characters in the string are alphanumeric (letters or digits) and the string is not empty, false otherwise.

Example:

    say "abc123".is_alnum     #=> true
    say "abc 123".is_alnum    #=> false (contains space)
    say "test".is_alnum       #=> true

Aliases: I<is_alphanum>

=cut

=head2 is_alpha

    str.is_alpha

Returns true if all characters in the string are alphabetic letters and the string is not empty, false otherwise.

Example:

    say "hello".is_alpha      #=> true
    say "hello123".is_alpha   #=> false
    say "test".is_alpha       #=> true

=cut

=head2 is_ascii

    str.is_ascii

Returns true if all characters in the string are ASCII characters (code points 0-127), false otherwise.

Example:

    say "hello".is_ascii      #=> true
    say "café".is_ascii       #=> false (é is not ASCII)

=cut

=head2 is_blank

    str.is_blank

Returns true if the string contains only whitespace characters or is empty, false otherwise.

Example:

    say "   ".is_blank        #=> true
    say "".is_blank           #=> true
    say "  a  ".is_blank      #=> false

=cut

=head2 is_control

    str.is_control

Returns true if all characters in the string are control characters and the string is not empty, false otherwise.

Example:

    say "\n\t".is_control     #=> true
    say "test".is_control     #=> false

=cut

=head2 is_digit

    str.is_digit

Returns true if all characters in the string are digits and the string is not empty, false otherwise.

Example:

    say "12345".is_digit      #=> true
    say "123a".is_digit       #=> false
    say "".is_digit           #=> false

=cut

=head2 is_empty

    str.is_empty

Determine if a given string is empty or not. It takes a string as an input and returns True if the string is empty, False otherwise.

Example:

    say "".is_empty           #=> true
    say "hello".is_empty      #=> false
    say "   ".is_empty        #=> false

=cut

=head2 is_graph

    str.is_graph

Returns true if all characters in the string are graphical characters (visible characters, not whitespace) and the string is not empty, false otherwise.

Example:

    say "hello!".is_graph     #=> true
    say "hello ".is_graph     #=> false (contains space)

=cut

=head2 is_lc

    str.is_lc

Returns true if all alphabetic characters in the string are lowercase and there is at least one alphabetic character, false otherwise.

Example:

    say "hello".is_lc         #=> true
    say "Hello".is_lc         #=> false
    say "123".is_lc           #=> false

Aliases: I<is_lowercase>

=cut

=head2 is_numeric

    str.is_numeric

Checks whether a given string looks like a number or not. It checks if the string can be converted to a number without raising an exception.

Example:

    say "123".is_numeric       #=> true
    say "123.45".is_numeric    #=> true
    say "-42".is_numeric       #=> true
    say "abc".is_numeric       #=> false

Aliases: I<looks_like_number>

=cut

=head2 is_palindrome

    str.is_palindrome

Checks whether a given string is a palindrome or not. A palindrome is a word, phrase, number, or other sequence of characters that reads the same backward as forward.

Example:

    say "racecar".is_palindrome    #=> true
    say "hello".is_palindrome      #=> false
    say "noon".is_palindrome       #=> true

=cut

=head2 is_printable

    str.is_printable

Returns true if all characters in the string are printable and the string is not empty, false otherwise. Printable characters include letters, digits, punctuation, and spaces.

Example:

    say "hello world".is_printable    #=> true
    say "test\n".is_printable         #=> false (contains newline)

=cut

=head2 is_punct

    str.is_punct

Returns true if all characters in the string are punctuation characters and the string is not empty, false otherwise.

Example:

    say "!@#".is_punct         #=> true
    say "hello!".is_punct      #=> false

Aliases: I<is_punctuation>

=cut

=head2 is_space

    str.is_space

Returns true if all characters in the string are whitespace characters and the string is not empty, false otherwise.

Example:

    say "   ".is_space         #=> true
    say " \t\n".is_space       #=> true
    say " a ".is_space         #=> false

=cut

=head2 is_uc

    str.is_uc

Returns true if all alphabetic characters in the string are uppercase and there is at least one alphabetic character, false otherwise.

Example:

    say "HELLO".is_uc          #=> true
    say "Hello".is_uc          #=> false
    say "123".is_uc            #=> false

Aliases: I<is_uppercase>

=cut

=head2 is_word

    str.is_word

Returns true if all characters in the string are word characters (letters, digits, or underscores) and the string is not empty, false otherwise.

Example:

    say "hello_123".is_word    #=> true
    say "hello world".is_word  #=> false (contains space)

=cut

=head2 is_xdigit

    str.is_xdigit

Returns true if all characters in the string are hexadecimal digits (0-9, a-f, A-F) and the string is not empty, false otherwise.

Example:

    say "1A2B".is_xdigit       #=> true
    say "xyz".is_xdigit        #=> false

=cut

=head2 iter

    str.iter

Returns an iterator object that can be used to iterate through the characters of the string one at a time.

Example:

    var it = "hello".iter
    say it.next    #=> "h"
    say it.next    #=> "e"

=cut

=head2 jaro

    jaro(str1, str2, winkler=false)

Calculates the Jaro similarity between two strings. Jaro distance is a measure of similarity between two strings, based on the number of matching characters and transpositions. The result is a value between 0 and 1, where 1 indicates identical strings.

When the third argument is true, it returns the Jaro-Winkler similarity score, which gives more weight to strings that match from the beginning.

Example:

    say jaro("accommodate", "accomodate")         #=> 0.96969696969697
    say jaro("accommodate", "accomodate", true)   #=> 0.981818181818182

=cut

=head2 join

    delim.join(strings...)

Concatenates a list of strings and returns a single string, using the caller string as a delimiter between each pair of strings.

Example:

    say ", ".join("apple", "banana", "cherry")    #=> "apple, banana, cherry"
    say "-".join("a", "b", "c")                   #=> "a-b-c"

=cut

=head2 last

    str.last(n)

Returns the last n characters of a string.

Example:

    say "hello world".last(5)    #=> "world"
    say "test".last(2)           #=> "st"

=cut

=head2 lc

    str.lc

Returns a new string with all alphabetic characters converted to lowercase.

Example:

    say "HELLO World".lc    #=> "hello world"

Aliases: I<lower>, I<downcase>, I<lowercase>

=cut

=head2 lcfirst

    str.lcfirst

Returns a new string with the first character of the string converted to lowercase.

Example:

    say "Hello World".lcfirst    #=> "hello World"

=cut

=head2 len

    str.len

Returns the length of the string in characters (not bytes).

Example:

    say "hello".len      #=> 5
    say "€".len          #=> 1
    say "café".len       #=> 4

Aliases: I<size>, I<length>, I<chars_len>, I<chars_length>

=cut

=head2 lev

    levenshtein(str1, str2)

Calculates the Levenshtein distance between two strings, which is the minimum number of single-character edits (insertions, deletions, or substitutions) required to transform one string into the other.

Example:

    say levenshtein("kitten", "sitting")    #=> 3
    say levenshtein("hello", "hallo")       #=> 1

Aliases: I<leven>, I<levenshtein>

=cut

=head2 lines

    str.lines

Returns an array of the lines in a string. A line is defined as a sequence of characters terminated by a newline character ("\n") or a carriage return character followed by a newline character ("\r\n").

Example:

    say "line1\nline2\nline3".lines    #=> ["line1", "line2", "line3"]

=cut

=head2 ltrim

    str.ltrim
    str.ltrim(regex)

Takes a regular expression regex and removes any substring from the beginning of the string str that matches the regular expression. The resulting string is returned.

When no argument is given, it strips whitespace characters from the beginning of the string.

Example:

    say "  hello  ".ltrim          #=> "hello  "
    say "xxxhello".ltrim(/x+/)     #=> "hello"

Aliases: I<lstrip>, I<trim_beg>, I<strip_beg>, I<trim_left>, I<strip_left>

=cut

=head2 md5

    str.md5

Returns the MD5 digest for the given string in hexadecimal form. MD5 is a widely-used cryptographic hash function that produces a 128-bit hash value.

Example:

    say "hello".md5    #=> "5d41402abc4b2a76b9719d911017c592"

=cut

=head2 new

    Str(args...)

Creates a new string, by concatenating together a given list of objects. Each object is converted to its string representation.

Example:

    say Str("hello", " ", "world")    #=> "hello world"
    say Str(1, 2, 3)                  #=> "123"

Aliases: I<call>

=cut

=head2 num

    str.num(base=10)

Returns the numeric representation of the string according to the specified base.

Parameters:

    base : An integer representing the numeric base to use for conversion. Valid values for base are between 2 and 62 (inclusive). If not specified, base defaults to 10.

Example:

    say "123".num         #=> 123
    say "FF".num(16)      #=> 255
    say "1010".num(2)     #=> 10

Aliases: I<to_n>, I<to_num>

=cut

=head2 nums

    str.nums

Returns a list of numbers that were found in the string. The function splits the string by whitespace, and collects every word that looks like a number. The numbers in the returned list will be in the same order that they appeared in the string.

Example:

    say "test 123 and 456".nums    #=> [123, 456]
    say "1.5 -2.3 test".nums       #=> [1.5, -2.3]

Aliases: I<numbers>

=cut

=head2 oct

    str.oct

Converts an octal string to a Number object. The string is interpreted as a base-8 number. The "0o" or "0O" prefix is optional.

Example:

    say "10".oct       #=> 8
    say "0o77".oct     #=> 63
    say "777".oct      #=> 511

=cut

=head2 open_r

    str.open_r(mode='<')

Opens a file with the name specified by the string and returns a file handle for reading or writing. The mode parameter specifies how the file should be opened.

Example:

    var fh = "myfile.txt".open_r
    say fh.readline

=cut

=head2 ord

    str.ord

Returns the Unicode code point value of the first character in the string.

Example:

    say "A".ord        #=> 65
    say "€".ord        #=> 8364
    say "hello".ord    #=> 104

=cut

=head2 overlaps

    overlaps(str1, str2)

Checks whether there is any overlap between two strings, i.e., whether they have any characters in common. It returns True if there is any overlap, and False otherwise.

Example:

    say overlaps("hello", "world")    #=> true (both have 'o' and 'l')
    say overlaps("abc", "xyz")        #=> false

=cut

=head2 pack

    str.pack(*list)

Creates a binary string from a list of values according to a template format specified by the string. This is similar to Perl's pack function.

Example:

    say "A*".pack("hello")         # Pack as ASCII string
    say "C*".pack(72, 105)         # Pack as unsigned chars

=cut

=head2 parse_quotewords

    str.parse_quotewords(delim=' ', keep=false)

Parse a string into an Array of words or phrases. It takes a string as an input and returns an Array of words or phrases parsed from the input string. The function can also handle quoted phrases, allowing users to specify phrases containing delimiters.

The method takes three parameters:

    str     : A string that needs to be split into words.
    delim   : A string that represents the delimiter to be used while splitting the string. The default value is a space character (' ').
    keep    : A Boolean value that indicates whether to keep the quotes around quoted words or not. The default value is False.

Example:

    say "one two 'three four'".parse_quotewords    #=> ["one", "two", "three four"]

=cut

=head2 pipe

    str.pipe

Executes the string as a shell command and opens a pipe to it, returning a file handle for reading from or writing to the command.

Example:

    var fh = "ls -l".pipe
    say fh.slurp

=cut

=head2 pop

    str.pop

Returns the last character of the string. If the string is empty, returns nil.

Example:

    say "hello".pop    #=> "o"
    say "test".pop     #=> "t"

=cut

=head2 prepend

    str.prepend(prefix)

Returns a new string with the C<prefix> added to the beginning of the C<str>.

Example:

    say "world".prepend("hello ")    #=> "hello world"

=cut

=head2 printf

    str.printf(*arguments)

Formats and prints the string using the provided arguments. This is similar to C's printf function.

Example:

    "%s has %d apples".printf("Alice", 5)    # Prints: Alice has 5 apples

=cut

=head2 range

    from.range(to, step=1)

Returns an iterator that produces strings from C<from> to C<to> with the specified step. This is similar to the C<..> operator but returns an iterator instead of an array.

Example:

    say 'a'.range('e').to_a    #=> ["a", "b", "c", "d", "e"]

=cut

=head2 require

    str.require

Loads a Sidef module specified by the string. Returns true if successful.

Example:

    "MyModule".require    # Loads MyModule

=cut

=head2 rindex

    str.rindex(substr, pos)

Returns the index of the last occurrence of a substring in the string, searching backwards from the specified position. Returns -1 if not found.

Example:

    say "hello world".rindex("o")       #=> 7
    say "hello world".rindex("o", 6)    #=> 4
    say "hello world".rindex("xyz")     #=> -1

=cut

=head2 rotate

    str.rotate(n)

Rotates the characters in the string by n positions. Positive values rotate right, negative values rotate left.

Example:

    say "abcde".rotate(2)     #=> "deabc"
    say "abcde".rotate(-1)    #=> "bcdea"

=cut

=head2 rtrim

    str.rtrim
    str.rtrim(regex)

Removes any substring from the end of the string that matches the given regular expression. When no argument is given, it strips whitespace characters from the end of the string.

Example:

    say "  hello  ".rtrim          #=> "  hello"
    say "helloxxx".rtrim(/x+/)     #=> "hello"

Aliases: I<rstrip>, I<trim_end>, I<strip_end>, I<trim_right>, I<strip_right>

=cut

=head2 run

    method.run(str, *args)

Dynamically invokes a method on the string. The method name is given as a string, and additional arguments are passed to the method.

Example:

    "uc".run("hello")    #=> "HELLO"

=cut

=head2 sayf

    str.sayf(*arguments)

Formats and prints the string using the provided arguments, followed by a newline.

Example:

    "%s has %d apples".sayf("Alice", 5)    # Prints: Alice has 5 apples\n

Aliases: I<printlnf>

=cut

=head2 scan

    str.scan(regex)

Scans the string for matches of the given regular expression and returns an array of all matches. This is similar to the C<collect> method.

Example:

    say "foo bar baz".scan(/\w+/)    #=> ["foo", "bar", "baz"]

=cut

=head2 sha1

    str.sha1

Returns the SHA-1 digest for the given string in hexadecimal form. SHA-1 is a cryptographic hash function that produces a 160-bit hash value.

Example:

    say "hello".sha1    #=> "aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d"

=cut

=head2 sha256

    str.sha256

Returns the SHA-256 digest for the given string in hexadecimal form. SHA-256 is a member of the SHA-2 family and produces a 256-bit hash value.

Example:

    say "hello".sha256    #=> "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"

=cut

=head2 sha512

    str.sha512

Returns the SHA-512 digest for the given string in hexadecimal form. SHA-512 is a member of the SHA-2 family and produces a 512-bit hash value.

Example:

    say "hello".sha512    #=> (long hex string)

=cut

=head2 slice

    str.slice(offset)
    str.slice(offset, length)

Extracts a substring out of the string and returns it. First character is at offset zero.

If C<offset> is negative, starts that far back from the end of the string.

If C<length> is omitted, returns everything through the end of the string.

If C<length> is negative, leaves that many characters off the end of the string.

Example:

    say "hello world".slice(0, 5)     #=> "hello"
    say "hello world".slice(6)        #=> "world"
    say "hello world".slice(-5)       #=> "world"
    say "hello world".slice(0, -6)    #=> "hello"

Aliases: I<substr>, I<substring>

=cut

=head2 slices

    str.slices(n)

Takes a string and divides it into slices of a specified length. The length of the slice is specified by the integer parameter C<n>. If the length of the string is not evenly divisible by C<n>, the last slice will be shorter than C<n> characters.

Example:

    say "abcdefgh".slices(3)    #=> ["abc", "def", "gh"]
    say "test".slices(2)        #=> ["te", "st"]

=cut

=head2 sort

    str.sort
    str.sort { |a, b| ... }

Returns a new string with the characters sorted. When a block is provided, it's used as the comparison function.

Example:

    say "dcba".sort           #=> "abcd"
    say "hello".sort          #=> "ehllo"

=cut

=head2 split

    str.split(sep, limit)

Splits the string into an array of substrings using the specified separator. The C<sep> can be a string or a regular expression. If C<limit> is specified, the array will contain at most C<limit> elements.

Example:

    say "a,b,c".split(',')         #=> ["a", "b", "c"]
    say "hello world".split(' ')   #=> ["hello", "world"]
    say "one:two:three".split(':', 2)    #=> ["one", "two:three"]

=cut

=head2 sprintlnf

    str.sprintlnf(*arguments)

Formats the string using the provided arguments and appends a newline, returning the formatted string without printing it.

Example:

    var s = "%s has %d apples".sprintlnf("Alice", 5)
    say s    # Alice has 5 apples\n

=cut

=head2 sub

    str.sub(regex, replacement)

Performs a substitution, replacing the first match of the regular expression with the replacement string.

Example:

    say "hello world".sub(/l/, "L")    #=> "heLlo world"
    say "foo bar".sub(/o/, "0")        #=> "f0o bar"

Aliases: I<replace>

=cut

=head2 tc

    str.tc

Returns a new string where each word in the input string C<str> is capitalized (first letter uppercase, rest lowercase).

Example:

    say "hello world".tc    #=> "Hello World"
    say "test CASE".tc      #=> "Test Case"

Aliases: I<ucfirst>, I<titlecase>

=cut

=head2 tclc

    str.tclc

Returns the string with the first character capitalized and the remaining characters in lower case.

Example:

    say "hello WORLD".tclc    #=> "Hello world"

Aliases: I<capitalize>

=cut

=head2 to_i

    str.to_i

Converts the string to an integer. This is equivalent to calling C<num()> with base 10.

Example:

    say "123".to_i     #=> 123
    say "-456".to_i    #=> -456

Aliases: I<to_int>

=cut

=head2 to_s

    str.to_s

Returns the string itself. Since the object is already a string, this is an identity operation.

Example:

    say "hello".to_s    #=> "hello"

Aliases: I<to_str>

=cut

=head2 tr

    str.tr(orig, repl, modes='')

Transliterates characters in the string. Replaces all occurrences of characters in C<orig> with corresponding characters in C<repl>. The C<modes> parameter can include options like 'c' for complement, 'd' for delete, or 's' for squeeze.

Example:

    say "hello".tr('el', 'ip')       #=> "hippo"
    say "hello".tr('aeiou', '')      #=> "hll" (delete vowels)

Aliases: I<translit>

=cut

=head2 trans

    str.trans(orig, repl)

Similar to C<tr>, but performs character-by-character translation from C<orig> to C<repl>.

Example:

    say "hello".trans('elo', 'xyz')    #=> "hxyxz"

=cut

=head2 trim

    str.trim
    str.trim(regex)

Removes whitespace (or characters matching the regex) from both the beginning and end of the string.

Example:

    say "  hello  ".trim         #=> "hello"
    say "xxxhelloxxx".trim(/x+/) #=> "hello"

Aliases: I<strip>

=cut

=head2 uc

    str.uc

Convert all the characters in a string to uppercase. It takes a string as an input and returns the same string with all the characters converted to uppercase.

Example:

    say "hello world".uc    #=> "HELLO WORLD"
    say "test".uc           #=> "TEST"

Aliases: I<upper>, I<upcase>

=cut

=head2 unescape

    str.unescape

Removes backslash escapes from a string. The reverse of the C<str.escape> method.

Example:

    say "hello\\.world".unescape    #=> "hello.world"
    say "\\(test\\)".unescape       #=> "(test)"

=cut

=head2 uniq

    str.uniq

Returns a new string with duplicate characters removed, keeping only the first occurrence of each character.

Example:

    say "hello".uniq        #=> "helo"
    say "aabbcc".uniq       #=> "abc"

Aliases: I<unique>, I<distinct>

=cut

=head2 unpack

    str.unpack(template)

Extracts values from a binary string according to a template format. This is the reverse of the C<pack> operation.

Example:

    say "Hi".unpack("C*")    #=> [72, 105]

=cut

=head2 use

    str.use

Loads and imports a Sidef module specified by the string. Similar to C<require> but also imports symbols.

Example:

    "MyModule".use    # Loads and imports MyModule

=cut

=head2 warn

    str.warn

Prints the string to STDERR as a warning message but does not terminate the program (unlike C<die>).

Example:

    "Warning: something might be wrong".warn    # Prints warning to STDERR

=cut

=head2 wc

    str.wc

Change the case of words in a string. It takes a string as an input and returns the same string with the case of each word modified, making the first letter uppercase and the other letters lowercase.

Example:

    say "hello WORLD test".wc    #=> "Hello World Test"

Aliases: I<wordcase>

=cut

=head2 words

    str.words

Split a string into words. It takes a string as an input and returns an Array of words in the string. A word is defined as a sequence of characters separated by whitespace characters.

Example:

    say "hello world test".words    #=> ["hello", "world", "test"]
    say "one  two   three".words    #=> ["one", "two", "three"]

=cut

=head1 SEE ALSO

L<Sidef::Types::Number::Number>, L<Sidef::Types::Array::Array>, L<Sidef::Types::Regex::Regex>

=cut
