NAME

Sidef::Types::String::String

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.

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

INHERITS

Inherits methods from:

* Sidef::Object::Object

METHODS

%

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: sprintf

&

str1 & str2

Performs a bitwise 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: and

*

str * n

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

Example:

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

Aliases: mul, repeat

+

str1 + str2

Concatenates two strings into a single string.

Example:

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

Aliases: add, append, concat

++

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: inc

-

str - substr
str - regex

Remove from str the first occurrence of 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: diff

..

a .. b

Returns a RangeStr object: 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: to, upto

/

str / n

Divide the str into at least 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: ÷, div

<

str1 < str2

Returns true if str1 is lexicographically less than str2.

Example:

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

Aliases: lt

<<

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: drop_left, shift_left

<=>

str1 <=> str2

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

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

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

If the two strings are equal, the function returns 0.

Example:

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

Aliases: cmp

==

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: eq

=~

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: match

>

str1 > str2

Returns true if str1 is lexicographically greater than str2.

Example:

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

Aliases: gt

>>

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: drop_right, shift_right

^

str1 ^ str2

Performs a bitwise 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: xor

|

str1 | str2

Performs a bitwise 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: or

~

~str

Performs a bitwise unary 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: not

≠

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: !=, ne

≤

str1 ≤ str2

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

Example:

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

Aliases: <=, le

≥

str1 ≥ str2

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

Example:

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

Aliases: >=, ge

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)

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"

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"

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.

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 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: decode_base64

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 base64_encode() method encodes the input string in base64 format.

Example:

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

Aliases: encode_base64

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: starts_with

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

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"

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: byte_at

bytes

str.bytes

Convert a string into an Array of bytes, ranging from 0 to 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]

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: bytes_length

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

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: char_at

chars

str.chars

Convert a string into an Array of characters.

Example:

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

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"

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        #=> ""

clear

str.clear

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

Example:

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

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: code_points

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: find_all, findall

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

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

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

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

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     #=> "é"

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)

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

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  #=> []

downto

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

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

Example:

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

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: inspect

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: each_char

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

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

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: each_grapheme

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

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 }

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: each_number

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

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

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

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]

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

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: quotemeta

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"

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

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

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

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

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

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: foldcase

first

str.first(n)

Returns the first n characters of the input string, where 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"

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: reverse

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"

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

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"

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

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

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: graphemes

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: graphs_length

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: replace_all

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"

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

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: contain, include, contains, includes

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

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: unhexlify

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: ascii2hex

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

inflate

str.inflate

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

Example:

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

insert

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

Inserts a substring into a given string at a specified position, optionally replacing 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"

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: integers

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: is_alphanum

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

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)

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

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

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

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

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)

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: is_lowercase

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: looks_like_number

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

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)

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: is_punctuation

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

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: is_uppercase

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)

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

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"

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

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"

last

str.last(n)

Returns the last n characters of a string.

Example:

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

lc

str.lc

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

Example:

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

Aliases: lower, downcase, lowercase

lcfirst

str.lcfirst

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

Example:

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

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: size, length, chars_len, chars_length

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: leven, levenshtein

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

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: lstrip, trim_beg, strip_beg, trim_left, strip_left

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"

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: call

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: to_n, to_num

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: numbers

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

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

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

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

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

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

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

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"

prepend

str.prepend(prefix)

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

Example:

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

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

range

from.range(to, step=1)

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

Example:

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

require

str.require

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

Example:

"MyModule".require    # Loads MyModule

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

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"

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: rstrip, trim_end, strip_end, trim_right, strip_right

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"

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: printlnf

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

Example:

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

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"

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"

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)

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 offset is negative, starts that far back from the end of the string.

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

If 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: substr, substring

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 n. If the length of the string is not evenly divisible by n, the last slice will be shorter than n characters.

Example:

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

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"

split

str.split(sep, limit)

Splits the string into an array of substrings using the specified separator. The sep can be a string or a regular expression. If limit is specified, the array will contain at most 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"]

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

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: replace

tc

str.tc

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

Example:

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

Aliases: ucfirst, titlecase

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: capitalize

to_i

str.to_i

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

Example:

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

Aliases: to_int

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: to_str

tr

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

Transliterates characters in the string. Replaces all occurrences of characters in orig with corresponding characters in repl. The 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: translit

trans

str.trans(orig, repl)

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

Example:

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

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: strip

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: upper, upcase

unescape

str.unescape

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

Example:

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

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: unique, distinct

unpack

str.unpack(template)

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

Example:

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

use

str.use

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

Example:

"MyModule".use    # Loads and imports MyModule

warn

str.warn

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

Example:

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

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: wordcase

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

SEE ALSO

Sidef::Types::Number::Number, Sidef::Types::Array::Array, Sidef::Types::Regex::Regex

cpanm Sidef

perl -MCPAN -e shell
install Sidef