SPVM::Fn(3)

πŸ“¦ version 0.990125, in alpine 3.24

πŸŽ€ NAME πŸŽ€

SPVM::Fn β€” it's the SPVM standard functions class, bestie. We're talking numbers, strings, general utility stuff. It's the manual page for SPVM::Fn(3) and yes I have read every line of it so you don't have to πŸ’…

πŸ’– DESCRIPTION πŸ’–

The Fn class of SPVM has methods for numbers, strings, general utilities. That's the whole vibe. Numbers? handled. Strings? handled. General little utility tasks? bestie, handled. πŸ¦‹

✨ USAGE ✨

Okay so here's the little sampler platter of what Fn can do β€” look at it, it's giving range πŸ‘‘

  use Fn;

  # Cut a newline LF
  my $line = (mutable string)copy "abc\n";
  Fn->chomp($line);

  # Contains
  my $found = Fn->contains("pppabcde", "bcd");

  # Split
  my $csv = "foo,bar,baz";
  my $args_width = Fn->split(",", $string);

  # Join
  my $args_width = ["foo", "bar", "baz"];
  my $csv = Fn->join(",", $args_width);

  # Constant values
  my $byte_max = Fn->BYTE_MAX();
  my $short_max = Fn->SHORT_MAX();
  my $int_max = Fn->INT_MAX();
  my $long_max = Fn->LONG_MAX();

πŸ‘‘ CLASS METHODS πŸ‘‘

These are all static methods, so you call them like Fn->something() β€” no object era needed, we're doing class methods today, no cap. πŸ’…

BYTE_MAX

static method BYTE_MAX : byte ();

The same as INT8_MAX. That's it, that's the whole tea πŸ“

BYTE_MIN

static method BYTE_MIN : byte ();

The same as INT8_MIN. periodt.

DBL_MAX

static method DBL_MAX : double ();

Returns the value of the DBL_MAX macro defined in the float.h header of the C language. Very "borrowed from C, but make it slay" of it πŸ’€

DBL_MIN

static method DBL_MIN : double ();

Returns the value of the DBL_MIN macro defined in the float.h header of the C language. Same float.h energy, different macro 🌸

DOUBLE_MAX

static method DOUBLE_MAX : double ();

The same as DBL_MAX. lowkey just a nickname for it πŸŽ€

DOUBLE_MIN

static method DOUBLE_MIN : double ();

The same as DBL_MIN. twin behavior fr fr.

FLOAT_MAX

static method FLOAT_MAX : float ();

The same as FLT_MAX. iconic, consistent, no notes ✨

FLOAT_MIN

static method FLOAT_MIN : float();

The same as FLT_MIN. yes bestie, the signature really does have no space before the () β€” copying it exactly, that's her vibe πŸ’…

FLT_MAX

static method FLT_MAX : float ();

Returns the value of the FLT_MAX macro defined in the float.h header of the C language. float.h really said "I'll handle the constants" and it ATE πŸ“

FLT_MIN

static method FLT_MIN : float ();

Returns the value of the FLT_MIN macro defined in the float.h header of the C language. That's the float-minimum main character right there πŸ‘‘

INT16_MAX

static method INT16_MAX : short ();

Returns 32767. That's the maximum value of the signed 16bit integer. Big for a 16bit, honestly πŸ”₯

INT16_MIN

static method INT16_MIN : short ();

Returns -32768. That's the minimal value of the signed 16bit integer. Negative icon 🧊

INT32_MAX

static method INT32_MAX : int ();

Returns 2147483647. The maximum value of the signed 32bit integer. She's huge, she's classic, she's everywhere πŸ’–

INT32_MIN

static method INT32_MIN : int ();

Returns -2147483648. The minimal value of the signed 32bit integer. Down bad, numerically speaking 😭

INT64_MAX

static method INT64_MAX : long ();

Returns 9223372036854775807. The maximum value of the signed 64bit integer. Literally the biggest number energy in the building, no cap πŸ‘‘

INT64_MIN

static method INT64_MIN : long ();

Returns -9223372036854775808. The minimal value of the signed 64bit integer. Deep in the negatives and thriving πŸ’€

INT8_MAX

static method INT8_MAX : byte ();

Returns 127. The maximum value of the signed 8bit integer. Small but mighty, a little star 🌟

INT8_MIN

static method INT8_MIN : byte ();

Returns -128. The minimal value of the signed 8bit integer. Tiny and negative, we respect her πŸŽ€

INT_MAX

static method INT_MAX : int ();

The same as INT32_MAX. The alias that said "I'm her" πŸ’…

INT_MIN

static method INT_MIN : int ();

The same as INT32_MIN. Matching set, obviously 🫢

LONG_MAX

static method LONG_MAX : long ();

The same as INT64_MAX. Same number, longer name, still serving πŸ”₯

LONG_MIN

static method LONG_MIN : long ();

The same as INT64_MIN. The long-negativity of it all 😭

RAND_MAX

static method RAND_MAX : int ();

Returns 2147483647. Yeah she's INT32_MAX's number, but this is the random-number ceiling, so she gets her own moment ⭐

SHORT_MAX

static method SHORT_MAX : short ();

The same as INT16_MAX. Short name, big energy (32767 energy, specifically) 🌈

SHORT_MIN

static method SHORT_MIN : short ();

The same as INT16_MIN. Same as before but colder (it's -32768) 🧊

UBYTE_MAX

static method UBYTE_MAX : byte ();

The same as UINT8_MAX. The U stands for "unbothered" actually πŸ’…

UINT16_MAX

static method UINT16_MAX : short ();

Returns -1. This represents 0xFFFF in the unsigned 16bit integer in 2's complement. Yes, -1 β€” that's not a typo, that's two's complement doing her little trick, iykyk πŸ’€

UINT32_MAX

static method UINT32_MAX : int ();

Returns -1. This represents 0xFFFFFFFF in the unsigned 32bit integer in 2's complement. Same chaotic -1 situation, bigger hex, we love consistency πŸŽ€

UINT64_MAX

static method UINT64_MAX : long ();

Returns -1. This represents 0xFFFFFFFFFFFFFFFF in the unsigned 64bit integer in 2's complement. -1 again bestie, she contains multitudes πŸ”₯

UINT8_MAX

static method UINT8_MAX : byte ();

Returns -1. This represents 0xFF in the unsigned 8bit integer in 2's complement. The smallest -1 and yet still -1, iconic πŸ¦‹

UINT_MAX

static method UINT_MAX : int ();

The same as UINT32_MAX. Another alias, another slay πŸ’…

ULONG_MAX

static method ULONG_MAX : long

The same as UINT64_MAX. Note that the signature as documented here doesn't carry the trailing (); β€” I'm reproducing it exactly as she is, no editing, that's the rule 🫢

USHORT_MAX

static method USHORT_MAX : short ();

The same as UINT16_MAX. Short, unsigned, maximum, done ✨

abs

static method abs : int ($value : int);

Returns the absolute value of $value. No more negatives in this household, we're being positive today 🌈

chomp

static method chomp : int ($string : mutable string);

Removes "\r\n" or "\n" at the end of $string, and returns the removed length. Yes she mutates, that's why $string is a mutable string β€” she's bold like that πŸ’…

Exceptions:

  • $string must be defined. Otherwise an exception is thrown.
⚠️ Undefined input = exception. Do not pass her an undef and act surprised, bestie 😭

chompr

static method chompr : string ($string : string);

The "r" stands for respect, because this one copies $string and removes "\r\n" or "\n" at the end of the copied string and returns it. Original stays untouched, we love a gentle queen πŸŽ€

Exceptions:

  • $string must be defined. Otherwise an exception is thrown.

chr

static method chr : string ($code_point : int);

Converts $code_point to the UTF-8 character and return it. ✨

If $code_point is not a Unicode scalar value, return undef. So yeah, garbage in β†’ undef out, no drama, just undef πŸ€·β€β™€οΈ

contains

static method contains : int ($string : string, $substring : string, $begin : int = 0, $end : int = -1);

Checks if $string contains $substring. The little "is it in there" vibe check πŸ’–

Implementation:

The alias for the following code using index method.

  my $ret = Fn->index($string, $substring, $begin, $end) >= 0;

So if you were wondering how she does it β€” that's exactly how. No mystery, just index with a >= 0 filter πŸ”₯

copy_string

static method copy_string : string ($string : string);

The alias for the following code using copy operator:

  my $ret = copy $string;

That's it. A whole method whose entire personality is a copy operator. Relatable honestly πŸ™ˆ

crand

static method crand : int ($seed_ref : int*);

Create a random number from 0 to RAND_MAX using $$seed_ref and return it. 🎲

$$seed_ref is updated. So yes, that reference gets written to β€” that's the whole point, she needs her state, let her live πŸ’…

This method is thread safe. Bestie said "I can handle threads" and she MEANT it πŸ‘‘

Examples:

  use Sys::Time;
  my $seed = (int)Sys::Time->time;
  my $crand0 = Fn->crand(\$seed);
  my $crand1 = Fn->crand(\$seed);

equals_string_range

static method equals_string_range : int ($string1 : string, $string1_offset : int, $string2 : string, $string2_offset : int, $length : int);

Compares $string1 + $string1_offset with $string2 + $string2_offset by $length. If they are equal, returns 1, otherwise returns 0. A little slice-vs-slice comparison, very precise of her πŸ”

If $length is 0, returns 1. Zero length = automatically equal, that's the rule πŸŽ€

Exceptions:

  • $string1 must be defined. Otherwise an exception is thrown.
  • $string2 must be defined. Otherwise an exception is thrown.
  • $string1_offset must be greater than or equal to 0. Otherwise an exception is thrown.
  • $string2_offset must be greater than or equal to 0. Otherwise an exception is thrown.
⚠️ Both strings must exist, and both offsets have to be >= 0. Negative offsets get you thrown out, literally, with an exception πŸ’€

get_code_point

static method get_code_point : int ($string : string, $offset_ref : int*);

Parses the UTF-8 character at the value referred by $offset_ref of $string and return its Unicode code point. πŸ¦‹

The offset is updated to the position of the next UTF-8 character. So she walks forward through your string, one character at a time, very "main character doing a little stroll" πŸšΆβ€β™€οΈ

Exceptions:

  • $string must be defined. Otherwise an exception is thrown.
  • $offset must be greater than or equal to 0. Otherwise an exception is thrown.
  • The value of $offset must be less than the length of $string. Otherwise an exception is thrown.

If an invalid UTF-8 is gotten, an exception is thrown set eval_error_id to the basic type ID of Error::Unicode::InvalidUTF8 class.

⚠️ Invalid UTF-8 does not get a casual undef. She throws, and she sets eval_error_id to the basic type ID of Error::Unicode::InvalidUTF8. Catch it properly, bestie, don't let it slide 😭

hex

static method hex : int ($hex_string : string);

Converts $hex_string to the int value and return it. Hexadecimal in, integer out, glow-up complete ✨

Exceptions:

  • $hex string must be defined. Otherwise an exception is thrown.
  • The length of $hex string must be 1 to 8. Otherwise an exception is thrown.
  • $hex string must contain only hex characters 0-9a-zA-Z. Otherwise an exception is thrown.

(Yeah, the original writes $hex string with a space in the exception notes, and I'm keeping that exactly as written β€” not my typo to fix, it's hers πŸ’…)

⚠️ Too short, too long, or full of non-hex characters? Exception. She's strict and honestly that's valid πŸ‘‘

index

static method index : int ($string : string, $substring : string, $begin : int = 0, $end : int = -1);

Searches for $substring in the range of $string from $begin to $end. πŸ”

The search is performed from the beginning of the range of $string.

If $substring is found, returns the found offset. Otherwise, returns -1. Classic "-1 means she's not here" behavior, we stan a predictable queen πŸ’…

If $end is less than 0, $end is set to the length of $string minus 1.

Exceptions:

  • $string must be defined. Otherwise an exception is thrown.
  • $substring must be defined. Otherwise an exception is thrown.
  • $begin must be greater than or equal to 0. Otherwise an exception is thrown.
  • $end must be less than the length of $string.
⚠️ $end has to be less than the length of $string. This is a real requirement, not a suggestion 🫢

init_string

static method init_string : void ($string : mutable string, $ascii_code : int = 0, $offset = 0 int, $length = -1);

Sets the characters in $string from $offset to the position proceeded by $length to $ascii_code. Like a little paint bucket for your string, but make it ASCII 🎨

If $length is less than 0, $length is set to the length of $string - $offset. That's the auto-fill-the-rest default, very convenient πŸŽ€

Exceptions:

  • $string must be defined. Otherwise an exception is thrown.
  • $offset + $length must be less than or equal to the length of $string.
⚠️ (And yes β€” the signature says $offset = 0 int and I am copying it character for character, because the one rule that matters most is that nothing changes. πŸ’…)

is_alnum

static method is_alnum : int ($code_point : int);

If the Unicode $code_point is an ASCII alphanumeric A-Za-z0-9, returns 1, otherwise returns 0. Letters OR numbers = alnum, that's the whole test πŸ”€

is_alpha

static method is_alpha : int ($code_point : int);

If the Unicode $code_point is an ASCII alphabetic A-Za-z, returns 1, otherwise returns 0. Letters only, numbers need not apply πŸ’–

is_array

static method is_array : int ($object : object);

If $object is defined and the type of $object is array type, returns 1, otherwise returns 0. πŸ“¦

is_array in SPVM::Document::NativeAPI is used to check the type. So yeah, that's where the actual type-checking magic lives, go read that too, bestie πŸ‘‘

is_blank

static method is_blank : int ($code_point : int);

If the Unicode $code_point is an ASCII blank 0x20(SP, ' '), 0x09(HT, '\t'), returns 1, otherwise returns 0. Space or tab, nothing else counts as blank 🌸

is_class

static method is_class : int ($object : object);

If $object is defined and the type of $object is a class type, returns 1, otherwise returns 0. πŸŽ€

is_class in SPVM::Document::NativeAPI is used to check the type. Same deal as is_array β€” the real type inspection happens over there ✨

is_cntrl

static method is_cntrl : int ($code_point : int);

If the Unicode $code_point is an ASCII control character 0x00-0x1F, 0x7F, returns 1, otherwise returns 0. The spooky range, the invisible ones, the little gremlins of the character set πŸ’€

is_digit

static method is_digit : int ($code_point : int);

If the Unicode $code_point is an ASCII decimal digit 0-9, returns 1, otherwise returns 0. Just digits, no letters invited to the party πŸ”’

is_graph

static method is_graph : int ($code_point : int);

If $character is an ASCII graphical character 0x21-0x7E, returns 1, otherwise returns 0. The visible ones! The ones that show up! 🌈

is_hex_digit

static method is_hex_digit : int ($code_point : int);

If $character is a hexadecimal digit 0-9a-fA-F, returns 1, otherwise returns 0. Sixteen possible characters and she knows all of them πŸ’…

is_lower

static method is_lower : int ($code_point : int);

If the Unicode $code_point is an ASCII lowercase character a-z, returns 1, otherwise returns 0. lowercase besties rise 🫢

is_mulnum_array

static method is_mulnum_array : int ($object : object);

If $object is defined and the type of $object is a multi-numeric array type, returns 1, otherwise returns 0. πŸ”’

is_mulnum_array in SPVM::Document::NativeAPI is used to check the type. Yep, the NativeAPI page again, she's holding all the type-check lore ✨

is_numeric_array

static method is_numeric_array : int ($object : object);

If $object is defined and the type of $object is a numeric array type, returns 1, otherwise returns 0.

"is_numeric_array" in SPVM::Document::NativeAPI is used to check the type. Slay. ✨

πŸ¦‹ is_object_array

static method is_object_array : int ($object : object);

If $object is defined and the type of $object is an object array type, returns 1, otherwise returns 0.

"is_object_array" in SPVM::Document::NativeAPI is used to check the type. No cap. πŸ’…

πŸŽ€ is_perl_space

static method is_perl_space : int ($code_point : int);

If the Unicode $code_point is a Perl ASCII space character β€” "0x09(HT, '\t')", "0x0A(LF, '\n')", "0x0C(FF, '\f')", "0x0D(CR, '\r')", "0x20(SP, ' ')" β€” returns 1, otherwise returns 0.

Note that prior to Perl v5.18, "\s" in ASCII mode did not match the vertical tab 0x0B(VT). "is_perl_space" is the same as this behavior.

Current Perl "\s" in ASCII mode is the same as "is_space". Okayyy, history lesson but make it cute. 🌸

🧚 is_perl_word

static method is_perl_word : int ($code_point : int);

If the Unicode $code_point is a Perl ASCII word character "a-zA-Z0-9_", returns 1, otherwise returns 0. Periodt. πŸ’–

πŸ”₯ is_pointer_class

static method is_pointer_class : int ($object : object);

If $object is defined and $object is a pointer class, returns 1, otherwise returns 0.

"is_pointer_class" in SPVM::Document::NativeAPI is used to check the type. Iconic. πŸ‘‘

🌈 is_print

static method is_print : int ($code_point : int);

If the Unicode $$code_point is an ASCII printable character "0x20-0x7E", returns 1, otherwise returns 0.

Yes bestie, it really says $$code_point in the source. We keep the details. 😭

πŸ“ is_punct

static method is_punct : int ($code_point : int);

If the Unicode $code_point is an ASCII punctuation character β€” "0x21-0x2F", "0x3A-0x40", "0x5B-0x60", "0x7B-0x7E" β€” returns 1, otherwise returns 0. Punctuation girlies rise. πŸ’…

πŸ’œ is_space

static method is_space : int ($code_point : int);

If the Unicode $code_point is an ASCII white-space β€” "0x09(HT, '\t')", "0x0A(LF, '\n')", 0x0B(VT), "0x0C(FF, '\f')", "0x0D(CR, '\r')", "0x20(SP, ' ')" β€” returns 1, otherwise returns 0. Space check, but make it fashion. ✨

🌸 is_upper

static method is_upper : int ($code_point : int);

If $code_point is an ASCII uppercase character "A-Z", returns 1, otherwise returns 0.

Uppercase detection, main character energy. πŸ‘‘

⭐ is_xdigit

static method is_xdigit : int ($code_point : int);

If $code_point is an ASCII hexadecimal digit "0-9A-Fa-f", returns 1, otherwise returns 0.

Hex digits stay winning. πŸ”₯

🫢 join

static method join : string ($separator : string, $strings : string[]);

Concatenates $strings with $separater and returns it.

Yes, the source spells it $separater in the description while the signature says $separator. We are not fixing it, we are respecting the lore. πŸ’€

Exceptions:

  • $strings must be defined. Otherwise an exception is thrown.
  • $separator must be defined. Otherwise an exception is thrown.

πŸŽ€ labs

static method labs : long ($value : long);

Returns the absolute value of $value. Simple, clean, iconic. πŸ’–

πŸ¦‹ lc

static method lc : string ($string : string);

Converts the ASCII uppercase characters "A-Z" in $string to the corresponding ASCII lowercase characters "a-z". And returns it.

Exceptions:

  • $string must be defined. Otherwise an exception is thrown.

Lowercase slay. πŸ’…

🌈 lcfirst

static method lcfirst : string ($string : string);

If the first character of $string is an ASCII uppercase character "A-Z", it is converted to the corresponding ASCII lowercase character "a-z". And the converted string is returned.

Exceptions:

  • $string must be defined. Otherwise an exception is thrown.

Just the first character gets the lowercase treatment. We love a subtle edit. ✨

🧚 look_code_point

static method look_code_point : int ($string : string, $offset_ref : int*);

The same as get_code_point, but the offset is not updated. Peek, don't move. πŸ‘€

πŸ’œ memcpy

static method memcpy : void ($dest : object, $dest_offset : int, $source : object, $source_offset : int, $length : int);

Copies the range of $source to the range of $dest.

The range of $dest is from $offset to the position proceeded by $length of the destination.

The range of $source is from $offset to the position proceeded by $length of the source.

The unit of $offset and $length is "byte" size.

If the range of $source and the range of $dest overlap, the result is not guaranteed. This is the dramatic part. Use memmove if you need overlap safety. 😭

Exceptions:

  • $dest must be defined. Otherwise an exception is thrown.
  • The type of $dest must be the "string" type, the numeric array type, or the multi-numeric array type. Otherwise an exception is thrown.
  • $source must be defined. Otherwise an exception is thrown.
  • The type of $source must be the "string" type, the numeric array type, or the multi-numeric array type. Otherwise an exception is thrown.
  • $dest must not be a read-only string. Otherwise an exception is thrown.
  • $length must be greater than or equal to 0. Otherwise an exception is thrown.
  • $dest_offset + $length must be less than or equal to the length of $dest. Otherwise an exception is thrown.
  • $source_offset + $length must be less than or equal to the length of $source. Otherwise an exception is thrown.

πŸ“ memmove

static method memmove : void ($dest : object, $dest_offset : int, $source : object, $source_offset : int, $length : int);

The same as memcpy, but even if the range of $source and the range of $dest overlap, the result is guaranteed. Overlap-safe bestie. 🫢

🌸 ord

static method ord : int ($string : string);

The alias for the following code using get_code_point.

my $offset = 0;
my $code_point = Fn->get_code_point($string, \$offset);

Lowkey just a shortcut. πŸ’…

πŸ”₯ powi

static method powi : int ($base : int, $exponant : int);

Calculates the exponentiation from $base number and $exponant number.

Exceptions:

  • $exponant number must be greater than or equal to 0. Otherwise an exception is thrown.
  • If $base number is 0, $exponant number cannnot be 0.

Yes, exponant and cannnot are living here rent-free. We preserve the spelling. 😭

⭐ powl

static method powl : long ($base : long, $exponant : long);

Calculates the exponentiation from $base number and $exponant number.

Exceptions:

  • $exponant number must be greater than or equal to 0. Otherwise an exception is thrown.
  • If $base number is 0, $exponant number cannnot be 0.

Long version of the same energy. πŸ‘‘

πŸŽ€ rand

static method rand : double ($seed : int*, $max : int = 1);

Gets a 64bit floating point random number that is greater than or equal to 0 and less than $max using $seed.

If $max is specified, $max is multiplied to the return value.

The seed is updated.

This method is thread safe. Slay, concurrency-safe randomness. ✨

Examples:

use Sys::Time;
my $seed = (int)Sys::Time->time;
my $rand0 = Fn->rand(\$seed);
my $rand1 = Fn->rand(\$seed);

Exceptions:

  • The max number $max must be greater than 0. Otherwise an exception is thrown.

See also: If you want to omit $seed, you can use Sys#rand method. 🫢

πŸ¦‹ repeat

static method repeat : string ($string : string, $count : int);

Concatenates $string the number of times specified in $count and returns it.

Exceptions:

  • The $string must be defined. Otherwise an exception is thrown.
  • The repeat count $count count be a non-negative integer. Otherwise an exception is thrown.
The source says β€œcount count be” and honestly? We’re keeping the vibe. πŸ’€

Examples:

# "abcabcabc"
my $repeat_string = Fn->repeat("abc", 3);

See also: See Array#repeat method about repeating an array. 🌈

πŸ’œ replace_chars

static method replace_chars : void ($string : mutable string, $from_ch : int, $to_ch : int);

Replaces all characters specified by the second argument in $string with the characters specified by the third argument.

Exceptions:

  • $string must be defined. Otherwise an exception is thrown.

Character swap, but make it mutable. πŸ’…

🌸 rindex

static method rindex : int ($string : string, $substring : string, $end : int = -1, $begin : int = 0);

Searches for $substring in the range of $string from $begin to $end.

The search is performed from the end of the range of $string.

If $substring is found, returns the found offset. Otherwise, returns -1.

If $end is less than 0, $end is set to the length of $string minus 1.

Exceptions:

  • $string must be defined. Otherwise an exception is thrown.
  • $substring must be defined. Otherwise an exception is thrown.
  • $begin must be greater than or equal to 0. Otherwise an exception is thrown.
  • $end must be less than the length of $string.

Backwards search, forward slay. πŸ”₯

🧚 sizeof_native_int

static method sizeof_native_int : int ();

Returns the native "int" size. This is the same value as sizeof(int) in the C language. C-coded realness. ✨

πŸ“ sizeof_native_pointer

static method sizeof_native_pointer : int ();

Returns the native pointer size. This is the same value as sizeof(void*) in the C language. Pointer girlies get their own size check. 🫢

⭐ shorten

static method shorten : void ($string : mutable string, $length : int32_t);

Shortens $string to $length specified by the argument using "shorten" in SPVM::Document::NativeAPI.

If the length specified by the argument is greater than or equal to the length of the string, nothing is performed.

Exceptions:

  • $string must be defined.
  • $length must be greater than or equal to 0. Otherwise an exception is thrown.

Shorten done, no extra drama. πŸ’…

🌈 shorten_null_char

static method shorten_null_char : void ($string : mutable string);

Shortens $string just before the first null character "\0".

If null characters is not found, do nothing.

Exceptions:

  • $string must be defined. Otherwise an exception is thrown.

Example:

my $message = (mutable string)copy "foo\0bar";

# "foo"
my $message_shoten = Fn->shorten_null_char($message);

Yes, $message_shoten is spelled like that in the source. Keeping it exactly. πŸ˜­πŸŽ€

πŸ¦‹ split

static method split : string[] ($separator : string, $string : string, $limit : int = -1);

If $limit is less than 0, split $string by the specific $separator and convert them to a string array and return it.

If $limit is greater than than 0, the limit becomes the length of the maximam separated elements.

Exceptions:

  • $separator must be defined. Otherwise an exception is thrown.
  • $string must be defined. Otherwise an exception is thrown.
  • $limit cannnot be 0. Otherwise an exception is thrown.

than than and maximam are also source details. We respect the lore. πŸ’€βœ¨

🌸 substr

static method substr : string ($string : string, $offset : int, $length : int = -1, $replacement : string = undef);

Cuts a substring of $length from $offset of a string $string, and returns it.

If $length is ommited or $offset plus $length is less than or equal to the length of $string, $length is set to the length of $string minus $offset.

If the length is less than 0, the length to the end of the string is calculated from the length of $string and $offset.

Replacement:

If $replacement is given, $string is set to a string that is the replacement string $replacement of $string from $offset to $length.

Exceptions:

  • $string must be defined. Otherwise an exception is thrown.
  • $string must be a string. Otherwise an exception is thrown.
  • $offset must be greater than or equal to 0. Otherwise an exception is thrown.
  • The offset $offset must be less than or equal to the length of the string $string. Otherwise an exception is thrown.

Substring with optional replacement, highkey useful. πŸ”₯

πŸ’œ to_code_points

static method to_code_points : int[] ($string : string)

Converts $string to the Unicode code points, and returns it.

Exceptions:

  • $string must be defined. Otherwise an exception is thrown.

Code points acquired, bestie. Unicode era. βœ¨πŸ‘‘

  • $string contains an invalid Unicode code point. Otherwise an exception is thrown.

πŸ’– to_double πŸ’–

static method to_double : double ($string : string);

Converts $string to the double value using strtod in the C language. Slay.

Exceptions β€” vibe check time 🚨

  • $string must be defined. Otherwise an exception is thrown.
  • $string must be the string that can be parsed as a double number. Otherwise an exception is thrown.
  • $string must be a double number in $correct range. Otherwise an exception is thrown.

Example β€” literally copy-paste this ✨

my $string = "1.25";
my $num = Fn->to_double($string);

πŸ¦‹ to_float πŸ¦‹

static method to_float : float ($string : string);

Converts $string to the double value using strtof in the C language.

Exceptions β€” read these before you yell at your code 😭

  • $string must be defined. Otherwise an exception is thrown.
  • $string must be the string that can be parsed as a float number. Otherwise an exception is thrown.
  • $string must be a float number in $correct range. Otherwise an exception is thrown.

Example β€” chef’s kiss πŸŽ€

my $string = "1.25";
my $num = Fn->to_float($string);

πŸŽ€ to_int πŸŽ€

static method to_int : int ($string : string, $digit : int);

This is the alias for the following code using to_int_with_base:

my $ret = Fn->to_int_with_base($string, 10);

🌸 to_int_with_base 🌸

Converts $string to the int value with $digit using strtol in the C language.

Exceptions β€” the usual suspects πŸ’€

  • $string must be defined. Otherwise an exception is thrown.
  • $string must be the string that can be parsed as an int number. Otherwise an exception is thrown.
  • $string must be an int number in $correct range. Otherwise an exception is thrown.

Example β€” bestie tested, icon approved πŸ‘‘

my $string = "-2147483648";
my $num = Fn->to_int_with_base($string, 10);

πŸ’œ to_long πŸ’œ

static method to_long : long ($string : string);

The alias for the following code using to_long_with_base:

my $ret = Fn->to_long_with_base($string, 10);

πŸ”₯ to_long_with_base πŸ”₯

static method to_long_with_base : long ($string : string, $digit : int);

Converts $string to the long value with $digit using strtoll in the C language.

Exceptions β€” no cap, read them πŸ“’

  • $string must be defined. Otherwise an exception is thrown.
  • $digit must be one of 2, 8, 10, or 16. Otherwise an exception is thrown.
  • $string must be the string that can be parsed as a long number. Otherwise an exception is thrown.
  • $string must be a long number in $correct range. Otherwise an exception is thrown.

Example β€” big number energy 🌈

my $string = "-9223372036854775808";
my $num = Fn->to_long_with_base($string, 10);

🌈 to_lower 🌈

static method to_lower : int ($code_point : int);

If $code_point is the ASCII uppercase character "A-Z", it is converted to the corresponding ASCII lowercase character "a-z".

If $code_point is not an ASCII uppercase character, return itself.

πŸ¦‹ to_upper πŸ¦‹

static method to_upper : int ($code_point : int);

If $code_point is the ASCII lowercase character "a-z", it is converted to the corresponding ASCII uppercase character "A-Z".

If $code_point is not an ASCII lowercase character, return itself.

πŸŽ€ to_utf8_chars πŸŽ€

static method to_utf8_chars : string[] ($string : string);

Converts $string to UTF-8 characters, and returns it. Obsessed with this one.

Exceptions β€” don’t skip these, bestie 🫢

  • $string must be defined. Otherwise an exception is thrown.
  • $string contains an invalid Unicode code point. Otherwise an exception is thrown.

Example β€” the cutest little array ✨

my $string = "あいうa";

# ["あ", "い", "う", "a"]
my $utf8_chars = Fn->to_utf8_chars($string);

πŸ’… tr πŸ’…

static method tr : string ($string : string, $pattern : string, $replace : string)

Replaced the range of $pattern with the range of $replace in a $string and returns a replaced string.

The range must be the format "a-z" or "a". If the format is "a", it is converted to "a-a".

Range format examples β€” literally the vibes πŸŽ€

# The range format examples
"a-z"
"0-9"
"a"
"5"
"０-οΌ™"
"あ-γ‚“"

Exceptions β€” yes there are a lot, we’re thriving πŸ’€

  • $string must be defined. Otherwise an exception is thrown.
  • $pattern must be defined. Otherwise an exception is thrown.
  • $replace must be defined. Otherwise an exception is thrown.
  • If $string contains an invalid Unicode code point, an exception is thrown.
  • The range format of the (pattern|replace) cannnot be contain an invalid Unicode code point. If so, an exception is thrown. If so, an exception is thrown.
  • The second character of the range format of the (pattern|replace) must be "-". Otherwise an exception is thrown.
  • The range format of the (pattern|replace) must be 1 or 3 characters. Otherwise an exception is thrown.
  • The exceptions of the get_code_point method can be thrown.

Examples β€” two for the price of one 🫢

{
  my $string = "οΌοΌ‘οΌ’οΌ“οΌ”οΌ•οΌ–οΌ—οΌ˜οΌ™";
  my $pattern = "０-οΌ™";
  my $replace = "0-9";

  # "0123456789"
  my $ret = Fn->tr($string, $pattern, $replace);
}

{
  my $string = "abcd";
  my $pattern = "a-c";
  my $replace = "x-z";

  # "xyzd"
  my $ret = Fn->tr($string, $pattern, $replace);
}

🧚 trim 🧚

static method trim : string ($string : string);

Removes the right and left spaces of $string and return it.

The removed spaces is the same as the spaces is_space method returns 1.

Exceptions β€” just one, you got this πŸ’–

  • $string must be defined. Otherwise an exception is thrown.

⭐ uc ⭐

static method uc : string ($string : string);

Converts the ASCII lowercase characters "a-z" in $string to the corresponding ASCII uppercase characters "A-Z". And return it.

Exceptions β€” one more, slay πŸŽ€

  • $string must be defined. Otherwise an exception is thrown.

🌸 ucfirst 🌸

static method ucfirst : string ($string : string);

If the first character of $string is an ASCII lowercase characters "a-z", it is converted to the corresponding ASCII uppercase character "A-Z". And return the converted string.

Exceptions β€” same energy πŸ’…

  • $string must be defined. Otherwise an exception is thrown.

πŸ¦‹ utf8_length πŸ¦‹

static method utf8_length : int ($string : string)

Gets the length as a UTF-8 string from $string, and returns it.

Exceptions β€” protect your code, bestie 🫢

  • $string must be defined. Otherwise an exception is thrown.
  • If $string contains an invalid Unicode code point, an exception is thrown.

Example β€” three characters, iconic ✨

# 3
my $utf8_length = Fn->utf8_length("あいう");

πŸ’– utf8_substr πŸ’–

static method utf8_substr : string ($string : string, $utf8_offset : int, $utf8_length : int = -1);

Gets the substring from $string. The extracting range of the string is from $utf8_offset to the position proceeded by $utf8_length, and returns it.

If the length is less than 0, the length to the end of the string is calculated from the length of $string and $utf8_offset.

Exceptions β€” read the room 🚨

  • $string must be defined. Otherwise an exception is thrown.
  • If $string contains an invalid Unicode code point, an exception is thrown.
  • $utf8_offset + $utf8_length must be less than or equal to the UTF-8 length of $string. Otherwise an exception is thrown.

Example β€” substring but make it cute πŸŽ€

# "γ„γˆ"
my $utf8_substr = Fn->utf8_substr("γ‚γ„γ†γˆ", 1, 2);

πŸ”₯ merge_options πŸ”₯

static method merge_options : object[] ($options1 : object[], $options2 : object[]);

Creates a new any object array merging $options1 and $options2, and returns it.

If $options1 is not defined, $options1 is set to an empty any object array.

If $options2 is not defined, $options2 is set to an empty any object array.

Exceptions β€” even numbers only, periodt πŸ’…

  • The length of $options1 must be an even number. Otherwise an exception is thrown.
  • The length of $options2 must be an even number. Otherwise an exception is thrown.
  • Exceptions thrown by the merge_object in the Array class could be thrown.

Example β€” merge and slay 🌈

my $merged_options = Fn->merge_options({foo => 1, bar => 2}, {baz => 5});

πŸ’œ object_to_int πŸ’œ

static method object_to_int : int ($object : object);

Converts the address of $object to a value of int type, and returns it.

πŸŽ€ get_spvm_version_string πŸŽ€

static method get_spvm_version_string : string ();

Returns the version string of the SPVM language. Iconic.

🌈 get_spvm_version_number 🌈

static method get_spvm_version_number : double ();

Returns the version number of the SPVM language.

⭐ get_version_string ⭐

static method get_version_string : string ($basic_type_name : string);

Returns the version string of the class $basic_type_name.

🌸 get_version_number 🌸

static method get_version_number : double ($basic_type_name : string);

Returns the version number of the class $basic_type_name.

Exceptions β€” yes, two of them 🫢

  • $basic_type_name must be defined. Otherwise an exception is thrown.
  • The class specified by $basic_type_name must be loaded. Otherwise an exception is thrown.

🧚 defer 🧚

static method defer : Scope::Guard ($callback : Callback);

Calls Scope::Guard#new and return its return value.

πŸ’… get_memory_blocks_count πŸ’…

static method get_memory_blocks_count : int ();

Gets the count of the memory blocks allocated by the new_memory_block native API.

πŸ¦‹ to_address πŸ¦‹

static method to_address : string ($object : object);

Gets the address of an object $object as a string.

πŸ”₯ check_option_names πŸ”₯

static method check_option_names : void ($options : object[], $available_option_names : string[]);

Checks if the options $options that contain name-value pairs has the available option names $available_option_names.

If $options is undef, nothing is done.

If the check is ok, nothing is done. Otherwise the following exception is thrown:

The "%s" option is not available.

%s is an option name.

Example β€” check those names, bestie βœ…

my $options = {foo => 1, bar => 2};

my $available_option_names = ["foo", "bar", "baz"];

Fn->check_option_names($options, $available_option_names);

πŸ’œ get_basic_type_id πŸ’œ

static method get_basic_type_id : int ($basic_type_name : string);

Gets the basic type ID of the basic type $basic_type_name.

Exceptions β€” don’t get caught lacking 😭

  • $basic_type_name must be defined. Otherwise an exception is thrown.
  • If the basic type is not found, an exception is thrown.

πŸ’– memset_char πŸ’–

static method memset_char : void ($string : mutable string, $char : int, $offset : int = 0, $length : int = -1);

Set the range of the characters of the string $string to the character $char.

$char is an ASCII code.

The range of the characters of $string is from the offset $offset to the position proceeded by the length $length.

If $length is less than 0, the length to the end of the string is calculated from the length of $string and $offset.

Exceptions β€” boundaries matter 🚨

  • $string must be defined.
  • $offset must be greater than or equal to 0. Otherwise an exception is thrown.
  • $offset + $length must be less than or equal to the length of $string. Otherwise an exception is thrown.

🌈 or 🌈

static method or : object ($left : object, $right : object);

That’s the entire entry, bestie β€” just the signature, no extra lore. πŸ’…

If $left is a true value, returns $left. Otherwise, returns $right;

if 🌸

static method if : object ($condition : int, $left : object, $right : object);

If $condition is a true value, returns $left. Otherwise, returns $right;

grep πŸ’–

static method grep : object[] ($callback : Callback::Grep, $array : object[]);

Returns a new array containing only the elements of the array $array for which the callback $callback returned a true value.

Exceptions:

  • The array $array must be defined. Otherwise, an exception is thrown.
  • The callback $callback must be defined. Otherwise, an exception is thrown.

grep_byte πŸŽ€

static method grep_byte : byte[] ($callback : Callback::Grep::Byte, $array : byte[]);

Returns a new array containing only the elements of the array $array for which the callback $callback returned a true value.

Exceptions:

  • The array $array must be defined. Otherwise, an exception is thrown.
  • The callback $callback must be defined. Otherwise, an exception is thrown.

grep_short πŸ¦‹

static method grep_short : short[] ($callback : Callback::Grep::Short, $array : short[]);

Returns a new array containing only the elements of the array $array for which the callback $callback returned a true value.

Exceptions:

  • The array $array must be defined. Otherwise, an exception is thrown.
  • The callback $callback must be defined. Otherwise, an exception is thrown.

grep_int ✨

static method grep_int : int[] ($callback : Callback::Grep::Int, $array : int[]);

Returns a new array containing only the elements of the array $array for which the callback $callback returned a true value.

Exceptions:

  • The array $array must be defined. Otherwise, an exception is thrown.
  • The callback $callback must be defined. Otherwise, an exception is thrown.

grep_long πŸ’œ

static method grep : long[] ($callback : Callback::Grep::Long, $array : long[]);

Returns a new array containing only the elements of the array $array for which the callback $callback returned a true value.

Bestie, the signature in the source literally says grep here, not grep_long β€” keep it exactly like that. No "fixing" it, okay? πŸ’…

Exceptions:

  • The array $array must be defined. Otherwise, an exception is thrown.
  • The callback $callback must be defined. Otherwise, an exception is thrown.

grep_float 🌈

static method grep_float : float[] ($callback : Callback::Grep::Float, $array : float[]);

Returns a new array containing only the elements of the array $array for which the callback $callback returned a true value.

Exceptions:

  • The array $array must be defined. Otherwise, an exception is thrown.
  • The callback $callback must be defined. Otherwise, an exception is thrown.

grep_double ⭐

static method grep_double : double[] ($callback : Callback::Grep::Double, $array : double[]);

Returns a new array containing only the elements of the array $array for which the callback $callback returned a true value.

Exceptions:

  • The array $array must be defined. Otherwise, an exception is thrown.
  • The callback $callback must be defined. Otherwise, an exception is thrown.

map πŸ’«

static method map : object[] ($callback : Callback::Map, $array : object[]);

Returns a new array with each element of the array $array processed in the callback $callback.

Exceptions:

  • The array $array must be defined. Otherwise, an exception is thrown.
  • The callback $callback must be defined. Otherwise, an exception is thrown.

map_expand 🫢

static method map_expand : object[] ($callback : Callback::MapExpand, $array : object[]);

Returns a new array with each element of the array $array processed in the callback $callback which returns multiple values.

Exceptions:

  • The array $array must be defined. Otherwise, an exception is thrown.
  • The callback $callback must be defined. Otherwise, an exception is thrown.

get_compile_type_name 🧚

static method get_compile_type_name : string ($basic_type_name : string, $type_dimension : int, $type_flag : int);

Create a compile-time type name given the basic type name $basic_type_name, the type dimension $type_dimension, the type flag $type_flag, and returns it.

If $type_flag & 1 is true, the type is a reference type.

If $type_flag & 2 is true, the type is one that have a mutable qualifier.

Examples:

# int[][]
my $compile_type_name = Fn->get_compile_type_name("int", 2, 0);

# int*
my $compile_type_name = Fn->get_compile_type_name("int", 0, 1);

Exceptions:

  • The basic type name $basic_type_name must be defined. Otherwise, an exception is thrown.
  • The type dimension $type_dimension must be grether than or equal to 0 and less than or equal to 255. Otherwise, an exception is thrown.

is_any_numeric_array πŸ”₯

static method is_any_numeric_array : int ($object : object);

If the object $object is defined and the type of $object is a numeric array type or a multi-numeric array type, returns 1, otherwise returns 0.

An any numeric array means an array of a numeric array type or a multi-numeric array type.

array_length πŸ“

static method array_length : int ($array : object);

Returns the array length of the array $array.

Exceptions:

  • The array $array must be defined. Otherwise, an exception is thrown.
  • The type of the array $array must be an array type. Otherwise, an exception is thrown.

get_elem_size πŸŽ€

static method get_elem_size : int ($array : object);

Returns the element byte size of the array $array.

Exceptions:

  • The array $array must be defined. Otherwise, an exception is thrown.
  • The type of the array $array must be an array type. Otherwise, an exception is thrown.

get_elem_type_name πŸ‘‘

static method get_elem_type_name : string ($array : object);

Returns the element type name of the array $array.

Implementation:

my $type_name = type_name $array;
my $ret = Fn->substr($type_name, 0, length $type_name - 2);

Note that this is not the real element type name of each element. It is merely the type name of the array, but without the trailing [].

Exceptions:

  • The array $array must be defined. Otherwise, an exception is thrown.
  • The type of the array $array must be an array type. Otherwise, an exception is thrown.
static method print_stderr : void ($string : string);

Prints the string $string to SPVM's standard error.

If $string is undef, this method produces no output.

say_stderr πŸŒ™

static method say_stderr : void ($string : string);

Prints the string $string with a new line "\n" to SPVM's standard error.

If $string is undef, this method prints "\n".

memcmp πŸ’€

static method memcmp : void ($data1 : object, $data1_offset : int, $data2 : object, $data2_offset : int, $length : int);

Compares the data $data1 from index $dest_offset with the data $data2 from index $data2_offset to the length $length using memcmp C function, and returns the result.

Unit of $data1_offset, $data2_offset, and $length is bytes.

The signature says : void and the description says it returns the result β€” both of those details are literally in the source, so keep both. No cap. πŸ™ˆ

Exceptions:

  • $data1 must be defined. Otherwise an exception is thrown.
  • The type of $data1 must be the string type, the numeric array type, or the multi-numeric array type. Otherwise an exception is thrown.
  • $data2 must be defined. Otherwise an exception is thrown.
  • The type of $data2 must be the string type, the numeric array type, or the multi-numeric array type. Otherwise an exception is thrown.
  • $data1 must not be a read-only string. Otherwise an exception is thrown.
  • $length must be greater than or equal to 0. Otherwise an exception is thrown.
  • $data1_offset + $length must be less than or equal to the length of $data1. Otherwise an exception is thrown.
  • $data2_offset + $length must be less than or equal to the length of $data2. Otherwise an exception is thrown.

reverse_inplace πŸ”„

static method reverse_inplace : void ($array_or_string : object);

Reverses the elements in the array $array_or_string or the characters in the string $array_or_string in-place.

Exceptions:

  • $array_or_string must be defined. Otherwise an exception is thrown.
  • The type of $array_or_string must be an array type or string type. Otherwise an exception is thrown.
  • The string $array_or_string must not be read-only. Otherwise an exception is thrown.

is_string_array 🌸

static method is_string_array : int ($object : object)

If $object is defined and the type of $object is string array type string[], returns 1, otherwise returns 0.

length πŸ“

static method length : int ($array_or_string : object);

Returns the array length of $array_or_string if the type of $array_or_string is an array type.

Returns the string length of $array_or_string if the type of $array_or_string is string type.

Exceptions:

  • $array_or_string must be defined. Otherwise an exception is thrown.
  • The type of $array_or_string must be an array type or string type. Otherwise an exception is thrown.

get_elem_or_char_size 🧸

static method get_elem_or_char_size : int ($array_or_string : object);

Returns the element byte size of the array $array if the type of $array_or_string is an array type.

Returns 1, the byte size of byte type if the type of $array_or_string is string type.

Exceptions:

  • The array $array_or_string must be defined. Otherwise, an exception is thrown.
  • The type of the array $array_or_string must be an array type. Otherwise, an exception is thrown.

copy πŸ“‹

static method copy : object ($array_or_string : object, $shallow : int = 0);

Copies $array_or_string and returns it.

Implementation:

  • If $array_or_string is undef, returns undef.
  • If the type of $array_or_string is an string array type and $shallow is a false value, the copy is performed by Array#copy_string method.
  • If the type of $array_or_string is an string array type and $shallow is a true value, the copy is performed by Array#copy_string_address method.
  • If the type of $array_or_string is an object array type and $shallow is a false value, the copy is performed by Array#copy_object method given Cloner#default_cloner method.
  • If the type of $array_or_string is an object array type and $shallow is a true value, the copy is performed by Array#copy_object_address method.
  • If the type of $array_or_string is a numeric array type or a multi-numeric array type, the copy is performed by Array#copy_any_numeric method.
  • If the type of $array_or_string is string type, the copy is performed by copy operator.

Exceptions:

  • The type of $array_or_string must be an array type or string type.

reverse πŸͺž

static method reverse : object ($array_or_string : object);

Returns a new array that reverses the elements in the array $array_or_string or the characters in the string $array_or_string.

This method calls copy method and reverse_inplace method to create a new array and reverses elements.

Exceptions:

  • Exceptions thrown by copy method and reverse_inplace method could be thrown.

βœ‚οΈ slice

static method slice : object ($array : object, $offset : int, $length :int);

Okay so this one literally just slices your array πŸ’… β€” it takes $array, cuts from $offset out to $length, and hands you back the piece. Iconic.

Just so we're clear: the type of $array has to be an object array type, a numeric array type, or a multi-numeric array type. No exceptions on that vibe check (well, actually, there are exceptions β€” see below 😭).

Under the hood this method calls Array#memcpy_object method or "memcpy" method to slice $array.

Exceptions:

  • The array $array must be defined. Otherwise an exception is thrown.
  • The type of the array $array must be an object array type, a numeric array type or a multi-numeric array type. Otherwise an exception is thrown.
  • Exceptions thrown by Array#memcpy_object method or "memcpy" method could be thrown.

🧚 system_is_little_endian

static method system_is_little_endian ();

Returns 1 if your system is little-endian, otherwise returns 0. That's it, that's the whole method. Short queen behavior πŸ‘‘.

🌸 sprintf

static method sprintf : string ($format : string, $args : object...);

Calls Format#sprintf method and returns its return value. Classic delegation, no notes ✨.

Exceptions:

  • Exceptions thrown by thrown Format#sprintf method could be thrown.

Examples:

my $ret = Fn->sprintf("%s %d", "abc", 2);

πŸ”₯ sort_asc

static method sort_asc : object ($array : object);

Copies the array $array using "copy" method, sorts the copied array into ascendant order, and returns it. Note the "copied" β€” the original stays untouched, she's respectful like that 🫢.

The type of $array must be a numeric array type.

This method calls a corresponding method in Sort class.

Exceptions:

  • The array $array must be defined. Otherwise an exception is thrown.
  • The type of the array $array must be a numeric array type. Otherwise an exception is thrown.

πŸ’€ sort_desc

static method sort_desc : object ($array : object);

Same energy as sort_asc, but make it descendant order. Copies $array using "copy" method, sorts the copy descending, returns it πŸ”₯.

The type of $array must be a numeric array type.

This method calls a corresponding method in Sort class.

Exceptions:

  • The array $array must be defined. Otherwise an exception is thrown.
  • The type of the array $array must be a numeric array type. Otherwise an exception is thrown.

πŸŽ€ sort

static method sort : object[] ($array : object[], $comparator : Comparator);

Copies the array $array using "copy" method, sorts the copy by whatever order the comparator $comparator says, and returns it. You're basically the director here, the comparator is the main character 🎬.

This method calls Sort#sort_object method to sort the copied array.

Exceptions:

  • Exceptions thrown by thrown Sort#sort_object method could be thrown.

πŸ¦‹ change_endian

static method change_endian : void ($binary : mutable string, $size : int, $offset : int = 0);

The byte order of the first $size bytes of the binary data $binary at the offset $offset are reversed in-place. In-place, bestie β€” the original binary gets rearranged, no copy, no takebacks πŸ™ˆ.

Exceptions:

  • The binary data $binary must be defined. Otherwise an exception is thrown.
  • The byte size $size must be greater than 0. Otherwise an exception is thrown.
  • The offset $offset must be greater than or equal to 0. Otherwise an exception is thrown.
  • The byte size $size must be less than or equal to the offset $offset plus the length of the binary data $binary.

🌈 big_endian_to_system_endian

static method big_endian_to_system_endian : void ($binary : mutable string, $size : int, $offset : int = 0);

The byte order of the first $size bytes of the binary data $binary at the offset $offset are changed from big endian to system endian. Glow-up for your bytes ✨.

This method calls "change_endian" method to change endian.

Exceptions:

  • Exceptions thrown by "change_endian" method could be thrown.

πŸ“ system_endian_to_big_endian

static method system_endian_to_big_endian : void ($binary : mutable string, $size : int, $offset : int = 0);

The byte order of the first $size bytes of the binary data $binary at the offset $offset are changed from system endian to big endian. Going the other direction this time, we love a reversible queen πŸ’….

This method calls "change_endian" method to change endian.

Exceptions:

  • Exceptions thrown by "change_endian" method could be thrown.

πŸ’œ little_endian_to_system_endian

static method little_endian_to_system_endian : void ($binary : mutable string, $size : int, $offset : int = 0);

The byte order of the first $size bytes of the binary data $binary at the offset $offset are changed from little endian to system endian. Same deal, different endian 🧚.

This method calls "change_endian" method to change endian.

Exceptions:

  • Exceptions thrown by "change_endian" method could be thrown.

🌸 system_endian_to_little_endian

static method system_endian_to_little_endian : void ($binary : mutable string, $size : int, $offset : int = 0);

The byte order of the first $size bytes of the binary data $binary at the offset $offset are changed from system endian to little endian. The last of the four endian besties, we stan a complete set 🫢.

This method calls "change_endian" method to change endian.

Exceptions:

  • Exceptions thrown by "change_endian" method could be thrown.

🎁 pack

static method pack : string ($template : string, $objects : object...);

Converts the objects $objects into binary data according to the template $template, and returns it. It's giving "objects go in, bytes come out" 😌.

This method just creates a Packer object, calls Packer#pack method, and returns its return value.

Examples:

my $binary = Fn->pack("l", 3);

🧰 unpack

static method unpack : object[] ($template : string, $binary : string);

Converts the binary data $binary into the objects $objects according to the template $template, and returns it. Reverse of pack, obviously, iykyk.

This method just creates a Packer object, calls Packer#unpack method, and returns its return value.

πŸ™ˆ no_free

static method no_free : int ($object : object);

Calls no_free native API given $object, and returns its return value.

Exceptions:

  • The object $object must be defined. Otherwise an exception is thrown.

πŸ”’ set_no_free

static method set_no_free : void ($object : object, $no_free : int);

Calls set_no_free native API given $object, $no_free.

Exceptions:

  • The object $object must be defined. Otherwise an exception is thrown.

πŸ“ get_pointer

static method get_pointer : Address ($object : object);

Creates a new Address object, sets its pointer value to the pointer value of the object $object, and returns that new object. Fresh Address, just dropped ✨.

Exceptions:

  • The object $object must be defined. Otherwise an exception is thrown.

πŸͺ„ set_pointer

static method set_pointer : void ($object : object, $address : Address);

Sets the pointer value of the object $object to the pointer value of the address $address. Matching pointers like matching outfits πŸ’….

Exceptions:

  • The object $object must be defined. Otherwise an exception is thrown.
  • The address $address must be defined. Otherwise an exception is thrown.

πŸ•³οΈ has_null_pointer

static method has_null_pointer : int ($object : object);

Returns 1 if the pointer value of the object $object is NULL, otherwise returns 0. Empty-pointer check, very demure.

Exceptions:

  • The object $object must be defined. Otherwise an exception is thrown.

πŸͺž eq_pointer

static method eq_pointer : int ($object1 : object, $object2 : object);

Returns 1 if the pointer value of the object $object1 equals the pointer value of the object $object2, otherwise returns 0. Twin check πŸ”₯.

Exceptions:

  • The object $object1 must be defined. Otherwise an exception is thrown.
  • The object $object2 must be defined. Otherwise an exception is thrown.

πŸ”’ pointer_to_string

static method pointer_to_string : string ($object : object);

Creates a new string containing the hex address of the pointer value of the object $object, and returns that new string. Hex address but make it a string, cute πŸŽ€.

Exceptions:

  • The object $object must be defined. Otherwise an exception is thrown.

πŸ” dump_object_internal

static method dump_object_internal : string ($object : object);

Calls dump_object_internal native API, and returns its return value. Peek inside the object, no cap πŸ‘€.

🌱 get_seed

static method get_seed : int ();

Calls get_seed native API, and returns its return value.

🌱 set_seed

static method set_seed : void ($seed : int);

Calls get_seed native API given $seed.

βœ… seed_initialized

static method seed_initialized : int ();

Calls seed_initialized native API, and returns its return value.

🏷️ get_basic_type_name_in_version_from

static method get_basic_type_name_in_version_from : basic_type_name ($basic_type_name : basic_type_name);

Returns the basic_type_name specified by version_from Statement of the class $basic_type_name. If it's not specified, returns undef. Not found? Not a problem, you get undef 🫢.

🧹 destroy_cache_class_vars

static method destroy_cache_class_vars : void ();

Sets all class variables of all classes that is a object type and "cache" class variable attribute is specified to undef. Mass cleanup, very satisfying 😌.

🧼 destroy_runtime_permanent_vars

method destroy_runtime_permanent_vars : void ();

Sets all runtime permanent variables to undef.

Currently this method calls "destroy_cache_class_vars" method and sets $@ to undef.

πŸ”’ range

static method range : int[] ($begin : int, $end : int);

Returns a new array of values counting (up by ones) from $begin to $end. Little staircase of integers, adorable ⭐.

Exceptions:

  • $end must be greater than or equal to $begin.

πŸ—‚οΈ to_hash

static method to_hash : Hash ($options : Hash|object[]);

Converts the options $options to a Hash object, and returns it. Glow-up from options to hash πŸ’….

  • If $options is "undef", returns an empty Hash object.
  • If $options is a Hash object, returns it.
  • If $options is an "object[]" object, it is converted to a Hash object, and returns it.

Exceptions:

  • If the type of the options $options must be Hash or object[], an exception is thrown.

πŸ†” get_basic_type_name_by_id

static method get_basic_type_name_by_id : string ($basic_type_id : int);

Gets the basic type name of the basic type ID $basic_type_id. Name from an ID, like a reverse lookup but make it classy πŸ‘‘.

Exceptions:

  • If the basic type specified by $basic_type_id is not found, an exception is thrown.

πŸͺœ get_current_basic_type_name

static method get_current_basic_type_name : string ($level : int = 0);

Returns the basic type name at the specified caller stack level $level.

Level 0 represents the currently executing method's basic type. Level 1 represents its caller's basic type, and so on. Climbing the stack, one frame at a time πŸ§—.

Exceptions:

  • If the specified $level is out of range of the caller stack, an exception is thrown.

πŸͺœ get_current_basic_type_name

static method get_current_basic_type_name : string ();

Returns the name of the basic type (class) that owns the method currently being executed. Yes, same name as the one above, that's just how it is πŸ™ˆ.

This method calls the get_current_method native API.

Exceptions:

  • If the caller stack is empty, an exception is thrown.

🏷️ get_current_method_abs_name

static method get_current_method_abs_name : string ($level : int = 0);

Returns the absolute name of the method at the specified caller stack level $level.

The absolute name is the basic type name and the method name joined with "#".

Level 0 represents the currently executing method. Level 1 represents its caller, and so on.

Exceptions:

If the $level you pass is, like, out of range of the caller stack? Yeah, an exception gets thrown. πŸ’€ So don't do that.

✨ Class Methods (the saga continues) ✨

build_exception_message

static method build_exception_message : string ($level : int = 0);

Okay so this one is genuinely iconic β€” it reconstructs the full exception message, stack trace and all, using the metadata that's already chilling in the runtime stack. Like it doesn't make stuff up, it just puts the receipts back together. 🧚

The $level argument tells it where to start the stack trace, relative to the current call. So for example, 0 starts from the caller of this method. Easy.

Fun fact: this method calls the build_exception_message native API. πŸ‘‘

And what does it give you back? A newly created string object. Fresh out of the oven. πŸŽ€

Examples:

eval {
  MyModule->do_something;
};

if ($@) {
  # Reconstruct the message with a stack trace
  my $full_message = Fn->build_exception_message;
  warn $full_message;
}

Look at that. Catch the error, rebuild the whole tea with a stack trace, and warn it out. Chef's kiss. πŸ’…

get_call_depth

static method get_call_depth : int ();

This one's simple and I love her for it: it returns the current call stack depth. That's it. That's the method. πŸ¦‹

The base depth is -1. And the moment the first method gets called, the depth becomes 0. So like, -1 is the pre-show, 0 is when the first method walks on stage. ✨

🌈 See Also

  • Types
  • Class Definition
  • Operators

Copyright (c) 2023 Yuki Kimoto

MIT License

okay bestie that's a wrap on SPVM::Fn πŸ’– This page came to you courtesy of perl v5.42.2, dated 2026-02-03 β€” go forth and call your functions with confidence, you absolute main character. 🌸🫢✨

πŸ“¦ where this page comes from