SPVM::D...ativeAPI(3)

💅 SPVM::D...ativeAPI(3) — Native APIs

User Contributed Perl Documentation — that's the header metadata, bestie. Now let's get into it.

🎀 Name

SPVM::Document::NativeAPI — Native APIs

🌸 Description

The native APIs in SPVM are the APIs written by the C language for SPVM operations.

These APIs are available in native classes. Slay.

🌈 Native APIs 💫

✨ runtime

void* runtime;

The runtime for this runtime environment.

Examples:

void* runtime = env->runtime;

---

🧚 api

SPVM_ENV_API* api;

Returns a SPVM_ENV_API object. This object has the following fields for other native APIs:

• SPVM_API_ALLOCATOR* allocator
• SPVM_API_STRING_BUFFER* string_buffer
• SPVM_API_COMPILER* compiler
• SPVM_API_CLASS_FILE* class_file
• SPVM_API_RUNTIME* runtime
• SPVM_API_BASIC_TYPE* basic_type
• SPVM_API_CLASS_VAR* class_var
• SPVM_API_FIELD* field
• SPVM_API_METHOD* method
• SPVM_API_ARG* arg
• SPVM_API_TYPE* type
• SPVM_API_INTERNAL* internal
• SPVM_API_MUTEX* mutex

Examples:

SPVM_API_BASIC_TYPE* api_basic_type = env->api->basic_type;

---

🛠️ new_env

SPVM_ENV* (*new_env)();

Creates a new runtime environment.

This native API should not be used unless special purposes are intended.

---

🧹 free_env

void (*free_env)(SPVM_ENV* env);

Frees the runtime environment env.

This native API should not be used unless special purposes are intended.

---

🚀 call_init_methods

int32_t (*call_init_methods)(SPVM_ENV* env, SPVM_VALUE* stack);

Calls the consolidated INIT method for each class.

All INIT blocks in a class are merged into a single INIT method at compile time. This native API calls these methods for all classes that have them.

If an exception is thrown, returns a non-zero value. Otherwise, returns 0.

This native API should not be used unless special purposes are intended.

---

🏷️ set_command_info_program_name

int32_t (*set_command_info_program_name)(SPVM_ENV* env, SPVM_VALUE* stack, void* obj_program_name);

Sets the program name obj_program_name to the CommandInfo#PROGRAM_NAME class variable.

If an exception is thrown, returns a non-zero value. Otherwise, returns 0.

This native API should not be used unless special purposes are intended.

---

🎬 call_end_methods

int32_t (*call_end_methods)(SPVM_ENV* env, SPVM_VALUE* stack);

Calls the consolidated END method for each class.

All END blocks in a class are merged into a single END method in reverse order (LIFO) at compile time. This native API calls these methods for all classes that have them.

If an exception is thrown in an END method, it is converted to a warning message and printed to stderr, and the execution continues for the remaining classes.

This method always returns 0 because all exceptions are caught internally.

This native API should not be used unless special purposes are intended.

---

📥 set_command_info_argv

int32_t (*set_command_info_argv)(SPVM_ENV* env, SPVM_VALUE* stack, void* obj_argv);

Sets the command line arguments obj_argv to the CommandInfo#ARGV class variable.

If an exception is thrown, returns a non-zero value. Otherwise, returns 0.

This native API should not be used unless special purposes are intended.

---

⏰ set_command_info_basetime

int32_t (*set_command_info_basetime)(SPVM_ENV* env, SPVM_VALUE* stack, int64_t base_time);

Sets the base time base_time to the CommandInfo#BASE_TIME class variable.

If an exception is thrown, returns a non-zero value. Otherwise, returns 0.

This native API should not be used unless special purposes are intended.

---

💥 destroy_class_vars

void (*destroy_class_vars)(SPVM_ENV* env, SPVM_VALUE* stack);

Sets all class variables of all classes that is a object type to undef.

This native API should not be used unless special purposes are intended.

---

📏 args_width

int32_t (*args_width)(SPVM_ENV* env, SPVM_VALUE* stack);

Returns the width of the arguments given by the caller.

Examples:

int32_t args_width = env->args_width(env, stack);

---

🔍 get_object_basic_type

void* (*get_object_basic_type)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);

Returns the basic type of the object object.

---

🔢 get_object_basic_type_id

int32_t (*get_object_basic_type_id)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);

Returns the basic type ID of the object object.

---

🏷️ get_object_basic_type_name

const char* (*get_object_basic_type_name)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);

Returns the basic type name of the object object.

---

📐 get_object_type_dimension

int32_t (*get_object_type_dimension)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);

Returns the type dimension of the object object.

---

🔎 get_basic_type

void* (*get_basic_type)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name);

Searches a basic type given the basic type name basic_type_name.

If it is found, returns it. Otherwise, returns NULL.

---

🧭 get_basic_type_by_name

void* (*get_basic_type_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, int32_t* error_id, const char* func_name, const char* file, int32_t line);

Searches a basic type given the basic type name basic_type_name.

If it is found, returns it. Otherwise, an exception is thrown.

The function name func_name, the file path file, and the line number line must be given for the exception stack trace.

If the basic type given by basic_type_name is not found, an exception is thrown.

If an exception is thrown, error_id is set to a non-zero value. Otherwise, it is set to 0.

---

🆔 get_basic_type_by_id

void* (*get_basic_type_by_id)(SPVM_ENV* env, SPVM_VALUE* stack, int32_t basic_type_id);

Searches a basic type given the basic type ID basic_type_id.

If it is found, returns it. Otherwise, returns NULL.

---

🔢 get_basic_type_id

int32_t (*get_basic_type_id)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name);

Searches a basic type given the basic type name basic_type_name.

If it is found, returns the basic type id of it. Otherwise, returns a negative value.

Examples:

int32_t basic_type_id = env->get_basic_type_id(env, stack, "Int");

---

🪪 get_basic_type_id_by_name

int32_t (*get_basic_type_id_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, int32_t* error_id, const char* func_name, const char* file, int32_t line);

Searches a basic type ID given the basic type name basic_type_name.

The function name func_name, the file path file, and the line number line must be given for the exception stack trace.

If the basic type given by basic_type_name is not found, an exception is thrown.

If an exception is thrown, error_id is set to a non-zero value. Otherwise, it is set to 0.

---

📦 get_class_var

void* (*get_class_var)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, const char* class_var_name);

Searches a class variable given the basic type name basic_type_name and the class variable name class_var_name.

If it is found, returns it. Otherwise, returns NULL.

Examples:

void* class_var = env->get_class_var(env, stack, "MyClass", "$VAR");

---

🧊 get_class_var_byte

int8_t (*get_class_var_byte)(SPVM_ENV* env, SPVM_VALUE* stack, void* class_var);

Returns the value of the class variable class_var interpreting its type is byte type.

---

🩳 get_class_var_short

int16_t (*get_class_var_short)(SPVM_ENV* env, SPVM_VALUE* stack, void* class_var);

Returns the value of the class variable class_var interpreting its type is short type.

---

🔢 get_class_var_int

int32_t (*get_class_var_int)(SPVM_ENV* env, SPVM_VALUE* stack, void* class_var);

Returns the value of the class variable class_var interpreting its type is int type.

---

🦒 get_class_var_long

int64_t (*get_class_var_long)(SPVM_ENV* env, SPVM_VALUE* stack, void* class_var);

Returns the value of the class variable class_var interpreting its type is long type.

---

🫧 get_class_var_float

float (*get_class_var_float)(SPVM_ENV* env, SPVM_VALUE* stack, void* class_var);

Returns the value of the class variable class_var interpreting its type is float type.

---

🧁 get_class_var_double

double (*get_class_var_double)(SPVM_ENV* env, SPVM_VALUE* stack, void* class_var);

Returns the value of the class variable class_var interpreting its type is double type.

---

🪩 get_class_var_object

void* (*get_class_var_object)(SPVM_ENV* env, SPVM_VALUE* stack, void* class_var);

Returns the value of the class variable class_var interpreting its type is an object type.

---

🧵 get_class_var_string

void* (*get_class_var_string)(SPVM_ENV* env, SPVM_VALUE* stack, void* class_var);

Returns the value of the class variable class_var interpreting its type is string type.

---

✍️ set_class_var_byte

void (*set_class_var_byte)(SPVM_ENV* env, SPVM_VALUE* stack, void* class_var, int8_t value);

Sets value to the class variable class_var interpreting its type is byte type.

---

✍️ set_class_var_short

void (*set_class_var_short)(SPVM_ENV* env, SPVM_VALUE* stack, void* class_var, int16_t value);

Sets value to the class variable class_var interpreting its type is short type.

---

✍️ set_class_var_int

void (*set_class_var_int)(SPVM_ENV* env, SPVM_VALUE* stack, void* class_var, int32_t value);

Sets value to the class variable class_var interpreting its type is int type.

---

✍️ set_class_var_long

void (*set_class_var_long)(SPVM_ENV* env, SPVM_VALUE* stack, void* class_var, int64_t value);

Sets value to the class variable class_var interpreting its type is long type.

---

✍️ set_class_var_float

void (*set_class_var_float)(SPVM_ENV* env, SPVM_VALUE* stack, void* class_var, float value);

Sets value to the class variable class_var interpreting its type is float type.

---

✍️ set_class_var_double

void (*set_class_var_double)(SPVM_ENV* env, SPVM_VALUE* stack, void* class_var, double value);

Sets value to the class variable class_var interpreting its type is double type.

---

✍️ set_class_var_object

void (*set_class_var_object)(SPVM_ENV* env, SPVM_VALUE* stack, void* class_var, void* value);

Sets value to the class variable class_var interpreting its type is an object type.

---

✍️ set_class_var_string

void (*set_class_var_string)(SPVM_ENV* env, SPVM_VALUE* stack, void* class_var, void* value);

Sets value to the class variable class_var interpreting its type is string type.

---

🪞 get_class_var_object_ref

void** (*get_class_var_object_ref)(SPVM_ENV* env, SPVM_VALUE* stack, void* class_var);

Returns the address where the value of the class variable class_var is stored.

---

🧊 get_class_var_byte_by_name

int8_t (*get_class_var_byte_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, const char* class_var_name, int32_t* error_id, const char* func_name, const char* file, int32_t line);

okay so this one gets the value of the class variable you point at with the basic type name basic_type_name and the class variable name class_var_name, and then it hands that value right back to you. 🫶

The type of the field has to be "byte" type, no exceptions bestie.

The function name func_name, the file path file, and the line number line are all needed for the exception stack trace (yes, all three, they're doing the emotional labour of telling you where stuff blew up 💅).

If this function succeeds, error_id is set to 0. Slay.

Exceptions (the not-so-slaying part 😭):

• If basic_type_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If class_var_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If the class variable type is invalid, an exception is set and error_id is set to the basic type id of Error class.

Examples:

int32_t error_id = 0;
int8_t value = env->get_class_var_byte_by_name(env, stack, "TestCase::NativeAPI", "$BYTE_VALUE", &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

---

🌸 get_class_var_short_by_name 🌸

"int16_t (*get_class_var_short_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, const char* class_var_name, int32_t* error_id, const char* func_name, const char* file, int32_t line);"

Gets the value of the class variable specified by the basic type name basic_type_name and the class variable name class_var_name, and returns the value casting to "short" type. ✨

The type of the field must be "short" type or smaller numeric type — so like, it can be smol, but not bigger, iykyk.

The function name func_name, the file path file, and the line number line are needed for the exception stack trace.

If this function succeeds, error_id is set to 0.

Exceptions:

• If basic_type_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If class_var_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If the class variable type is invalid, an exception is set and error_id is set to the basic type id of Error class.

Examples:

int32_t error_id = 0;
int16_t value = env->get_class_var_short_by_name(env, stack, "TestCase::NativeAPI", "$SHORT_VALUE", &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

---

💜 get_class_var_int_by_name 💜

"int32_t (*get_class_var_int_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, const char* class_var_name, int32_t* error_id, const char* func_name, const char* file, int32_t line);"

Gets the value of the class variable specified by the basic type name basic_type_name and the class variable name class_var_name, and returns the value casting to "int" type. 🔥

The type of the field must be "int" type or smaller numeric type.

The function name func_name, the file path file, and the line number line are needed for the exception stack trace.

If this function succeeds, error_id is set to 0.

Exceptions:

• If basic_type_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If class_var_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If the class variable type is invalid, an exception is set and error_id is set to the basic type id of Error class.

Examples:

int32_t error_id = 0;
int8_t value = env->get_class_var_int_by_name(env, stack, "TestCase::NativeAPI", "$BYTE_VALUE", &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

ngl bestie, that example is written exactly like the original says — int8_t value holding a call to get_class_var_int_by_name. Type it exactly like that, don't go "fixing" it, ok? 😭

---

🦋 get_class_var_long_by_name 🦋

"int64_t (*get_class_var_long_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, const char* class_var_name, int32_t* error_id, const char* func_name, const char* file, int32_t line);"

Gets the value of the class variable specified by the basic type name basic_type_name and the class variable name class_var_name, and returns the value casting to "long" type. 👑

The type of the field must be "long" type or smaller numeric type.

The function name func_name, the file path file, and the line number line are needed for the exception stack trace.

If this function succeeds, error_id is set to 0.

Exceptions:

• If basic_type_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If class_var_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If the class variable type is invalid, an exception is set and error_id is set to the basic type id of Error class.

Examples:

int32_t error_id = 0;
int64_t value = env->get_class_var_long_by_name(env, stack, "TestCase::NativeAPI", "$LONG_VALUE", &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

---

🎀 get_class_var_float_by_name 🎀

"float (*get_class_var_float_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, const char* class_var_name, int32_t* error_id, const char* func_name, const char* file, int32_t line);"

Gets the value of the class variable specified by the basic type name basic_type_name and the class variable name class_var_name, and returns the value casting to "float" type. 🌸

The type of the field must be "float" type or smaller numeric type.

The function name func_name, the file path file, and the line number line are needed for the exception stack trace.

If this function succeeds, error_id is set to 0.

Exceptions:

• If basic_type_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If class_var_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If the class variable type is invalid, an exception is set and error_id is set to the basic type id of Error class.

Examples:

int32_t error_id = 0;
float value = env->get_class_var_float_by_name(env, stack, "TestCase::NativeAPI", "$FLOAT_VALUE", &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

---

⭐ get_class_var_double_by_name ⭐

"double (*get_class_var_double_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, const char* class_var_name, int32_t* error_id, const char* func_name, const char* file, int32_t line);"

Gets the value of the class variable specified by the basic type name basic_type_name and the class variable name class_var_name, and returns the value casting to "double" type. 💖

The type of the field must be "double" type or smaller numeric type.

The function name func_name, the file path file, and the line number line are needed for the exception stack trace.

If this function succeeds, error_id is set to 0.

Exceptions:

• If basic_type_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If class_var_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If the class variable type is invalid, an exception is set and error_id is set to the basic type id of Error class.

Examples:

int32_t error_id = 0;
double value = env->get_class_var_double_by_name(env, stack, "TestCase::NativeAPI", "$DOUBLE_VALUE", &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

---

🌈 get_class_var_object_by_name 🌈

"void* (*get_class_var_object_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, const char* class_var_name, int32_t* error_id, const char* func_name, const char* file, int32_t line);"

Gets the value of the class variable specified by the basic type name basic_type_name and the class variable name class_var_name, and returns the value. It's giving object energy. 🦋

The type of the field must be an object type.

The function name func_name, the file path file, and the line number line are needed for the exception stack trace.

If this function succeeds, error_id is set to 0.

Exceptions:

• If basic_type_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If class_var_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If the class variable type is invalid, an exception is set and error_id is set to the basic type id of Error class.

Examples:

int32_t error_id = 0;
void* value = env->get_class_var_object_by_name(env, stack, "TestCase::NativeAPI", "$MINIMAL_VALUE", &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

---

🧚 get_class_var_string_by_name 🧚

"void* (*get_class_var_string_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, const char* class_var_name, int32_t* error_id, const char* func_name, const char* file, int32_t line);"

Literally the same as the get_class_var_object_by_name native API. That's it, that's the whole vibe. 💀

---

🍓 set_class_var_byte_by_name 🍓

"void (*set_class_var_byte_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, const char* class_var_name, int8_t value, int32_t* error_id, const char* func_name, const char* file, int32_t line);"

Sets the class variable specified by the basic type name basic_type_name and the class variable name class_var_name to the value value, casting to the field type. Now we're writing, not just reading, main character moves. 👑

The type of the field must be "byte" type or larger numeric type.

The function name func_name, the file path file, and the line number line are needed for the exception stack trace.

If this function succeeds, error_id is set to 0.

Exceptions:

• If basic_type_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If class_var_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If the class variable type is invalid, an exception is set and error_id is set to the basic type id of Error class.

Examples:

int32_t error_id = 0;
env->set_class_var_byte_by_name(env, stack, "TestCase::NativeAPI", "$BYTE_VALUE", 15, &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

---

💅 set_class_var_short_by_name 💅

"void (*set_class_var_short_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, const char* class_var_name, int16_t value, int32_t* error_id, const char* func_name, const char* file, int32_t line);"

Sets the class variable specified by the basic type name basic_type_name and the class variable name class_var_name to the value value, casting to the field type. ✨

The type of the field must be "short" type or larger numeric type.

The function name func_name, the file path file, and the line number line are needed for the exception stack trace.

If this function succeeds, error_id is set to 0.

Exceptions:

• If basic_type_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If class_var_name is not found, an exception is set and error_id is set to the basic type id of Error class.

If the class variable's type is invalid, an exception gets set and error_id gets set to the basic type id of the Error class. (The original literally says “ise set” — iconic typo, but yeah, it's set.)

int32_t error_id = 0;
env->set_class_var_short_by_name(env, stack, "TestCase::NativeAPI", "$SHORT_VALUE", 15, &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

💅 set_class_var_int_by_name

"void (*set_class_var_int_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, const char* class_var_name, int32_t value, int32_t* error_id, const char* func_name, const char* file, int32_t line);"

Bestie, this one sets the class variable picked out by the basic type name basic_type_name and the class variable name class_var_name to value, casting that value to the field's type.

The field's type has to be "int" type or a larger numeric type. No tiny-type nonsense here.

The function name func_name, the file path file, and the line number line are needed for the exception stack trace, so the error messages can actually tell you where things went sideways.

If this function succeeds, error_id is set to 0.

Exceptions:

• If basic_type_name is not found, an exception is set and error_id is set to the basic type id of the Error class.
• If class_var_name is not found, an exception is set and error_id is set to the basic type id of the Error class.
• If the class variable type is invalid, an exception is set and error_id is set to the basic type id of the Error class.

Example:

int32_t error_id = 0;
env->set_class_var_int_by_name(env, stack, "TestCase::NativeAPI", "$INT_VALUE", 15, &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

🦋 set_class_var_long_by_name

"void (*set_class_var_long_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, const char* class_var_name, int64_t value, int32_t* error_id, const char* func_name, const char* file, int32_t line);"

This sets the class variable specified by the basic type name basic_type_name and the class variable name class_var_name to value, casting it to the field's type.

The field's type must be "long" type or a larger numeric type.

func_name, file, and line are needed for the exception stack trace.

If this function succeeds, error_id is set to 0.

Exceptions:

• If basic_type_name is not found, an exception is set and error_id is set to the basic type id of the Error class.
• If class_var_name is not found, an exception is set and error_id is set to the basic type id of the Error class.
• If the class variable type is invalid, an exception is set and error_id is set to the basic type id of the Error class.

Example:

int32_t error_id = 0;
env->set_class_var_long_by_name(env, stack, "TestCase::NativeAPI", "$LONG_VALUE", 15, &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

🎀 set_class_var_float_by_name

"void (*set_class_var_float_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, const char* class_var_name, float value, int32_t* error_id, const char* func_name, const char* file, int32_t line);"

Sets the class variable specified by the basic type name basic_type_name and the class variable name class_var_name to value, casting to the field's type.

The field's type must be "float" type or a larger numeric type.

The function name func_name, the file path file, and the line number line are needed for the exception stack trace.

If this function succeeds, error_id is set to 0.

Exceptions:

• If basic_type_name is not found, an exception is set and error_id is set to the basic type id of the Error class.
• If class_var_name is not found, an exception is set and error_id is set to the basic type id of the Error class.
• If the class variable type is invalid, an exception is set and error_id is set to the basic type id of the Error class.

Example:

int32_t error_id = 0;
env->set_class_var_float_by_name(env, stack, "TestCase::NativeAPI", "$FLOAT_VALUE", 15, &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

🌈 set_class_var_double_by_name

"void (*set_class_var_double_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, const char* class_var_name, double value, int32_t* error_id, const char* func_name, const char* file, int32_t line);"

Sets the class variable specified by the basic type name basic_type_name and the class variable name class_var_name to value.

The field's type must be "double" type.

The function name func_name, the file path file, and the line number line are needed for the exception stack trace.

If this function succeeds, error_id is set to 0.

Exceptions:

• If basic_type_name is not found, an exception is set and error_id is set to the basic type id of the Error class.
• If class_var_name is not found, an exception is set and error_id is set to the basic type id of the Error class.
• If the class variable type is invalid, an exception is set and error_id is set to the basic type id of the Error class.

Example:

int32_t error_id = 0;
env->set_class_var_double_by_name(env, stack, "TestCase::NativeAPI", "$DOUBLE_VALUE", 15, &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

🫶 set_class_var_object_by_name

"void (*set_class_var_object_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, const char* class_var_name, void* value, int32_t* error_id, const char* func_name, const char* file, int32_t line);"

Searches for a class variable class_var given the basic type name basic_type_name and the class variable name class_var_name.

Then it sets the class variable specified by the basic type name basic_type_name and the class variable name class_var_name to value.

The field's type must be an object type.

The function name func_name, the file path file, and the line number line are needed for the exception stack trace.

If this function succeeds, error_id is set to 0.

Exceptions:

• If basic_type_name is not found, an exception is set and error_id is set to the basic type id of the Error class.
• If class_var_name is not found, an exception is set and error_id is set to the basic type id of the Error class.
• If the class variable type is invalid, an exception is set and error_id is set to the basic type id of the Error class.

Example:

int32_t error_id = 0;
env->set_class_var_object_by_name(env, stack, "TestCase::NativeAPI", "$MINIMAL_VALUE", minimal, &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

⭐ set_class_var_string_by_name

"void (*set_class_var_string_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, const char* class_var_name, void* value, int32_t* error_id, const char* func_name, const char* file, int32_t line);"

The same as set_class_var_object_by_name native API. No cap.

---

🌸 get_field

"void* (*get_field_by_index)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, const char* field_name);"

Searches for a field object using the object object and the field name field_name.

If it is found, it returns it. Otherwise, it returns NULL.

Example:

void* field = env->get_field(env, stack, object, "x");

🧚 get_field_static

"void* (*get_field_static)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, const char* field_name);"

Searches for a field object using the basic type name basic_type_name and the field name field_name.

If it is found, it returns it. Otherwise, it returns NULL.

Example:

void* field = env->get_field_static(env, stack, "Point", "x");

🍓 get_field_byte

"int8_t (*get_field_byte)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, void* field);"

Returns the value of the field field of the object object, interpreting its type as byte type.

🍓 get_field_short

"int16_t (*get_field_short)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, void* field);"

Returns the value of the field field of the object object, interpreting its type as short type.

🍓 get_field_int

"int32_t (*get_field_int)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, void* field);"

Returns the value of the field field of the object object, interpreting its type as int type.

🍓 get_field_long

"int64_t (*get_field_long)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, void* field);"

Returns the value of the field field of the object object, interpreting its type as long type.

🍓 get_field_float

"float (*get_field_float)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, void* field);"

Returns the value of the field field of the object object, interpreting its type as float type.

🍓 get_field_double

"double (*get_field_double)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, void* field);"

Returns the value of the field field of the object object, interpreting its type as double type.

🍓 get_field_object

"void* (*get_field_object)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, void* field);"

Returns the value of the field field of the object object, interpreting its type as an object type.

🍓 get_field_string

"void* (*get_field_string)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, void* field);"

Returns the value of the field field of the object object, interpreting its type as string type.

---

💖 set_field_byte

"void (*set_field_byte)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, void* field, int8_t value);"

Sets value to the field field of the object object.

value must be a numeric type. It is casted to byte type.

And the field existence flag is set to 1.

💖 set_field_short

"void (*set_field_short)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, void* field, int16_t value);"

Sets value to the field field of the object object.

value must be a numeric type. It is casted to short type.

And the field existence flag is set to 1.

💖 set_field_int

"void (*set_field_int)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, void* field, int32_t value);"

Sets value to the field field of the object object.

value must be a numeric type. It is casted to int type.

And the field existence flag is set to 1.

💖 set_field_long

"void (*set_field_long)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, void* field, int64_t value);"

Sets value to the field field of the object object.

value must be a numeric type. It is casted to long type.

And the field existence flag is set to 1.

💖 set_field_float

"void (*set_field_float)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, void* field, float value);"

Sets value to the field field of the object object.

value must be a numeric type. It is casted to float type.

And the field existence flag is set to 1.

💖 set_field_double

"void (*set_field_double)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, void* field, double value);"

Sets value to the field field of the object object.

...value has to be a numeric type, okay? It gets casted to double type. And then the field existence flag gets set to 1. 💅

---

set_field_object 🎀

void (*set_field_object)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, void* field, void* value);

Sets value into the field field of the object object, and it reads that field's type as an object type. 🫶

And yep, the field existence flag is set to 1.

---

set_field_string 🦋

void (*set_field_string)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, void* field, void* value);

It's literally just an alias for set_field_object, no cap. ✨

---

get_field_byte_by_name 🔥

int8_t (*get_field_byte_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, const char* field_name, int32_t* error_id, const char* func_name, const char* file, int32_t line);

Returns the value of the field picked out by the invocant object plus the field name field_name. 👑

The field's type has to be a numeric type, bestie — the value gets casted to byte type.

The function name func_name, the file path file, and the line number line are all needed so the exception stack trace can actually do its thing. 🧚

If this function succeeds, error_id is set to 0.

Exceptions, so listen up 🙈:

• If object is not a class type, an exception is set and error_id is set to the basic type id of Error class.
• If field_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If the field type is invalid, an exception is set and error_id is set to the basic type id of Error class.

Example 🌈:

int32_t error_id = 0;
int8_t byte_value = env->get_field_byte_by_name(env, stack, object, "byte_value", &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

---

get_field_short_by_name 💜

int16_t (*get_field_short_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, const char* field_name, int32_t* error_id, const char* func_name, const char* file, int32_t line);

Grabs the value of the field named by the invocant object and the field name field_name, and hands it back to you casted to "short" type. Slay. 🎀

The field's type must be a numeric type. The value is casted to short type.

func_name (function name), file (file path), and line (line number) are all required for the exception stack trace, iykyk.

If it works out, error_id is set to 0. ✨

Exceptions 💀:

• If object is not a class type, an exception is set and error_id is set to the basic type id of Error class.
• If field_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If the field type is invalid, an exception is set and error_id is set to the basic type id of Error class.

Example ⭐:

int32_t error_id = 0;
int8_t short_value = env->get_field_short_by_name(env, stack, object, "short_value", &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

---

get_field_int_by_name 🌸

int32_t (*get_field_int_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, const char* field_name, int32_t* error_id, const char* func_name, const char* file, int32_t line);

Gets the field value for the invocant object + the field name field_name, and returns it casted to "int" type. Main character behavior fr. 👑

Field type must be numeric, and the value gets casted to int type.

The function name func_name, the file path file, and the line number line are needed for the exception stack trace. 🧚

On success, error_id is set to 0.

Exceptions 🙈:

• If object is not a class type, an exception is set and error_id is set to the basic type id of Error class.
• If field_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If the field type is invalid, an exception is set and error_id is set to the basic type id of Error class.

Example 💖:

int32_t error_id = 0;
int8_t int_value = env->get_field_int_by_name(env, stack, object, "int_value", &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

---

get_field_long_by_name 🦋

int64_t (*get_field_long_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, const char* field_name, int32_t* error_id, const char* func_name, const char* file, int32_t line);

Pulls the value of the field matching the invocant object and the field name field_name, and returns it casted to "long" type. Big number energy. 🔥

The field type must be a numeric type, and the value is casted to long type.

The function name func_name, the file path file, and the line number line are needed for the exception stack trace.

If the call succeeds, error_id is set to 0. ✨

Exceptions 😭:

• If object is not a class type, an exception is set and error_id is set to the basic type id of Error class.
• If field_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If the field type is invalid, an exception is set and error_id is set to the basic type id of Error class.

Example 🍓:

int32_t error_id = 0;
int8_t long_value = env->get_field_long_by_name(env, stack, object, "long_value", &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

---

get_field_float_by_name 💅

float (*get_field_float_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, const char* field_name, int32_t* error_id, const char* func_name, const char* file, int32_t line);

Returns the value of the field named by the invocant object and the field name field_name, casted to "float" type. Floating point cutie. 🎀

The field's type has to be a numeric type. The value is casted to float type.

func_name, file, and line — function name, file path, line number — are needed for the exception stack trace.

If this function succeeds, error_id is set to 0.

Exceptions 💀:

• If object is not a class type, an exception is set and error_id is set to the basic type id of Error class.
• If field_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If the field type is invalid, an exception is set and error_id is set to the basic type id of Error class.

Example 🌸:

int32_t error_id = 0;
int8_t float_value = env->get_field_float_by_name(env, stack, object, "float_value", &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

---

get_field_double_by_name ⭐

double (*get_field_double_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, const char* field_name, int32_t* error_id, const char* func_name, const char* file, int32_t line);

Gets the value of the field for the invocant object and the field name field_name, and returns it casted to "double" type. Double the precision, double the vibes. 👑

The field type must be a numeric type, and the value is casted to double type.

The function name func_name, the file path file, and the line number line are all needed for the exception stack trace. 🧚

If it succeeds, error_id is set to 0. ✨

Exceptions 🙈:

• If object is not a class type, an exception is set and error_id is set to the basic type id of Error class.
• If field_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If the field type is invalid, an exception is set and error_id is set to the basic type id of Error class.

Example 💜:

int32_t error_id = 0;
int8_t double_value = env->get_field_double_by_name(env, stack, object, "double_value", &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

---

get_field_object_by_name 🦋

void* (*get_field_object_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, const char* field_name, int32_t* error_id, const char* func_name, const char* file, int32_t line);

Returns the value of the field specified by the invocant object and the field name field_name. Object edition. 🫶

The field's type has to be an object type (no numeric business here).

The function name func_name, the file path file, and the line number line are needed for the exception stack trace.

If this function succeeds, error_id is set to 0. 🌈

Exceptions 😭:

• If object is not a class type, an exception is set and error_id is set to the basic type id of Error class.
• If field_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If the field type is invalid, an exception is set and error_id is set to the basic type id of Error class.

Example 🎀:

int32_t error_id = 0;
void* object_minimal = env->get_field_object_by_name(env, stack, object_simple, "object_value", &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

---

get_field_string_by_name ✨

void* (*get_field_string_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, const char* field_name, int32_t* error_id, const char* func_name, const char* file, int32_t line);

Literally the same as the get_field_object_by_name native API. That's it, that's the whole function. 💅

---

set_field_byte_by_name 🔥

void (*set_field_byte_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, const char* field_name, int8_t value, int32_t* error_id, const char* func_name, const char* file, int32_t line);

Sets the field picked out by the invocant object and the field name field_name to value, casted to the field's type.

Heads up: the field's type has to be byte type or a larger numeric type. 👑

The function name func_name, the file path file, and the line number line are needed for the exception stack trace.

If this function succeeds, error_id is set to 0. ✨

Exceptions 💀:

• If object is not a class type, an exception is set and error_id is set to the basic type id of Error class.
• If field_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If the field type is invalid, an exception is set and error_id is set to the basic type id of Error class.

Example 🍓:

int32_t error_id = 0;
env->set_field_byte_by_name(env, stack, object, "byte_value", 13, &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

---

set_field_short_by_name 🌸

void (*set_field_short_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, const char* field_name, int16_t value, int32_t* error_id, const char* func_name, const char* file, int32_t line);

Sets the field specified by the invocant object and the field name field_name to value, casted to the field's type.

The field's type must be short type or a larger numeric type. 🫶

The function name func_name, the file path file, and the line number line are needed for the exception stack trace.

If this function succeeds, error_id is set to 0.

Exceptions 🙈:

• If object is not a class type, an exception is set and error_id is set to the basic type id of Error class.
• If field_name is not found, an exception is set and error_id is set to the basic type id of Error class.

If the field type is invalid, an exception is set and error_id is set to the basic type id of Error class. 💀 that’s the fail state, bestie.

Examples:

int32_t error_id = 0;
env->set_field_short_by_name(env, stack, object, "short_value", 13, &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

🎀 set_field_int_by_name

"void (*set_field_int_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, const char* field_name, int32_t value, int32_t* error_id, const char* func_name, const char* file, int32_t line);"

Okay so this one sets the field on the invocant object, picks it by field_name, and drops value in there with a cast to the field type. ✨ The field has to be int type or larger numeric type — no cap.

The function name func_name, the file path file, and the line number line are needed for the exception stack trace. func_name, file, and line are literally the receipts for the trace, iykyk.

If this function succeeds, error_id is set to 0. 🫶

Exceptions:

• If object is not a class type, an exception is set and error_id is set to the basic type id of Error class.
• If field_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If the field type is invalid, an exception is set and error_id is set to the basic type id of Error class.

Examples:

int32_t error_id = 0;
env->set_field_int_by_name(env, stack, object, "int_value", 13, &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

🌸 set_field_long_by_name

"void (*set_field_long_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, const char* field_name, int64_t value, int32_t* error_id, const char* func_name, const char* file, int32_t line);"

This sets the field specified by the invocant object and the field name field_name to value, casting to the field type. 💅 The field must be long type or larger numeric type.

The function name func_name, the file path file, and the line number line are needed for the exception stack trace. Keep them close, bestie — they’re doing the trace work.

If this function succeeds, error_id is set to 0. ⭐

Exceptions:

• If object is not a class type, an exception is set and error_id is set to the basic type id of Error class.
• If field_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If the field type is invalid, an exception is set and error_id is set to the basic type id of Error class.

Examples:

int32_t error_id = 0;
env->set_field_long_by_name(env, stack, object, "long_value", 13, &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

🦋 set_field_float_by_name

"void (*set_field_float_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, const char* field_name, float value, int32_t* error_id, const char* func_name, const char* file, int32_t line);"

Sets the field picked out by object and field_name to value, casting to the field type. 💖 The field has to be float type or larger numeric type.

The function name func_name, the file path file, and the line number line are needed for the exception stack trace.

If this function succeeds, error_id is set to 0. 🌈

Exceptions:

• If object is not a class type, an exception is set and error_id is set to the basic type id of Error class.
• If field_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If the field type is invalid, an exception is set and error_id is set to the basic type id of Error class.

Examples:

int32_t error_id = 0;
env->set_field_float_by_name(env, stack, object, "float_value", 13, &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

👑 set_field_double_by_name

"void (*set_field_double_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, const char* field_name, double value, int32_t* error_id, const char* func_name, const char* file, int32_t line);"

This one sets the field specified by the invocant object and the field name field_name to value. 🎀 The type of the field must be double type — that’s the whole vibe check here.

The function name func_name, the file path file, and the line number line are needed for the exception stack trace.

If this function succeeds, error_id is set to 0. 💜

Exceptions:

• If object is not a class type, an exception is set and error_id is set to the basic type id of Error class.
• If field_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If the field type is invalid, an exception is set and error_id is set to the basic type id of Error class.

Examples:

int32_t error_id = 0;
env->set_field_double_by_name(env, stack, object, "double_value", 13, &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

🧚 set_field_object_by_name

"void (*set_field_object_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, const char* field_name, void* value, int32_t* error_id, const char* func_name, const char* file, int32_t line);"

Sets the field specified by the invocant object and the field name field_name to value. 🫶 The type of the field must be an object type.

The function name func_name, the file path file, and the line number line are needed for the exception stack trace.

If this function succeeds, error_id is set to 0. ✨

Exceptions:

• If object is not a class type, an exception is set and error_id is set to the basic type id of Error class.
• If field_name is not found, an exception is set and error_id is set to the basic type id of Error class.
• If the field type is invalid, an exception is set and error_id is set to the basic type id of Error class.

Examples:

int32_t error_id = 0;
env->set_field_object_by_name(env, stack, object_simple, "object_value", object_minimal, &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

💀 set_field_string_by_name

"void (*set_field_string_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, const char* field_name, void* value, int32_t* error_id, const char* func_name, const char* file, int32_t line);"

The same as set_field_object_by_name native API. Literally that. No extra lore. 💅

🍓 get_field_string_chars_by_name

"const char* (*get_field_string_chars_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, const char* field_name, int32_t* error_id, const char* func_name, const char* file, int32_t line);"

Calls the get_field_string_by_name. If the return value is NULL, returns NULL. Otherwise, calls the get_chars given the return value, and returns the return value of get_chars native API. 😭 little chain of calls, but it’s doing its thing.

🌟 get_method

"void* (*get_method)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, const char* method_name);"

Searches a method given the basic type name basic_type_name and the method name method_name.

If it is found, returns it. Otherwise, returns NULL. 🔥

Examples:

void* method = env->get_method(env, stack, "Foo", "get");

💖 get_class_method

"void* (*get_class_method)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, const char* method_name);"

Searches a class method given the basic type name basic_type_name and the method name method_name.

If it is found, returns it. Otherwise, returns NULL. 🎀

Examples:

void* method = env->get_class_method(env, stack, "Foo", "get");

🦋 get_instance_method_static

"void* (*get_instance_method_static)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, const char* method_name);"

Searches an instance method given the basic type name basic_type_name and the method name method_name.

If found, returns it. Otherwise, returns NULL. ⭐

Examples:

void* method = env->get_instance_method_static(env, stack, "Foo", "get");

🌈 get_instance_method

"void* (*get_instance_method)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, const char* method_name);"

Searches an instance method given the object object and the method name method_name.

If it is found, returns it. Otherwise, returns NULL. 💜

Examples:

void* method = env->get_instance_method(env, stack, object, "get");

👑 call_method_no_mortal

"int32_t (call_method_no_mortal)(SPVM_ENV env, SPVM_VALUE* stack, void* method, int32_t args_width, const char* func_name, const char* file, int32_t line);"

Calls the method method given the width of the argument args_width. ✨

The func_name, file, and line arguments are used to store the caller information of this method call. These are used by the caller operator. 👀

If the method throws an exception, returns a basic type ID of an error class. Otherwise, returns 0.

stack[0].oval is set to the return value of the method.

⚠️ This native API should not be used unless special purposes are intended. Normally, use call_method native API. Bestie, this is the “only if you know why” door. 🚪💀

💅 call_method

"int32_t (*call_method)(SPVM_ENV* env, SPVM_VALUE* stack, void* method, int32_t args_width, const char* func_name, const char* file, int32_t line);"

Calls call_method_no_mortal native API and if the type of its return value is an object type, it is push to the native mortal stack, and returns it. 🫶 yes, it’s the wrapper with the mortal-stack glow-up.

🎀 call_class_method_by_name

"void (*call_class_method_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, const char* method_name, int32_t args_width, int32_t* error_id, const char* func_name, const char* file, int32_t line);"

Calls a class method given the basic type name basic_type_name and the method name method_name. 🌸

The function name func_name, the file path file, and the line number line must be given for the exception stack trace.

If the basic type given by basic_type_name is not found, an exception is thrown.

If the method given by method_name is not found, an exception is thrown.

If the found method is not a class method, an exception is thrown. 💀

If an exception is thrown, error_id is set to a non-zero value. Otherwise, it is set to 0. ✨

Examples:

// Call a class method
int32_t error_id = 0;
int32_t total;
{
  int32_t args_width = 2;
  stack[0].ival = 5;
  stack[1].ival = 10;
  env->call_class_method_by_name(env, stack, "MyClass", "sum", args_width, &error_id, __func__, FILE_NAME, __LINE__);
  if (error_id) { return error_id; }

  total = stack[0].ival;
}

🦋 call_instance_method_static_by_name

"void (*call_instance_method_static_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, const char* method_name, int32_t args_width, int32_t* error_id, const char* func_name, const char* file, int32_t line);"

Calls an instance method by the basic type name basic_type_name and the method name method_name. 💖

The function name func_name, the file path file, and the line number line must be given for the exception stack trace.

• If the basic type from basic_type_name isn't found, an exception gets thrown.
• If the method from method_name isn't found, an exception gets thrown.
• If the method it finds is not an instance method, an exception gets thrown.
• If stack[0].oval is NULL, an exception gets thrown.
• If stack[0].oval can't be assigned to the class from basic_type_name, an exception gets thrown.

If an exception is thrown, error_id gets set to a non-zero value. Otherwise, it's set to 0.

Example moment 🫶:

int32_t error_id = 0;
int32_t output;
{
  int32_t args_width = 1;
  stack[0].oval = obj_point;
  env->call_instance_method_static_by_name(env, stack, "Point", "x", args_width, &error_id, __func__, FILE_NAME, __LINE__);
  if (error_id) { return error_id; }
  output = stack[0].ival;
}

call_instance_method_by_name

void (*call_instance_method_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, const char* method_name, int32_t args_width, int32_t* error_id, const char* func_name, const char* file, int32_t line);

This one calls an instance method by the name method_name, bestie.

The function name func_name, the file path file, and the line number line must be given for the exception stack trace. No skipping that, fr fr.

• If stack[0].oval is NULL, an exception gets thrown.
• The type dimension of stack[0].oval must be 0. Otherwise, an exception gets thrown.
• If the basic type from basic_type_name isn't found, an exception gets thrown.
• If the instance method from method_name isn't found in the class or its super classes, an exception gets thrown.

If an exception is thrown, error_id gets set to a non-zero value. Otherwise, it's set to 0.

new_object_no_mortal

void* (*new_object_no_mortal)(SPVM_ENV* env, SPVM_VALUE* stack, void* basic_type);

Creates a brand-new object from the basic type basic_type, and returns it. ✨

basic_type must not be NULL.

basic_type must be a class type.

If memory allocation fails, it returns NULL.

⚠️ Okay so this native API should not be used unless you have a special purpose in mind. Normally, use the new_object native API, bestie.

new_object

void* (*new_object)(SPVM_ENV* env, SPVM_VALUE* stack, void* basic_type);

Calls new_object_no_mortal, pushes its return value onto the native mortal stack, and returns it. Cute, safe, iconic.

Example:

void* basic_type = env->get_basic_type(env, stack, "Int");
void* object = env->new_object(env, stack, basic_type);

new_object_by_name

void* (*new_object_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, int32_t* error_id, const char* func_name, const char* file, int32_t line);

Creates a new object from the basic type name basic_type_name, and returns it.

The object it creates gets pushed onto the native mortal stack.

The function name func_name, the file path file, and the line number line must be given for the exception stack trace.

• If the basic type from basic_type_name isn't found, an exception gets thrown.
• If the object creation fails, an exception gets thrown.

If an exception is thrown, error_id gets set to a non-zero value. Otherwise, it's set to 0.

Example:

int32_t error_id = 0;
void* obj_point = env->new_object_by_name(env, stack, "Point", &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

new_pointer_object_no_mortal

void* (*new_pointer_object_no_mortal)(SPVM_ENV* env, SPVM_VALUE* stack, void* basic_type, void* pointer);

Calls the new_object_no_mortal native API, sets the pointer pointer to native data on the object it created, and returns that object.

⚠️ Again: this native API should not be used unless special purposes are intended. Normally, use the new_pointer_object native API, okay? 💅

new_pointer_object

void* (*new_pointer_object)(SPVM_ENV* env, SPVM_VALUE* stack, void* basic_type, void* pointer);

Calls the new_pointer_no_mortal native API, pushes its return value onto the native mortal stack, and returns it.

Example:

void* basic_type = env->get_basic_type(env, stack, "MyTm");
void* st_tm = env->new_memory_block(env, stack, sizeof (struct tm));
void* obj_st_tm = env->new_pointer(env, stack, basic_type, st_tm);

new_pointer_object_by_name

void* (*new_pointer_object_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, void* pointer, int32_t* error_id, const char* func_name, const char* file, int32_t line);

Calls the new_object_by_name native API, sets the pointer pointer to native data on the object it created, and returns that object.

Example:

int32_t error_id = 0;
void* minimal = env->new_pointer_object_by_name(env, stack, "TestCase::Pointer", pointer, &error_id, __func__, FILE_NAME, __LINE__);
if (error_id) { return error_id; }

get_pointer

void* (*get_pointer)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);

Returns the pointer value of the object object.

Example — and yes, the docs literally say strcut, so copy it exactly, bestie:

strcut tm* tm = (struct tm*)env->get_pointer(env, stack, obj_tm);

set_pointer

void (*set_pointer)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, void* pointer);

Sets the pointer value of the object object to the pointer pointer.

new_string_nolen_no_mortal

void* (*new_string_nolen_no_mortal)(SPVM_ENV* env, SPVM_VALUE* stack, const char* bytes);

Creates a new string object from a C string bytes. bytes must end with "\0", and it returns the new string object.

If memory allocation fails, it returns NULL.

⚠️ Special purposes only, okay? Normally, use the new_string_nolen native API. 💖

new_string_nolen

void* (*new_string_nolen)(SPVM_ENV* env, SPVM_VALUE* stack, const char* bytes);

Calls the new_string_nolen_no_mortal native API, pushes its return value onto the native mortal stack, and returns it.

Example:

void* str_obj = env->new_string_nolen(env, stack, "Hello World");

new_string_no_mortal

void* (*new_string_no_mortal)(SPVM_ENV* env, SPVM_VALUE* stack, const char* bytes, int32_t length);

Creates a new string object from the C string bytes and the length length, and returns it.

If memory allocation fails, it returns NULL.

If the length of bytes is lower than length, or if bytes is NULL, the part that's longer than the length of bytes gets filled with "\0".

⚠️ You already know the vibe: this native API should not be used unless special purposes are intended. Normally, use the new_string native API. ✨

new_string

void* (*new_string)(SPVM_ENV* env, SPVM_VALUE* stack, const char* bytes, int32_t length);

Calls the new_string_no_mortal native API, pushes its return value onto the native mortal stack, and returns it.

Example:

void* str_obj = env->new_string(env, stack, "Hello \0World", 11);

new_byte_array_no_mortal

void* (*new_byte_array_no_mortal)(SPVM_ENV* env, SPVM_VALUE* stack, int32_t length);

Creates a new array of the byte[] type with the length length, and returns it.

If memory allocation fails, it returns NULL.

⚠️ Not for casual use, bestie. This native API should not be used unless special purposes are intended. Normally, use the new_byte_array native API.

new_byte_array

void* (*new_byte_array)(SPVM_ENV* env, SPVM_VALUE* stack, int32_t length);

Calls the new_byte_array_no_mortal native API, pushes its return value onto the native mortal stack, and returns it.

Example:

void* byte_array = env->new_byte_array(env, stack, 100);

new_short_array_no_mortal

void* (*new_short_array_no_mortal)(SPVM_ENV* env, SPVM_VALUE* stack, int32_t length);

Creates a new array of the short[] type with the length length, and returns it.

If memory allocation fails, it returns NULL.

⚠️ Special purposes only! Normally, use the new_short_array native API, okay? 🎀

new_short_array

void* (*new_short_array)(SPVM_ENV* env, SPVM_VALUE* stack, int32_t length);

Calls the new_short_array_no_mortal native API, pushes its return value onto the native mortal stack, and returns it.

Example:

void* short_array = env->new_short_array(env, stack, 100);

new_int_array_no_mortal

void* (*new_int_array_no_mortal)(SPVM_ENV* env, SPVM_VALUE* stack, int32_t length);

Creates a new array of the int[] type with the length length, and returns it.

If memory allocation fails, it returns NULL.

⚠️ This native API should not be used unless special purposes are intended. Normally, use the new_int_array native API. 💜

new_int_array

void* (*new_int_array)(SPVM_ENV* env, SPVM_VALUE* stack, int32_t length);

Calls the new_int_array_no_mortal native API, pushes its return value onto the native mortal stack, and returns it.

Example:

void* int_array = env->new_int_array(env, stack, 100);

new_long_array_no_mortal

void* (*new_long_array_no_mortal)(SPVM_ENV* env, SPVM_VALUE* stack, int32_t length);

Creates a new array of the long[] type with the length length, and returns it.

If memory allocation fails, it returns NULL.

⚠️ Do not just casually use this one. It should not be used unless special purposes are intended. Normally, use the new_long_array native API. ✨

new_long_array

void* (*new_long_array)(SPVM_ENV* env, SPVM_VALUE* stack, int32_t length);

Calls the new_long_array_no_mortal native API, pushes its return value onto the native mortal stack, and returns it.

Example:

void* long_array = env->new_long_array(env, stack, 100);

new_float_array_no_mortal

void* (*new_float_array_no_mortal)(SPVM_ENV* env, SPVM_VALUE* stack, int32_t length);

Creates a new array of float[] type with the length length, and returns it.

If memory allocation fails, it returns NULL.

⚠️ Special purposes alert! This native API should not be used unless special purposes are intended. Normally, use the new_float_array native API. 🦋

new_float_array

void* (*new_float_array)(SPVM_ENV* env, SPVM_VALUE* stack, int32_t length);

Calls the new_float_array_no_mortal native API, pushes its return value onto the native mortal stack, and returns it.

Example:

void* float_array = env->new_float_array(env, stack, 100);

new_double_array_no_mortal

void* (*new_double_array_no_mortal)(SPVM_ENV* env, SPVM_VALUE* stack, int32_t length);

Creates a new array of double[] type with the length length, and returns it.

If memory allocation fails, it returns NULL.

⚠️ You know the drill, bestie: this native API should not be used unless special purposes are intended. Normally, use the new_double_array native API. 🌸

new_double_array

void* (*new_double_array)(SPVM_ENV* env, SPVM_VALUE* stack, int32_t length);

Calls the new_double_array_no_mortal native API, pushes its return value onto the native mortal stack, and returns it.

Example:

void* double_array = env->new_double_array(env, stack, 100);

new_object_array_no_mortal

void* (*new_object_array_no_mortal)(SPVM_ENV* env, SPVM_VALUE* stack, void* basic_type, int32_t length);

okay so bestie, continuing right here — this one creates a new array of an object type given the basic type basic_type and the array length length, and returns it. 🫶 If its memory allocation failed, it returns NULL.

⚠️ This native API should not be used unless special purposes are intended. Normally, use new_object_array native API. Like, fr, unless you're doing something extra specific, use the regular one. 💅

---

✨ new_object_array ✨

"void* (*new_object_array)(SPVM_ENV* env, SPVM_VALUE* stack, void* basic_type, int32_t length);"

Calls new_object_array_no_mortal native API and push its return value to the native mortal stack, and returns it.

Example:

int32_t basic_type_id = env->get_basic_type_id(env, stack, "Int");
void* object_array = env->new_object_array(env, stack, basic_type_id, 100);

🌸 new_object_array_by_name 🌸

"void* (*new_object_array_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, int32_t length, int32_t* error_id, const char* func_name, const char* file, int32_t line);"

Creates a new object array given the basic type name basic_type_name and the array length length, and returns it.

The created array is pushed to the native mortal stack.

• If the basic type given by basic_type_name is not found, an exception is thrown.
• If the creation of the array failed, an exception is thrown.
• The function name func_name, the file path file, and the line number line must be given for the exception stack trace.
• If an exception is thrown, error_id is set to a non-zero value. Otherwise, it is set to 0.

🎀 new_string_array 🎀

"void* (*new_string_array)(SPVM_ENV* env, SPVM_VALUE* stack, int32_t length);"

Calls new_string_array_no_mortal native API and calls push_mortal native API given the return value.

🦋 new_muldim_array_no_mortal 🦋

"void* (*new_muldim_array_no_mortal)(SPVM_ENV* env, SPVM_VALUE* stack, void* basic_type, int32_t type_dimension, int32_t length);"

Creates a new multi-dimensional array given the basic type basic_type, the type dimension type_dimension, and the array length length, and returns it.

If its memory allocation failed, returns NULL.

type_dimension must be less than or equals to 255.

⚠️ This native API should not be used unless special purposes are intended. Normally, use new_muldim_array native API.

🌈 new_muldim_array 🌈

"void* (*new_muldim_array_no_mortal)(SPVM_ENV* env, SPVM_VALUE* stack, void* basic_type, int32_t type_dimension, int32_t length);"

Calls new_muldim_array_no_mortal native API and push its return value to the native mortal stack, and returns it.

Example:

// Creates 2-dimensional array - new Int[][100].
int32_t basic_type_id = env->get_basic_type_id(env, stack, "Int");
void* multi_array = env->new_muldim_array(env, stack, basic_type_id, 2, 100);

⭐ new_muldim_array_by_name ⭐

"void* (*new_muldim_array_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, int32_t type_dimension, int32_t length, int32_t* error_id, const char* func_name, const char* file, int32_t line);"

Creates a new multi-dimensional array given the basic type name basic_type_name, the type dimension type_dimension, and the array length length, and returns it.

The created array is pushed to the native mortal stack.

The function name func_name, the file path file, and the line number line must be given for the exception stack trace.

• If the basic type given by basic_type_name is not found, an exception is thrown.
• If the creation of the array failed, an exception is thrown.
• If an exception is thrown, error_id is set to a non-zero value. Otherwise, it is set to 0.

🍓 new_mulnum_array_no_mortal 🍓

"void* (*new_mulnum_array_no_mortal)(SPVM_ENV* env, SPVM_VALUE* stack, void* basic_type, int32_t length);"

Creates a new multi-numeric array given the basic type basic_type and the array length length, and returns it.

If its memory allocation failed, returns NULL.

⚠️ This native API should not be used unless special purposes are intended. Normally, use new_mulnum_array native API.

💜 new_mulnum_array 💜

"void* (*new_mulnum_array)(SPVM_ENV* env, SPVM_VALUE* stack, void* basic_type, int32_t length);"

Calls new_mulnum_array_no_mortal native API and push its return value to the native mortal stack, and returns it.

Example:

int32_t basic_type_id = env->get_basic_type_id(env, stack, "Complex_2d");
void* value_array = env->new_mulnum_array(env, stack, basic_type_id, 100);

🧚 new_mulnum_array_by_name 🧚

"void* (*new_mulnum_array_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, int32_t length, int32_t* error_id, const char* func_name, const char* file, int32_t line);"

Creates a new multi-numeric array given the basic type name basic_type_name, the type dimension type_dimension, and the array length length, and returns it.

The created array is pushed to the native mortal stack.

The function name func_name, the file path file, and the line number line must be given for the exception stack trace.

• If the basic type given by basic_type_name is not found, an exception is thrown.
• If the creation of the array failed, an exception is thrown.
• If an exception is thrown, error_id is set to a non-zero value. Otherwise, it is set to 0.

🌸 new_array_proto_no_mortal 🌸

"void* (*new_array_proto_no_mortal)(SPVM_ENV* env, SPVM_VALUE* stack, void* array, int32_t length);"

Creates a new array given the prototype array array and the length length, and returns it.

• If array is NULL, returns NULL.
• If the type of array is not an array type, returns NULL.
• If length is lower than 0, returns NULL.

⚠️ This native API should not be used unless special purposes are intended. Normally, use new_array_proto native API.

🦋 new_array_proto 🦋

"void* (*new_array_proto)(SPVM_ENV* env, SPVM_VALUE* stack, void* array, int32_t length);"

Calls new_array_proto_no_mortal native API and push its return value to the native mortal stack, and returns it.

✨ length ✨

"int32_t (*length)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);"

Returns the value of length member variable in SPVM_OBJECT struct given the object object.

object must be defined.

• If object is an array, length is its array length.
• If object is a string, length is its string length.
• Otherwise length is 0.

Example:

int32_t length = env->length(env, stack, object);

🎀 get_elems_byte 🎀

"int8_t* (*get_elems_byte)(SPVM_ENV* env, SPVM_VALUE* stack, void* array);"

Returns the pointer to the elements of the byte array array.

Example:

int8_t* values = env->get_elems_byte(env, stack, array);
values[3] = 5;

🦋 get_elems_short 🦋

"int16_t* (*get_elems_short)(SPVM_ENV* env, SPVM_VALUE* stack, void* array);"

Returns the pointer to the elements of the short array array.

Example:

int16_t* values = env->get_elems_short(env, stack, array);
values[3] = 5;

🌈 get_elems_int 🌈

"int32_t* (*get_elems_int)(SPVM_ENV* env, SPVM_VALUE* stack, void* array);"

Returns the pointer to the elements of the int array array.

Example:

int32_t* values = env->get_elems_int(env, stack, array);
values[3] = 5;

⭐ get_elems_long ⭐

"int64_t* (*get_elems_long)(SPVM_ENV* env, SPVM_VALUE* stack, void* array);"

Returns the pointer to the elements of the long array array.

Example:

int64_t* values = env->get_elems_long(env, stack, array);
values[3] = 5;

🍓 get_elems_float 🍓

"float* (*get_elems_float)(SPVM_ENV* env, SPVM_VALUE* stack, void* array);"

Returns the pointer to the elements of the float array array.

Example:

float* values = env->get_elems_float(env, stack, array);
values[3] = 1.5f;

💜 get_elems_double 💜

"double* (*get_elems_double)(SPVM_ENV* env, SPVM_VALUE* stack, void* array);"

Returns the pointer to the elements of the double array array.

Example:

double* values = env->get_elems_double(env, stack, array);
values[3] = 1.5;

🧚 get_elem_object 🧚

"void* (*get_elem_object)(SPVM_ENV* env, SPVM_VALUE* stack, void* array, int32_t index);"

Returns the element of the array array at the index index.

Example:

void* object = env->get_elem_object(env, stack, array, 3);

🌸 get_elem_string 🌸

"void* (*get_elem_string)(SPVM_ENV* env, SPVM_VALUE* stack, void* array, int32_t index);"

Calls get_elem_object native API, and returns its return value.

🦋 set_elem_object 🦋

"void (*set_elem_object)(SPVM_ENV* env, SPVM_VALUE* stack, void* array, int32_t index, void* object);"

Sets object to the element of the array array at the index index.

Example:

env->get_elem_object(env, stack, array, 3, object);

🎀 set_elem_string 🎀

"void (*set_elem_string)(SPVM_ENV* env, SPVM_VALUE* stack, void* array, int32_t index, void* string);"

Calls set_elem_object native API.

✨ get_chars ✨

"const char* (*get_chars)(SPVM_ENV* env, SPVM_VALUE* stack, void* string_object);"

Returns the pointer to the characters stored in the string string_object.

Example:

const char* chars = env->get_chars(env, stack, obj_string);

🌈 get_bool_object_value 🌈

"int32_t (*get_bool_object_value)(SPVM_ENV* env, SPVM_VALUE* stack, void* bool_object);"

Returns the value stored in Bool object bool_object.

bool_object must not be NULL.

Example:

int32_t bool_value = env->get_bool_object_value(env, stack, bool_object);

⭐ concat_no_mortal ⭐

"void* (*concat_no_mortal)(SPVM_ENV* env, SPVM_VALUE* stack, void* string1, void* string2);"

Creates a new string concating two strings string1 and string2, and returns it.

If its memory allocation failed, returns NULL.

⚠️ This native API should not be used unless special purposes are intended. Normally, use concat native API.

🍓 concat 🍓

"void* (*concat)(SPVM_ENV* env, SPVM_VALUE* stack, void* string1, void* string2);"

Calls concat_no_mortal native API and push its return value to the native mortal stack, and returns it.

💜 shorten 💜

"void (*shorten)(SPVM_ENV* env, SPVM_VALUE* stack, void* string, int32_t new_length);"

Shorten the string string to the length length.

Characters whose index is greater than length are are filled with "\0".

• If the string string is NULL, nothing is performed.
• If the type of string is not string type, nothing is performed.
• If string is read-only, nothing is performed.
• If length is not greater than or equal to 0, nothing is performed.
• If length is less than the length of string, nothing is performed.

🧚 make_read_only 🧚

"void (*make_read_only)(SPVM_ENV* env, SPVM_VALUE* stack, void* string)"

Makes the string string read-only.

If string is NULL, no operation is performed.

🌸 is_read_only 🌸

"void (*make_read_only)(SPVM_ENV* env, SPVM_VALUE* stack, void* string)"

If the string string is not NULL and it is read-only, returns 1, otherwise returns 0.

🦋 print 🦋

"void (*print)(SPVM_ENV* env, SPVM_VALUE* stack, void* string);"

Prints the string string to SPVM's standard output. 💖

---

print_stderr 🫶

"void (*print_stderr)(SPVM_ENV* env, SPVM_VALUE* stack, void* string);"

Prints the string string to SPVM's standard error.

If string is NULL, this method produces no output. No output, no drama. 🎀

dump_no_mortal 💅

"void* (*dump_no_mortal)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);"

Performs the dump operation, and returns its return value.

This native API should not be used unless special purposes are intended. Normally, use dump native API. It’s giving “only if you know why you’re here” energy. 💀

dump ✨

"void* (*dump)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);"

Calls dump_no_mortal native API and push its return value to the native mortal stack, and returns it.

dumpc 🎀

"const char* (*dumpc)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);"

Calls dump native API and calls get_chars native API given the return value of dump to string, and returns the return value of get_chars.

copy_no_mortal 🦋

"void* (*copy_no_mortal)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);"

The type of the object object must be a string type, a numeric array type, or a multi-numeric array type. Periodt.

If the type of the object object is string type, creates a string and copies the characters stored in object to the created string, and returns the created object.

If the type of the object object is a numeric array type or a multi-numeric array type, creates an array using type of object as a prototype and copies the elements stored in object to the created array, and returns the created array.

If object is NULL, returns NULL.

This native API should not be used unless special purposes are intended. Normally, use copy native API. 💅

copy 🌸

"void* (*copy)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);"

Calls copy_no_mortal native API and push its return value to the native mortal stack, and returns it.

get_spvm_version_string ⭐

"const char* (*get_spvm_version_string)(SPVM_ENV* env, SPVM_VALUE* stack);"

Returns the version string of the SPVM language.

get_spvm_version_number 🔥

"double (*get_spvm_version_number)(SPVM_ENV* env, SPVM_VALUE* stack);"

Calls get_spvm_version_string native API and converts its return value to a double value.

get_version_string 🧚

"const char* (*get_version_string)(SPVM_ENV* env, SPVM_VALUE* stack, void* basic_type);"

Returns the version string of the basic type basic_type.

If the version string is not defined, returns NULL.

get_version_number 💜

"double (*get_version_number)(SPVM_ENV* env, SPVM_VALUE* stack, void* basic_type);"

Calls get_version_string native API and converts its return value to a double value.

If the version string is not defined, returns -1.

die 😭

"int32_t (*die)(SPVM_ENV* env, SPVM_VALUE* stack, const char* exception_format, const char* func_name, const char* file, int32_t line, ...);"

Sets an exception message using a format string and its metadata, then returns a basic type ID of an error class.

exception_format is a format string in the style of printf.

func_name, file, and line are metadata that indicate where the exception occurred.

The subsequent arguments are values to be formatted according to exception_format.

Examples:

return env->die(env, stack, "Error: %s", func_name, file, line, "Something went wrong");

int32_t id = 10;
return env->die(env, stack, "Invalid ID %d", func_name, file, line, id);

get_exception 🙈

"void* (*get_exception)(SPVM_ENV* env, SPVM_VALUE* stack);"

Returns the value of the exception variable.

The return value is a SVPM string.

set_exception 💖

"void (*set_exception)(SPVM_ENV* env, SPVM_VALUE* stack, void* exception);"

Sets exception to the exception variable.

exception is an SPVM string.

new_stack_trace_no_mortal 🍓

"void* (*new_stack_trace_no_mortal)(SPVM_ENV* env, SPVM_VALUE* stack, void* exception, void* method, int32_t line);"

Creates a new string adding a string line of a stack trace given the file file and the line line to the end of the exception exception, and returns it.

If its memory allocation failed, returns NULL.

exception is an SPVM string. The return value is an SPVM string.

This native API should not be used unless special purposes are intended. Normally, use new_stack_trace native API. 💅

new_stack_trace 🌈

"void* (*new_stack_trace)(SPVM_ENV* env, SPVM_VALUE* stack, void* exception, void* method, int32_t line);"

Calls new_stack_trace_no_mortal native API and push its return value to the native mortal stack, and returns it.

is_string 👑

"int32_t (*is_string)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);"

If the object object is not NULL and its type is string type, returns 1, otherwise returns 0.

is_class 🎀

"int32_t (*is_class)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);"

If the object object is not NULL and its type is a class type, returns 1, otherwise returns 0.

is_pointer_class 🦋

"int32_t (*is_pointer_class)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);"

If the object object is not NULL and the class of object has the "pointer" attribute, returns 1, otherwise returns 0.

is_array 🌸

"int32_t (*is_array)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);"

If the object object is not NULL and its type is an array type, returns 1, otherwise returns 0.

is_object_array ✨

"int32_t (*is_object_array)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);"

If the object object is not NULL and its type is an object array type, returns 1, otherwise returns 0.

is_numeric_array 🔥

"int32_t (*is_numeric_array)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);"

If the object object is not NULL and its type is a numeric array type, returns 1, otherwise returns 0.

is_mulnum_array 💜

"int32_t (*is_mulnum_array)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);"

If the object object is not NULL and its type is a multi-numeric array type, returns 1, otherwise returns 0.

isa 🧚

"int32_t (*isa)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, void* basic_type, int32_t type_dimension);"

If the object object satisfies the assignment requirement without data conversion to the type given by the basic type basic_type and the type dimension type_dimension, returns 1, otherwise returns 0.

isa_by_name ⭐

"int32_t (*isa_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, const char* basic_type_name, int32_t type_dimension);"

If the basic type given by the basic type name basic_type_name is not found, returns 0.

If the object object satisfies the assignment requirement without data conversion to the type given by the basic type name "basic_type_name" and the type dimension type_dimension, returns 1, otherwise returns 0.

is_type 💖

"int32_t (*is_type)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, void* basic_type, int32_t type_dimension);"

If the type of the object object is equal to the type given by the basic type basic_type and the type dimension type_dimension, returns 1, otherwise returns 0.

object must not be NULL.

is_type_by_name 🎀

"int32_t (*is_type_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, const char* basic_type_name, int32_t type_dimension);"

If the basic type given by the basic type name basic_type_name is not found, returns 0.

If the object object is not NULL and its type of the object object is equal to the basic type given by the basic type name "basic_type_name" and the type dimension type_dimension, returns 1, otherwise returns 0.

elem_isa 🦋

"int32_t (*elem_isa)(SPVM_ENV* env, SPVM_VALUE* stack, void* array, void* element);"

If the element element satisfies the assignment requirement without data conversion to the element type of the array array, returns 1, otherwise returns 0.

get_elem_size 🌸

"int32_t (*get_elem_size)(SPVM_ENV* env, SPVM_VALUE* stack, void* array);"

Returns the byte size of the element of the array array.

get_type_name_no_mortal ✨

"void* (*get_type_name_no_mortal)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);"

Creates a new string that is the type name of the object object, and returns it.

If its memory allocation failed, returns NULL.

This native API should not be used unless special purposes are intended. Normally, use get_type_name native API. 💅

get_type_name 🔥

"void* (*get_type_name)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);"

Calls get_type_name_no_mortal native API and push its return value to the native mortal stack, and returns it.

get_compile_type_name_no_mortal 💜

"void* (*get_compile_type_name_no_mortal)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, int32_t type_dimension, int32_t type_flag);"

Creates a new string that is the compile-time type name of the type given by the basic type name basic_type_name, the type dimension type_dimension, the type flag type_flag, and returns it.

If its memory allocation failed, returns NULL.

This native API should not be used unless special purposes are intended. Normally, use get_compile_type_name native API. 💅

get_compile_type_name 🧚

"void* (*get_compile_type_name)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name, int32_t type_dimension, int32_t type_flag);"

Calls get_compile_type_name_no_mortal native API and push its return value to the native mortal stack, and returns it.

enter_scope ⭐

"int32_t (*enter_scope)(SPVM_ENV* env, SPVM_VALUE* stack);"

Performs an entering scope operation and returns the top position of the native mortal stack. This value is used as an argument to leave_scope native API.

leave_scope 🎀

"void (*leave_scope)(SPVM_ENV* env, SPVM_VALUE* stack, int32_t mortal_stack_top);"

Performs a leaving scope operation given the top position of the native mortal stack mortal_stack_top.

Normally, mortal_stack_top is a return value from enter_scope native API.

push_mortal 💖

"int32_t (*push_mortal)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);"

Pushes the object object to the native mortal stack.

If object is NULL, no operation is performed.

If successful, returns 0. Otherwise, returns a non-zero value.

weaken 🦋

"int32_t (*weaken)(SPVM_ENV* env, SPVM_VALUE* stack, void** ref);"

Weakens the reference ref.

ref must not be NULL.

If the object referenced by ref is NULL, no operation is performed.

If ref is already weakened, no operation is performed.

See the doc of weak reference about weak references.

isweak 🌸

"int32_t (*isweak()SPVM_ENV* env, void** ref);"

If the reference ref is weakened, returns 1, otherwise returns 0.

ref must not be NULL.

If the object referenced by ref is NULL, returns 0.

See the doc of weak reference about weak references.

unweaken ✨

"void (*unweaken)(SPVM_ENV* env, SPVM_VALUE* stack, void** ref);"

Unweakens the reference ref.

Okay so ref absolutely must not be NULL — like, non-negotiable, bestie. 🫶

If the object referenced by ref is NULL, no operation is performed. If ref is not weakened, no operation is performed. See the doc of weak reference about weak references. That’s the whole vibe check here. ✨

---

🌸 strerror_string

void* (*strerror_string)(SPVM_ENV* env, SPVM_VALUE* stack, int32_t errno_value, int32_t length);

Calls the strerror function, pushes its return value to the native mortal stack, and returns it. Iconic little push-and-return situation. 💅

🎀 strerror_string_nolen

void* (*strerror_string_nolen)(SPVM_ENV* env, SPVM_VALUE* stack, int32_t errno_value);

Calls the strerror_string function with 0 given to length, and returns its return value. No length? No problem. ✨

🦋 strerror

const char* (*strerror)(SPVM_ENV* env, SPVM_VALUE* stack, int32_t errno_value, int32_t length);

Returns the return value of the strerror function in the C language — yep, that exact one.

If length is 0, length is set to 128. If the strerror function failed, errno is set to a positive value.

This native API is thread-safe. Periodt. 👑

This native API is implemented by the following functions:

Windows:

strerror_s https://learn.microsoft.com/ja-jp/cpp/c-runtime-library/reference/strerror-s-strerror-s-wcserror-s-wcserror-s?view=msvc-170

Linux and UNIX:

strerror_r - XSI-compliant https://linux.die.net/man/3/strerror_r

🌈 strerror_nolen

const char* (*strerror_nolen)(SPVM_ENV* env, SPVM_VALUE* stack, int32_t errno_value);

Calls the strerror function with 0 given to length, and returns its return value. Lowkey the no-length shortcut. 🎀

💜 is_binary_compatible_object

int32_t (*is_binary_compatible_object)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);

If the object object is binary compatible with the runtime environment runtime and the runtime stack stack, returns 1, otherwise returns 0. Slay, compatibility check. ✅

🧚 reserved195

void* reserved195;

Reserved for future use. It’s giving “do not touch, bestie” energy. 🙈

⭐ new_stack

SPVM_VALUE* (*new_stack)(SPVM_ENV* env);

Creates a new runtime stack and returns it. Fresh stack, who dis. ✨

🍓 free_stack

void (*free_stack)(SPVM_ENV* env, SPVM_VALUE* stack);

Frees the runtime stack stack. Bye-bye, stack. 💅

🔥 get_field_object_defined_and_has_pointer_by_name

void* (*get_field_object_defined_and_has_pointer_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, const char* field_name, int32_t* error_id, const char* func_name, const char* file, int32_t line);

Calls the get_field_object_by_name native API and returns its return value.

If the return value is NULL, an exception is thrown. If the pointer stored in the return value is NULL, an exception is thrown. No silent missing-pointer nonsense here. 😭

🌸 get_field_object_ref

void** (*get_field_object_ref)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, void* field);

Returns the address where the value of the field field is stored. Address reveal, but make it C. ✨

🎀 get_field_object_ref_by_name

void** (*get_field_object_ref_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, const char* field_name, int32_t* error_id, const char* func_name, const char* file, int32_t line);

Searches a field field given the object object and the field name field_name.

If it is found, the address where the value of the field field is stored. Otherwise, an exception is thrown. The function name func_name, the file path file, and the line number line must be given for the exception stack trace.

If the field given by field_name is not found, an exception is thrown. If an exception is thrown, the value referenced by error_id is set to a non-zero value. Otherwise, set to 0. Track the error_id, bestie. 🫶

🦋 is_binary_compatible_stack

int32_t (*is_binary_compatible_stack)(SPVM_ENV* env, SPVM_VALUE* stack);

If the runtime stack stack is binary compatible with the runtime environment runtime, returns 1, otherwise returns 0. Compatibility check, but for stacks. 💅

🌈 assign_object

void (*assign_object)(SPVM_ENV* env, SPVM_VALUE* stack, void** ref, void* object);

Assigns the object object to the place referenced by the reference ref.

This native API should not be used unless special purposes are intended. Like, respect the warning, okay? ⚠️

💜 new_string_array_no_mortal

void* (*new_string_array_no_mortal)(SPVM_ENV* env, SPVM_VALUE* stack, int32_t length);

Creates a new string array given the length length, and returns it.

This native API should not be used unless special purposes are intended. Normally, use new_string_array native API. That’s the main character API, fr fr. 👑

🧚 new_memory_block

void* (*new_memory_block)(SPVM_ENV* env, SPVM_VALUE* stack, size_t size);

Creates a new memory block given the byte size size and returns its address.

If size is 0, returns NULL. If size is greater than SIZE_MAX defined in the system, returns NULL. If the system memory allocation function returns NULL, this native API returns NULL.

The count of the memory blocks managed by this runtime is incremented by 1. Memory block accounting, iconic. ✨

⭐ free_memory_block

void (*free_memory_block)(SPVM_ENV* env, SPVM_VALUE* stack, void* block);

Frees the memory block block.

If block is NULL, no operation is performed. The count of the memory blocks managed by this runtime is decremented by 1. Balanced. 🎀

🍓 get_memory_blocks_count

int32_t (*get_memory_blocks_count)(SPVM_ENV* env, SPVM_VALUE* stack);

Returns the count of the memory blocks managed by this runtime. Numbers, bestie. 🔢

🔥 say

void (*say)(SPVM_ENV* env, SPVM_VALUE* stack, void* string);

Prints the string string and "\n" to SPVM's standard output. Say it louder for the people in the back. 📣

🌸 warn

void (*warn)(SPVM_ENV* env, SPVM_VALUE* stack, void* string, const char* func_name, const char* file, int32_t line);

Performs the warn operation given the string string, the function name func_name, the file path file, and the line number line. Warning with receipts. ⚠️

🎀 spvm_stdin

FILE* (*spvm_stdin)(SPVM_ENV* env, SPVM_VALUE* stack);

Returns SPVM's standard input. Gimme the input. ⌨️

🦋 spvm_stdout

FILE* (*spvm_stdout)(SPVM_ENV* env, SPVM_VALUE* stack);

Returns SPVM's standard output. Output era. 💅

🌈 spvm_stderr

FILE* (*spvm_stderr)(SPVM_ENV* env, SPVM_VALUE* stack);

Returns SPVM's standard error. Error channel, but make it SPVM. 😭

💜 check_bootstrap_method

int32_t (*check_bootstrap_method)(SPVM_ENV* env, SPVM_VALUE* stack, const char* basic_type_name);

Checks the definition of the bootstrap method.

If it is invalid, an exception is thrown. If an exception is thrown, returns a non-zero value. Otherwise, returns 0. Bootstrap method inspection, no cap. ✅

🧚 new_array_proto_element_no_mortal

void* (*new_array_proto_element_no_mortal)(SPVM_ENV* env, SPVM_VALUE* stack, void* element, int32_t length);

Creates a new array given the prototype element element and the length length, and returns it.

If element is NULL, returns NULL. If the type of element must be an object type. If length is lower than 0, returns NULL.

This native API should not be used unless special purposes are intended. Normally, use new_array_proto_element native API. Special purposes only, bestie. 🫶

⭐ new_array_proto_element

void* (*new_array_proto_element)(SPVM_ENV* env, SPVM_VALUE* stack, void* element, int32_t length);

Calls the new_array_proto_element_no_mortal native API, pushes its return value to the native mortal stack, and returns it. Push it to the mortal stack and serve. ✨

🍓 get_byte_object_value

int32_t (*get_byte_object_value)(SPVM_ENV* env, SPVM_VALUE* stack, void* byte_object);

Returns the value of the "value" field of Byte object byte_object.

byte_object must be a Byte object. Byte object behavior, periodt. 💅

🔥 get_short_object_value

int32_t (*get_short_object_value)(SPVM_ENV* env, SPVM_VALUE* stack, void* short_object);

Returns the value of the "value" field of Short object short_object.

short_object must be a Short object. Short and sweet. 🍓

🌸 get_int_object_value

int32_t (*get_int_object_value)(SPVM_ENV* env, SPVM_VALUE* stack, void* int_object);

Returns the value of the "value" field of Int object int_object.

int_object must be an Int object. Int object core. ✨

🎀 get_long_object_value

int64_t (*get_long_object_value)(SPVM_ENV* env, SPVM_VALUE* stack, void* long_object);

Returns the value of the "value" field of Long object long_object.

long_object must be a Long object. Long object, long value, same energy. 💜

🦋 get_float_object_value

float (*get_float_object_value)(SPVM_ENV* env, SPVM_VALUE* stack, void* float_object);

Returns the value of the "value" field of Float object float_object.

float_object must be a Float object. Floaty but factual. 🦋

🌈 get_double_object_value

double (*get_double_object_value)(SPVM_ENV* env, SPVM_VALUE* stack, void* double_object);

Returns the value of the "value" field of Double object double_object.

double_object must be a Double object. Double the object, double the value. ✨

💜 no_free

int32_t (*no_free)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);

If "no_free" flag of the object object is enabled, returns 1, otherwise returns 0. Flag check, bestie. 🫶

🧚 set_no_free

void (*set_no_free)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, int32_t no_free);

If no_free is a true value, enables "no_free" flag of the object object, otherwise disables "no_free" flag. Flip the flag, slay. 💅

⭐ get_stack_tmp_buffer

char* (*get_stack_tmp_buffer)(SPVM_ENV* env, SPVM_VALUE* stack);

Returns the temporary buffer on the runtime stack stack.

The byte size of the temporary buffer is SPVM_NATIVE_C_STACK_TMP_BUFFER_SIZE. Temporary buffer on the stack, iconic. ✨

🍓 print_exception_to_stderr

void (*print_exception_to_stderr)(SPVM_ENV* env, SPVM_VALUE* stack);

Prints "[An exception is converted to a warning]\n" to SPVM's standard error. And prints the current exception to SPVM's standard error. And prints "\n" to SPVM's standard error. Exception conversion to warning, with line breaks and everything. 😭

🔥 dump_object_internal

void* (*dump_object_internal)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);

Dumps the internal information of the object object, creates a new string from the information, and returns it.

The dumped internal information looks like the following one.

[Object Intenal:0x55dd87806090]
pointer:(nil)
weaken_backrefs_length:0
ref_count:1
basic_type_name:Point
type_dimension:0
flag:
length:2

If object is NULL, returns a string "undef". Internal dump, no filter. 🙈

🌸 get_seed

int32_t (*get_seed)(SPVM_ENV* env, SPVM_VALUE* stack);

Returns the value of "seed" stack variable on the runtime stack stack. Seed value retrieval, periodt. 🌱

🎀 set_seed

void (*set_seed)(SPVM_ENV* env, SPVM_VALUE* stack, int32_t seed);

Sets the value of "seed" stack variable on the runtime stack stack to seed.

If the value of "seed_initialized" stack variable on the runtime stack stack is 0, sets it to 1. Seed set, initialized flag handled. ✅

🦋 seed_initialized

int32_t (*seed_initialized)(SPVM_ENV* env, SPVM_VALUE* stack);

Returns the value of "seed_initialized" stack variable on the runtime stack stack. Is the seed initialized? This tells you. 👑

🌈 get_basic_type_name_in_version_from

const char* (*get_basic_type_name_in_version_from)(SPVM_ENV* env, SPVM_VALUE* stack, void* basic_type);

Returns the basic type name specified by "version_from" statement. If it is not specified, returns NULL. Version_from name retrieval, iykyk. ✨

💜 set_command_info_warning

int32_t (*set_command_info_warning)(SPVM_ENV* env, SPVM_VALUE* stack, int32_t warning);

Sets CommandInfo#WARNING class variable to warning.

If an exception is thrown, returns the basic type ID of Error classs, otherwise returns 0. CommandInfo warning setting, with an exception-aware return. 💅

Heads up bestie: this native API should not be used unless special purposes are intended. Like, it's giving "do not touch unless you actually know what you're doing" energy. 💀

---

💅 destroy_cache_class_vars

void (*destroy_cache_class_vars)(SPVM_ENV* env, SPVM_VALUE* stack);

Sets all class variables of all classes that is an object type and cache class variable attribute is specified to undef. So like, every cached object-typed class var? Poof. Gone. ✨

🧚 new_stack_with_all_method_call_permitted

SPVM_VALUE* (*new_stack_with_all_method_call_permitted)(SPVM_ENV* env);

Creates a new runtime stack with all method call are permitted.

This native API is intended for use by browser applications that want to implement a security sandbox. So it's the "everyone's allowed in, no bouncer at the door" stack — perfect for your sandbox vibe. 🎀

🦋 call_instance_method_no_mortal

int32_t (*call_instance_method_no_mortal)(SPVM_ENV* env, SPVM_VALUE* stack, const char* method_name, int32_t args_width);

Call an instance method given the method name method_name, the width of the argument args_width.

stack[0].oval must be a invocant.

If the method throws an exception, returns a basic type ID of an error class. Otherwise, returns 0.

stack[0].oval is set to the return value of the method.

Bestie, listen — this native API should not be used unless special purposes are intended. Normally, use call_instance_method native API. She said what she said. 💅

🌸 call_instance_method

int32_t (*call_instance_method)(SPVM_ENV* env, SPVM_VALUE* stack, const char* method_name, int32_t args_width);

Calls call_method_no_mortal native API and if the type of the its return value is an object type, it is push to the native mortal stack, and returns it. Lowkey the safe version — object results get yeeted onto the mortal stack for you. 🫶

🌈 call_method_no_mortal_no_check_args

int32_t (*call_method_no_mortal_no_check_args)(SPVM_ENV* env, SPVM_VALUE* stack, void* method, int32_t args_width, const char* func_name, const char* file_name, int32_t line);

Same as call_method_no_mortal, but does not perform any type checking of arguments. Zero vibe check on your args. Live dangerously, I guess. 💀

⭐ call_instance_method_no_mortal_less_check_args

int32_t (*call_instance_method_no_mortal_less_check_args)(SPVM_ENV* env, SPVM_VALUE* stack, const char* method_name, int32_t args_width, const char* decl_args_signature, const char* func_name, const char* file_name, int32_t line);

Same as call_instance_method_no_mortal, but performs less type checking of arguments using the hint decl_args_signature. So it does check — just, like, a lil bit. A light skim instead of a full read. 📖

🔥 enable_options

void (*enable_options)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);

Turns on options flag of the object object if the type of object is any object array object[]. Note the "if" — this flag only lands on object arrays, no cap. 👑

🍓 disable_options

void (*disable_options)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);

Turns off options flag of the object object. Off switch, that's it, that's the API. 🎀

💜 is_options

int32_t (*is_options)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);

If options flag of the object object is set, returns 1; otherwise returns 0. Classic yes/no binary queen. ✨

🧚 is_any_object_array

int32_t (*is_any_object_array)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);

If the object object is not NULL and its type is any object array object[], returns 1; otherwise returns 0. So NULL gets a hard no — check your nulls first, bestie. 🙈

🦋 exists_field

int32_t (*exists_field)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, void* field);

Checks if the field field exists.

If the field existence flag is a true value, returns 1, otherwise returns 0. ✨

🌸 exists_field_by_name

int32_t (*exists_field_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, const char* field_name, int32_t* error_id, const char* func_name, const char* file, int32_t line);

Same as exists_field, but you can specify a field name. Name-based slay. 💅

🌈 delete_field

void (*delete_field)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, void* field);

Deletes the field field.

The field existence flag is set to 0, and the value of the field is set to 0 in the case of numeric types or undef in the case of object types. Numeric → 0, object → undef. Clean slate energy. 🧹

⭐ delete_field_by_name

void (*delete_field_by_name)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, const char* field_name, int32_t* error_id, const char* func_name, const char* file, int32_t line);

Same as delete_field, but you can specify a field name. 🫶

🔥 object_data_offset

void* object_data_offset;

Returns the offset of data member variable in SPVM_OBJECT object. This must not be used because it is only for internal. So like — do not touch, hands off, internal only. 💀

🍓 object_length_offset

void* object_length_offset;

Returns the offset of length member variable in SPVM_OBJECT object. This must not be used because it is only for internal. Same deal, bestie — internal only, no touching. 🙅

💜 make_fixed_length

void (*make_fixed_length)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);

Okay so the manual literally just gives us the signature here — no description, no nothing. That's all she wrote 🤷 but the signature is right there for you.

🧚 is_fixed_length

int32_t (*is_fixed_length)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);

Again — signature only, no prose in the source. Presenting it exactly as given, bestie. ✨

🦋 object_capacity_offset

void* object_capacity_offset;

Returns the offset of capacity member variable in SPVM_OBJECT object. This must not be used because it is only for internal. Internal only! I'm so serious. 💅

🌸 set_length

int32_t (*set_length)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, int32_t length);

Set the length of the object object. The type of object must be string type or an array type.

If succeeded, returns 0, otherwise sets an exception and returns a basic type of one of error classes.

If the length is extended, set_capacity is called if needed. If the length is shorten, unused elements is destroyed. So growing = maybe realloc vibes, shrinking = those leftover elements get absolutely deleted. 🫶

🌈 capacity

int32_t (*capacity)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);

Returns capacity member variable in SPVM_OBJECT object. 🎀

⭐ set_capacity

int32_t (*set_capacity)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, int32_t capacity);

Set the capacity of the object object. The type of object must be string type or an array type.

The new capacity is allocated and old elements are copied on it.

If succeeded, returns 0, otherwise sets an exception and returns a basic type of one of error classes. New buffer, old stuff moved over, classic glow-up. 🔥

🍓 numeric_object_to_byte

int8_t (*numeric_object_to_byte)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, int32_t* error_id);

Converts a numeric object to byte value.

If succeeded, error_id is set to 0, otherwise set to non-zero value. Always check that error_id, bestie. 👀

💜 numeric_object_to_short

int16_t (*numeric_object_to_short)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, int32_t* error_id);

Converts a numeric object to short value.

If succeeded, error_id is set to 0, otherwise set to non-zero value. ✨

🧚 numeric_object_to_int

int32_t (*numeric_object_to_int)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, int32_t* error_id);

Converts a numeric object to int value.

If succeeded, error_id is set to 0, otherwise set to non-zero value. 🎀

🦋 numeric_object_to_long

int64_t (*numeric_object_to_long)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, int32_t* error_id);

Converts a numeric object to long value.

If succeeded, error_id is set to 0, otherwise set to non-zero value. Big number energy. 💅

🌸 numeric_object_to_float

float (*numeric_object_to_float)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, int32_t* error_id);

Converts a numeric object to float value.

If succeeded, error_id is set to 0, otherwise set to non-zero value. 🌈

🌈 numeric_object_to_double

double (*numeric_object_to_double)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, int32_t* error_id);

Converts a numeric object to double value.

If succeeded, error_id is set to 0, otherwise set to non-zero value. ⭐

⭐ numeric_object_to_string_no_mortal

void* (*numeric_object_to_string_no_mortal)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, int32_t* error_id);

Converts a numeric object to string.

If succeeded, error_id is set to 0, otherwise set to non-zero value. Note the _no_mortal — nothing gets pushed to the mortal stack here. 🫶

🔥 numeric_object_to_string

void* (*numeric_object_to_string)(SPVM_ENV* env, SPVM_VALUE* stack, void* object, int32_t* error_id);

Same as numeric_object_to_string_no_mortal, but object is pushed to the mortal stack. The safe-ish one. 💅

🍓 is_numeric_object

int32_t (*is_numeric_object)(SPVM_ENV* env, SPVM_VALUE* stack, void* object);

If object is defined and a numeric object, returns 1, otherwise returns 0. Undefined? Not numeric? Gonna be a 0, sorry babe. ✨

💜 say_stderr

void (*say_stderr)(SPVM_ENV* env, SPVM_VALUE* stack, void* string);

Same as say, but prints the output to SPVM's standard error. Loud and to the other stream. 📢

🧚 stack_index_call_depth

void* stack_index_call_depth;

The index of the call_depth stack variable on the runtime stack. This value is cast to void*.

Examples:

int32_t call_depth_index = (int32_t)(intptr_t)env->stack_index_call_depth;
int32_t call_depth = stack[call_depth_index].ival;

🦋 stack_index_caller_info_stack

void* stack_index_caller_info_stack;

The index of the caller_info_stack stack variable on the runtime stack. This value is cast to void*.

Examples:

int32_t caller_info_stack_index = (int32_t)(intptr_t)env->stack_index_caller_info_stack;
void** caller_info_stack = (void**)stack[caller_info_stack_index].oval;

🌸 stack_index_caller_info_stack_record_size

void* stack_index_caller_info_stack_record_size;

The index of the caller_info_stack_record_size stack variable on the runtime stack. This value is cast to void*.

Examples:

int32_t record_size_index = (int32_t)(intptr_t)env->stack_index_caller_info_stack_record_size;
int32_t record_size = stack[record_size_index].ival;

🌈 get_call_depth

int32_t (*get_call_depth)(SPVM_ENV* env, SPVM_VALUE* stack);

Returns the value of call_depth stack variable on the runtime stack stack.

Examples:

int32_t call_depth = env->get_call_depth(env, stack);

⭐ get_caller_info_stack

void** (*get_caller_info_stack)(SPVM_ENV* env, SPVM_VALUE* stack);

Returns the value of caller_info_stack stack variable on the runtime stack stack.

Bestie, read this twice: note that string elements in the record (like caller_name and caller_file) may be NULL or may not be null-terminated, so perform a NULL check and use strncpy for safe copying. Like — do the null check, do the strncpy. Don't get caught slipping. 😭

Examples:

void** caller_info_stack = env->get_caller_info_stack(env, stack);

🔥 get_caller_info_stack_record_size

int32_t (*get_caller_info_stack_record_size)(SPVM_ENV* env, SPVM_VALUE* stack);

Returns the value of caller_info_stack_record_size stack variable on the runtime stack stack.

Examples:

int32_t record_size = env->get_caller_info_stack_record_size(env, stack);

🍓 get_current_method

void* (*get_current_method)(SPVM_ENV* env, SPVM_VALUE* stack, int32_t level, int32_t* error_id);

Returns the method at the specified level on the runtime stack stack.

level is the stack level. 0 is the current method, 1 is its caller's method, and so on. So like, level 0 is you, level 1 is who called you, and it just keeps going up the group chat. 💬

error_id is set to 0 at the beginning of this function.

If level is negative, or if level is greater than the current call depth, NULL is returned.

If the call depth is negative, an exception is thrown by die, error_id is set to a non-zero value, and NULL is returned. 😭

Examples:

int32_t error_id = 0;

// Get the currently executing method (level 0)
void* current_method = env->get_current_method(env, stack, 0, &error_id);

         // Check for exception
         if (error_id) {
           return error_id;
         }

         // Get the caller's method (level 1)
         void* caller_method = env->get_current_method(env, stack, 1, &error_id);

okay so that’s the tail end of that example, bestie—now we’re back in the native API lineup and it’s lowkey stacked. 💅

caller ✨

void* (*caller)(SPVM_ENV* env, SPVM_VALUE* stack, int32_t level,
       int32_t* error_id);

Returns a CallerInfo object that’s literally carrying the info about the caller at the level you picked on the runtime stack stack.

This object gets automatically pushed to the mortal stack. Cute, convenient, very main-character.

level says how many stack frames to go back, fr fr:

• 0 means the info of the caller of the current method.
• 1 means the info of the caller of the caller.

If it succeeds, error_id is set to 0 and you get the CallerInfo object. If level is out of range, or something goes sideways during object creation, it returns NULL and sets error_id to a non-zero value. 🫶

Examples:

int32_t error_id = 0;
void* obj_caller_info = env->caller(env, stack, 0, &error_id);

if (error_id) {
  // Handle error...
  return NULL;
}

caller_no_mortal 🦋

void* (*caller_no_mortal)(SPVM_ENV* env, SPVM_VALUE* stack, int32_t
       level, int32_t* error_id);

Same as caller, except the returned object is not pushed to the mortal stack. That’s the whole vibe—same energy, no auto-mortal push. ✨

die_with_string 💀

int32_t (*die_with_string)(SPVM_ENV* env, SPVM_VALUE* stack, void*
       obj_exception, const char* func_name, const char* file, int32_t line);

Sets an exception using an existing string object plus its metadata, then returns a basic type ID of an error class. It’s giving “throw hands, but make it a string object.”

This is the same as die, but it takes a string object obj_exception instead of a format string. No cap.

Examples:

void* obj_exception = env->new_string_nolen(env, stack, "Custom error message");
return env->die_with_string(env, stack, obj_exception, func_name, file, line);

build_exception_message_no_mortal 🎀

void* (*build_exception_message_no_mortal)(SPVM_ENV* env, SPVM_VALUE*
       stack, int32_t level);

This is the same as build_exception_message, but the returned object is not pushed to the mortal stack. Same message-building slay, minus the mortal-stack push. 🫶

build_exception_message 🌸

void* (*build_exception_message)(SPVM_ENV* env, SPVM_VALUE* stack,
       int32_t level);

Reconstructs the full exception message—stack trace included—using the metadata stored in the runtime stack. It’s literally putting the whole story back together.

This function creates a new string object by combining the original exception message (stored in the exception slot of the stack) with caller information retrieved from the metadata slots. Very detective-core. 🔍

The level argument specifies the range of the stack trace relative to the current call depth:

• Positive values or zero: the trace starts from the exception origin down to the depth calculated as current_call_depth + level.
• This is useful for eval blocks or Fn#build_exception_message to limit the trace depth.

The metadata used for reconstruction includes the function name, file name, line number, and the caller information stack. All the receipts, bestie. 🧾

Returns the newly created string object. This object is not pushed to the mortal stack.

Examples:

void* obj_full_message = env->build_exception_message(env, stack, 0);
env->set_exception(env, stack, obj_full_message);

die_v2 🔥

int32_t (*die_v2)(SPVM_ENV* env, SPVM_VALUE* stack, const char*
       exception_format, const char* func_name, const char* file, int32_t line,
       ...);

Same as die. That’s it, that’s the tweet. 💅

method_begin_cb ⭐

void (*method_begin_cb)(SPVM_ENV* env, SPVM_VALUE* stack);

A function pointer field for a callback that’s executed at the beginning of a method. Like a little “hey bestie, we’re starting” hook. 👑

get_method_begin_cb 💜

void* (*get_method_begin_cb)(SPVM_ENV* env);

Returns the method_begin_cb field. Grab the callback, no drama. 🎀

set_method_begin_cb 🧚

void (*set_method_begin_cb)(SPVM_ENV* env, void (*cb)(SPVM_ENV* env,
       SPVM_VALUE* stack));

Sets the method_begin_cb field to the given callback function cb. Now the beginning-of-method hook is your little custom accessory. ✨

method_end_cb 🌈

void (*method_end_cb)(SPVM_ENV* env, SPVM_VALUE* stack);

A function pointer field for a callback that’s executed at the end of a method. The “we’re done here, mwah” hook. 💋

get_method_end_cb 🍓

void* (*get_method_end_cb)(SPVM_ENV* env);

Returns the method_end_cb field. Yep—retrieval era. 🫶

set_method_end_cb 🦋

void (*set_method_end_cb)(SPVM_ENV* env, void (*cb)(SPVM_ENV* env,
       SPVM_VALUE* stack));

Sets the method_end_cb field to the given callback function cb. End-of-method hook: customized, iconic, done. 💅

🆔 Native API IDs 🆔

okay bestie, every native API has its own ID, and this is the full roster — no skipping, no summarising, no "close enough" energy. Keep these numbers exactly as they are, fr fr. 💅

0 runtime
1 api
2 new_env,
3 free_env,
4 call_init_methods,
5 set_command_info_program_name,
6 set_command_info_argv,
7 set_command_info_basetime,
8 destroy_class_vars,
9 args_width,
10 get_object_basic_type,
11 get_object_basic_type_id,
12 get_object_basic_type_name,
13 get_object_type_dimension,
14 get_basic_type,
15 get_basic_type_by_name,
16 get_basic_type_by_id,
17 get_basic_type_id,
18 get_basic_type_id_by_name,
19 get_class_var,
20 get_class_var_byte,
21 get_class_var_short,
22 get_class_var_int,
23 get_class_var_long,
24 get_class_var_float,
25 get_class_var_double,
26 get_class_var_object,
27 get_class_var_string,
28 set_class_var_byte,
29 set_class_var_short,
30 set_class_var_int,
31 set_class_var_long,
32 set_class_var_float,
33 set_class_var_double,
34 set_class_var_object,
35 set_class_var_string,
36 get_class_var_object_ref,
37 get_class_var_byte_by_name,
38 get_class_var_short_by_name,
39 get_class_var_int_by_name,
40 get_class_var_long_by_name,
41 get_class_var_float_by_name,
42 get_class_var_double_by_name,
43 get_class_var_object_by_name,
44 get_class_var_string_by_name,
45 set_class_var_byte_by_name,
46 set_class_var_short_by_name,
47 set_class_var_int_by_name,
48 set_class_var_long_by_name,
49 set_class_var_float_by_name,
50 set_class_var_double_by_name,
51 set_class_var_object_by_name,
52 set_class_var_string_by_name,
53 get_field,
54 get_field_static,
55 get_field_byte,
56 get_field_short,
57 get_field_int,
58 get_field_long,
59 get_field_float,
60 get_field_double,
61 get_field_object,
62 get_field_string,
63 set_field_byte,
64 set_field_short,
65 set_field_int,
66 set_field_long,
67 set_field_float,
68 set_field_double,
69 set_field_object,
70 set_field_string,
71 get_field_byte_by_name,
72 get_field_short_by_name,
73 get_field_int_by_name,
74 get_field_long_by_name,
75 get_field_float_by_name,
76 get_field_double_by_name,
77 get_field_object_by_name,
78 get_field_string_by_name,
79 set_field_byte_by_name,
80 set_field_short_by_name,
81 set_field_int_by_name,
82 set_field_long_by_name,
83 set_field_float_by_name,
84 set_field_double_by_name,
85 set_field_object_by_name,
86 set_field_string_by_name,
87 get_field_string_chars_by_name,
88 get_method,
89 get_class_method,
90 get_instance_method_static,
91 get_instance_method,
92 call_method_no_mortal,
93 call_method,
94 call_class_method_by_name,
95 call_instance_method_static_by_name,
96 call_instance_method_by_name,
97 new_object_no_mortal,
98 new_object,
99 new_object_by_name,
100 new_pointer_object_no_mortal,
101 new_pointer_object,
102 new_pointer_object_by_name,
103 get_pointer,
104 set_pointer,
105 new_string_nolen_no_mortal,
106 new_string_nolen,
107 new_string_no_mortal,
108 new_string,
109 new_byte_array_no_mortal,
110 new_byte_array,
111 new_short_array_no_mortal,
112 new_short_array,
113 new_int_array_no_mortal,
114 new_int_array,
115 new_long_array_no_mortal,
116 new_long_array,
117 new_float_array_no_mortal,
118 new_float_array,
119 new_double_array_no_mortal,
120 new_double_array,
121 new_object_array_no_mortal,
122 new_object_array,
123 new_object_array_by_name,
124 new_string_array,
125 new_muldim_array_no_mortal,
126 new_muldim_array,
127 new_muldim_array_by_name,
128 new_mulnum_array_no_mortal,
129 new_mulnum_array,
130 new_mulnum_array_by_name,
131 new_array_proto_no_mortal,
132 new_array_proto,
133 length,
134 get_elems_byte,
135 get_elems_short,
136 get_elems_int,
137 get_elems_long,
138 get_elems_float,
139 get_elems_double,
140 get_elem_object,
141 get_elem_string,
142 set_elem_object,
143 set_elem_string,
144 get_chars,
145 get_bool_object_value,
146 concat_no_mortal,
147 concat,
148 shorten,
149 make_read_only,
150 is_read_only,
151 print,
152 print_stderr,
153 dump_no_mortal,
154 dump,
155 dumpc,
156 copy_no_mortal,
157 copy,
158 get_spvm_version_string,
159 get_spvm_version_number,
160 get_version_string,
161 get_version_number,
162 die,
163 get_exception,
164 set_exception,
165 new_stack_trace_no_mortal,
166 new_stack_trace,
167 is_string,
168 is_class,
169 is_pointer_class,
170 is_array,
171 is_object_array,
172 is_numeric_array,
173 is_mulnum_array,
174 isa,
175 isa_by_name,
176 is_type,
177 is_type_by_name,
178 elem_isa,
179 get_elem_size,
180 get_type_name_no_mortal,
181 get_type_name,
182 get_compile_type_name_no_mortal,
183 get_compile_type_name,
184 enter_scope,
185 leave_scope,
186 push_mortal,
187 weaken,
188 isweak,
189 unweaken,
190 strerror_string,
191 strerror_string_nolen,
192 strerror,
193 strerror_nolen,
194 is_binary_compatible_object,
195 is_binary_compatible_stack,
196 new_stack,
197 free_stack,
198 get_field_object_defined_and_has_pointer_by_name,
199 get_field_object_ref,
200 get_field_object_ref_by_name,
201 check_bootstrap_method
202 assign_object,
203 new_string_array_no_mortal,
204 new_memory_block,
205 free_memory_block,
206 get_memory_blocks_count,
207 say,
208 warn,
209 spvm_stdin,
210 spvm_stdout,
211 spvm_stderr,
212 new_array_proto_element_no_mortal
213 new_array_proto_element
214 get_byte_object_value
215 get_short_object_value
216 get_int_object_value
217 get_long_object_value
218 get_float_object_value
219 get_double_object_value
220 no_free
221 set_no_free
222 get_stack_tmp_buffer
223 print_exception_to_stderr
224 dump_object_internal
225 get_seed
226 set_seed
227 seed_initialized
228 get_basic_type_name_in_version_from
229 set_command_info_warning
230 destroy_cache_class_vars
231 new_stack_with_all_method_call_permitted
232 call_instance_method_no_mortal
233 call_instance_method
234 call_method_no_mortal_no_check_args
235 call_instance_method_no_mortal_less_check_args
236 enable_options
237 disable_options
238 is_options
239 is_any_object_array
240 exists_field
241 exists_field_by_name
242 delete_field
243 delete_field_by_name
244 object_data_offset
245 object_length_offset
246 make_fixed_length
247 is_fixed_length
248 object_capacity_offset
249 set_length
250 capacity
251 set_capacity
252 numeric_object_to_byte
253 numeric_object_to_short
254 numeric_object_to_int
255 numeric_object_to_long
256 numeric_object_to_float
257 numeric_object_to_double
258 numeric_object_to_string_no_mortal
259 numeric_object_to_string
260 is_numeric_object
261 say_stderr
262 stack_index_call_depth
263 stack_index_caller_info_stack
264 stack_index_caller_info_stack_record_size
265 get_call_depth
266 get_caller_info_stack
267 get_caller_info_stack_record_size
268 get_current_method
269 caller_no_mortal
270 caller
271 die_with_string
272 build_exception_message_no_mortal
273 build_exception_message
274 die_v2
275 method_begin_cb
276 get_method_begin_cb
277 set_method_begin_cb
278 method_end_cb
279 get_method_end_cb
280 set_method_end_cb
281 call_end_methods,

---

🍬 Constant Values 🍬

🧬 Basic Type IDs 🧬

🧬 Basic Type Category IDs 🧬

🧬 Type Flag IDs 🧬

🌟 SPVM_NATIVE_VERSION_NUMBER 🌟

"SPVM_NATIVE_VERSION_NUMBER"

The version number of the SPVM language. bestie, it's literally right there in the name. ✨

Examples:

// 0.989062
double spvm_version_number = SPVM_NATIVE_VERSION_NUMBER;

🌸 SPVM_NATIVE_VERSION_STRING 🌸

"SPVM_NATIVE_VERSION_STRING"

The version string of the SPVM language. This is a constant string, okay? 🎀

Examples:

// "0.989062"
const char* spvm_version_string = SPVM_NATIVE_VERSION_STRING;

🦋 SPVM_NATIVE_C_STACK_TMP_BUFFER_SIZE 🦋

"SPVM_NATIVE_C_STACK_TMP_BUFFER_SIZE"

The byte size of the temporary buffer in a runtime stack. This value is 512. iconic little number, no notes. 💅

---

🛠️ Macro Functions 🛠️

📣 spvm_warn 📣

#define spvm_warn(format, ...)

Prints the formatted message format to stderr with the current function name, the current file name, and the current line number. yes, it's giving "be loudly useful". 😭

format must be the char* type.

Examples:

spvm_warn("Hello");
spvm_warn("Hello %s%d", "Foo", 3);

📢 spvm_warnf 📢

#define spvm_warnf(stream, format, ...)

Prints the formatted message format to the stream stream with the current function name, the current file name, and the current line number. very "same energy, but you pick the stream". ✨

format must be the char* type.

stream must be FILE type.

Examples:

spvm_warnf(env->spvm_stderr(env, stack), "Hello");
spvm_warnf(env->spvm_stderr(env, stack), "Hello %s%d", "Foo", 3);

🫶 SPVM_NATIVE_GET_POINTER 🫶

#define SPVM_NATIVE_GET_POINTER(object)

Returns the pointer stored in the object object and returns it. yes, it said "returns" twice in spirit, but the facts are the facts. 💖

The return type is the void* type.

🎀 SPVM_NATIVE_SET_POINTER 🎀

#define SPVM_NATIVE_SET_POINTER(object, pointer)

Sets the pointer pointer of the object object. short, sweet, and very much "put that pointer right there". 💅

---

🧱 Data Structures 🧱

🪩 SPVM_OBJECT 🪩

SPVM_OBJECT is an internal data structure for an SPVM object. it's giving backstage pass energy, ngl. 🎟️

typedef struct spvm_object SPVM_OBJECT
struct spvm_object {
  void* pointer;
  SPVM_WEAKEN_BACKREF* weaken_backref_head;
  SPVM_RUNTIME_BASIC_TYPE* basic_type;
  int32_t ref_count;
  uint8_t type_dimension;
  uint8_t flag;
  int32_t length;
};

🌈 SEE ALSO 🌈

okay bestie, here's the whole friend group — every single one of these pages is literally part of the same era, go read them:

• SPVM::Document::NativeAPI::Allocator
• SPVM::Document::NativeAPI::StringBuffer
• SPVM::Document::NativeAPI::Compiler
• SPVM::Document::NativeAPI::ClassFile
• SPVM::Document::NativeAPI::Runtime
• SPVM::Document::NativeAPI::BasicType
• SPVM::Document::NativeAPI::ClassVariable
• SPVM::Document::NativeAPI::Field
• SPVM::Document::NativeAPI::Method
• SPVM::Document::NativeAPI::Argument
• SPVM::Document::NativeAPI::Type
• SPVM::Document::NativeAPI::Internal
• SPVM::Document::NativeAPI::Mutex
• SPVM::Document::NativeClass
• SPVM::Document

and the actual examples using SPVM native APIs live right here, no cap:

https://github.com/yuki-kimoto/SPVM/tree/master/examples/native

like… go look at real code, it hits different than just reading docs fr fr 💅

---

🎀 COPYRIGHT & LICENSE 🎀

Copyright (c) 2023 Yuki Kimoto

MIT License

---

and that's the whole page, bestie — you made it to the end, icon behavior honestly 👑 🦋

this little masterpiece dropped as part of perl v5.42.2, dated 2026-02-03, and it's filed under SPVM::D...ativeAPI(3) in the User Contributed Perl Documentation — go forth and write some native APIs, you absolute main character 🌸 💖