
=encoding utf8

=head1 NAME

Sidef::Types::String::String

=head1 DESCRIPTION

This class implements ...

=head1 SYNOPSIS

var obj = String(...)


=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.

Aliases: I<sprintf>

=cut

=head2 &

    str1 & str2

Performs a bitwise B<AND> operation on two strings and returns the result as a new string.

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.

Aliases: I<mul>, I<repeat>

=cut

=head2 +

    str1 + str2

Concatenates two strings into a single string.

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

=cut

=head2 ++

    a++

Increments an alphanumeric string to the next ASCIIbetical string.

Aliases: I<inc>

=cut

=head2 -

    str - substr
    str - regex

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

    'fo 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)>.

Aliases: I<to>, I<upto>

=cut

=head2 /

    str / n

Divide the C<str> into at least C<n> parts, returing an Array object.

    'foobar' / 2   => ["foo", "bar"]
    'fooba' / 2    => ["fo", "ob", "a"]

Aliases: I<÷>, I<div>

=cut

=head2 <

    str1 < str2

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

Aliases: I<lt>

=cut

=head2 <<

    str << n

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

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>.

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.

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.

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.

Aliases: I<match>

=cut

=head2 >

    str1 > str2

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

Aliases: I<gt>

=cut

=head2 >>

    str >> n

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

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.

Aliases: I<xor>

=cut

=head2 |

    str1 | str2

Performs a bitwise B<OR> operation on two strings and returns the result as a new string.

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.

Aliases: I<not>

=cut

=head2 ≠

    str1 ≠ str2

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

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

=cut

=head2 ≤

    str1 ≤ str2

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

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

=cut

=head2 ≥

    str1 ≥ str2

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

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

=cut

=head2 apply_escapes

    self.apply_escapes(parser)

Returns the

=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.

=cut

=head2 ascii2bits

    self.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.

=cut

=head2 backtick

    self.backtick

Returns the

=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.

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.

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.

Aliases: I<starts_with>

=cut

=head2 bin

    self.bin

Returns the

=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.

=cut

=head2 byte

    self.byte(pos)

Returns the

Aliases: I<byte_at>

=cut

=head2 bytes

    str.bytes

Convert a string into an Array of bytes, ranging from C<0> to C<255>.

=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.

Aliases: I<bytes_length>

=cut

=head2 center

    self.center(size, char)

Returns the

=cut

=head2 char

    self.char(pos)

Returns the

Aliases: I<char_at>

=cut

=head2 chars

    str.chars

Convert a string into an Array of characters.

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

=cut

=head2 chomp

    self.chomp

Returns the

=cut

=head2 chop

    self.chop

Returns the

=cut

=head2 clear

    self.clear

Returns the

=cut

=head2 codes

    str.codes

Convert a string into an Array of code points.

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

Aliases: I<code_points>

=cut

=head2 collect

    self.collect(regex)

Returns the

Aliases: I<find_all>, I<findall>

=cut

=head2 cons

    self.cons(n)

Returns the

=cut

=head2 count

    self.count(arg)

Returns the

=cut

=head2 crypt

    self.crypt(salt)

Returns the

=cut

=head2 decode

    str.decode(enconding)

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.

=cut

=head2 decode_utf8

    str.decode_utf8

Decodes a UTF-8 encoded string and returns the corresponding Unicode string.

=cut

=head2 deflate

    self.deflate

Returns the

=cut

=head2 die

    self.die

Returns the

=cut

=head2 digits

    self.digits

Returns the

=cut

=head2 downto

    from.downto(to, step)

Returns the

=cut

=head2 dump

    self.dump

Returns the

Aliases: I<inspect>

=cut

=head2 each

    self.each {|char| ... }

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

Aliases: I<each_char>

=cut

=head2 each_byte

    self.each_byte {|byte| ... }

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

=cut

=head2 each_cons

    self.each_cons(n, block)

Returns the

=cut

=head2 each_graph

    self.each_graph {|grapheme| ... }

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

Aliases: I<each_grapheme>

=cut

=head2 each_kv

    self.each_kv(block)

Returns the

=cut

=head2 each_line

    self.each_line {|line| ... }

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

=cut

=head2 each_num

    self.each_num {|num| ... }

Iterates through each word, converted to a number, in the string and applies a given block of code to each number.

Aliases: I<each_number>

=cut

=head2 each_slice

    self.each_slice(n, block)

Returns the

=cut

=head2 each_word

    self.each_word {|word| ... }

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

=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.

=cut

=head2 encode_utf8

    self.encode_utf8

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

=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.

=cut

=head2 escape

    str.escape

Returns a copy of the input string with all non-word characters escaped using a backslash character.

Aliases: I<quotemeta>

=cut

=head2 esub

    self.esub(regex, block)

Returns the

=cut

=head2 extract_bracketed

    self.extract_bracketed(brackets)

Returns the

=cut

=head2 extract_codeblock

    self.extract_codeblock(delim)

Returns the

=cut

=head2 extract_delimited

    self.extract_delimited(delim)

Returns the

=cut

=head2 extract_quotelike

    self.extract_quotelike

Returns the

=cut

=head2 extract_tagged

    self.extract_tagged

Returns the

=cut

=head2 fc

    str.fc

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

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.

Aliases: I<foldcase>

=cut

=head2 flip

    str.flip

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

Aliases: I<reverse>

=cut

=head2 format

    self.format

Returns the

=cut

=head2 frequire

    self.frequire

Returns the

=cut

=head2 gesub

    self.gesub(regex, block)

Returns the

=cut

=head2 glob

    self.glob

Returns the

=cut

=head2 gmatch

    self.gmatch(regex, pos)

Returns the

=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.

Aliases: I<graphemes>

=cut

=head2 graphs_len

    str.graphs_len

Returns the number of grapheme clusters in the input string.

Aliases: I<graphs_length>

=cut

=head2 gsub

    self.gsub(regex, str)

Returns the

Aliases: I<replace_all>

=cut

=head2 gunzip

    self.gunzip

Returns the

=cut

=head2 gzip

    self.gzip

Returns the

=cut

=head2 has

    self.has(substr, pos=0)
    self.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.

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

=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.

=cut

=head2 hex

    self.hex

Returns the

=cut

=head2 hex2ascii

    self.hex2ascii

Decodes a hexadecimal string and returns its equivalent byte-string.

Aliases: I<unhexlify>

=cut

=head2 hexlify

    self.hexlify

Encodes the input string as a hexadecimal string.

Aliases: I<ascii2hex>

=cut

=head2 index

    str.index(substr, pos)

Returns the index of the first occurrence of a substring in a given string starting from a specified position.

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.

=cut

=head2 inflate

    self.inflate

Returns the

=cut

=head2 insert

    str.insert(substring, pos, len)

Inserts a substring into a given string at a specified position for a given length.

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 original string from the position where the insertion is to begin.

=cut

=head2 ints

    self.ints

Returns the

Aliases: I<integers>

=cut

=head2 is_alnum

    self.is_alnum

Returns the

Aliases: I<is_alphanum>

=cut

=head2 is_alpha

    self.is_alpha

Returns the

=cut

=head2 is_ascii

    self.is_ascii

Returns the

=cut

=head2 is_blank

    self.is_blank

Returns the

=cut

=head2 is_control

    self.is_control

Returns the

=cut

=head2 is_digit

    self.is_digit

Returns the

=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.

=cut

=head2 is_graph

    self.is_graph

Returns the

=cut

=head2 is_lc

    self.is_lc

Returns the

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.

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.

=cut

=head2 is_printable

    self.is_printable

Returns the

=cut

=head2 is_punct

    self.is_punct

Returns the

Aliases: I<is_punctuation>

=cut

=head2 is_space

    self.is_space

Returns the

=cut

=head2 is_uc

    self.is_uc

Returns the

Aliases: I<is_uppercase>

=cut

=head2 is_word

    self.is_word

Returns the

=cut

=head2 is_xdigit

    self.is_xdigit

Returns the

=cut

=head2 iter

    self.iter

Returns the

=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.

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

When the third argument is true, it returns the Jaro-Winkler similarity score.

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

=cut

=head2 join

    delim.join(strings...)

Concatenates a list of strings and returns a single string, using a specified delimiter.

=cut

=head2 last

    str.last(n)

Returns the last n characters of a string.

=cut

=head2 lc

    str.lc

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

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.

=cut

=head2 len

    str.len

Returns the length of the string.

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.

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").

=cut

=head2 ltrim

    str.ltrim
    self.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.

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.

=cut

=head2 new

    Str(args...)

Creates a new string, by concatenating together a given list of objects.

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.

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.

Aliases: I<numbers>

=cut

=head2 oct

    self.oct

Returns the

=cut

=head2 open_r

    self.open_r(mode)

Returns the

=cut

=head2 ord

    self.ord

Returns the

=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.

=cut

=head2 pack

    self.pack(*list)

Returns the

=cut

=head2 parse_quotewords

    str.parse_quotewords(delim, keep)

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.

=cut

=head2 pipe

    self.pipe

Returns the

=cut

=head2 pop

    str.pop

Returns the last character of the string.

=cut

=head2 prepend

    str.prepend(prefix)

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

=cut

=head2 printf

    self.printf(*arguments)

Returns the

=cut

=head2 range

    from.range(to, step)

Returns the

=cut

=head2 require

    self.require

Returns the

=cut

=head2 rindex

    self.rindex(substr, pos)

Returns the

=cut

=head2 rotate

    self.rotate(n)

Returns the

=cut

=head2 rtrim

    self.rtrim(arg)

Returns the

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

=cut

=head2 run

    method.run(self, *args)

Returns the

=cut

=head2 sayf

    self.sayf(*arguments)

Returns the

Aliases: I<printlnf>

=cut

=head2 scan

    self.scan(regex)

Returns the

=cut

=head2 sha1

    self.sha1

Returns the

=cut

=head2 sha256

    self.sha256

Returns the SHA-256 digest for the given string in hexadecimal form.

=cut

=head2 sha512

    str.sha512

Returns the SHA-512 digest for the given string in hexadecimal form.

=cut

=head2 slice

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

Extracts a substring out of the self-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.

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.

=cut

=head2 sort

    self.sort(block)

Returns the

=cut

=head2 split

    self.split(sep, size)

Returns the

=cut

=head2 sprintlnf

    self.sprintlnf(*arguments)

Returns the

=cut

=head2 sub

    self.sub(regex, str)

Returns the

Aliases: I<replace>

=cut

=head2 tc

    str.tc

Returns a new string where each word in the input string C<str> is capitalized.

Aliases: I<ucfirst>, I<titlecase>

=cut

=head2 tclc

    self.tclc

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

Aliases: I<capitalize>

=cut

=head2 to_i

    self.to_i

Returns the

Aliases: I<to_int>

=cut

=head2 to_s

    self.to_s

Returns the

Aliases: I<to_str>

=cut

=head2 tr

    self.tr(orig, repl, modes)

Returns the

Aliases: I<translit>

=cut

=head2 trans

    self.trans(orig, repl)

Returns the

=cut

=head2 trim

    self.trim(arg)

Returns the

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.

Aliases: I<upper>, I<upcase>

=cut

=head2 unescape

    str.unescape

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

=cut

=head2 uniq

    self.uniq

Returns the

Aliases: I<unique>, I<distinct>

=cut

=head2 unpack

    self.unpack(arg)

Returns the

=cut

=head2 use

    self.use

Returns the

=cut

=head2 warn

    self.warn

Returns the

=cut

=head2 wc

    self.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.

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.

=cut
