Data Manipulation

Classes

json_array

Methods

add

Add a value to the end of a JSON array.

void json_array::add(var@ value);

Arguments:

var@ value: a handle to the value to be set.

Example:

void main() {
	json_array@ arr = parse_json("[]");
	for (uint i = 0; i < 5; i++)
		arr.add(random(1, 100));
	alert("Filled array", arr.stringify());
}

clear

Clears the JSON array completely.

void json_array::clear();

Example:

void main() {
	string data = "[1, 2, 3, 4, 5]";
	json_array@ arr = parse_json(data);
	alert("Before being cleared", arr.stringify());
	arr.clear();
	alert("After being cleared", arr.stringify());
}

is_array

Determine if the value at the given index is a JSON array or not.

bool json_array::is_array(uint index);

Arguments:

uint index: the position of the item.

Returns:

bool: true if the value at the specified index is a JSON array, false otherwise.

Example:

void main() {
	json_array@ arr = parse_json("[[1, 2], [3, 4]]");
	alert("Info", arr.is_array(1) ? "It is an array": "It is not an array");
}

is_null

Determine if the value at the given index is null.

bool json_array::is_null(uint index);

Arguments:

uint index: the position of the item.

Returns:

bool: true if the value at the specified index is null, false otherwise.

Example:

void main() {
	json_array@ arr = parse_json("[1, 2, null, 4]");
	alert("Info", "Index 1 " + (arr.is_null(1) ? " is null": " is not null"));
	alert("Info", "Index 2 " + (arr.is_null(2) ? " is null": " is not null"));
}

is_object

Determine if the value at the given index is a JSON object.

bool json_array::is_object(uint index);

Arguments:

uint index: the position of the item.

Returns:

bool: true if the value at the specified index is a JSON object, false otherwise.

Example:

void main() {
	json_array@ arr = parse_json("""[{}, {}, "test", {}]""");
	alert("Info", "Position 0 " + (arr.is_object(0) ? "is an object" : "is not an object"));
	alert("Info", "Position 2 " + (arr.is_object(2) ? "is an object": "is not an object"));
}

remove

Remove a value from the JSON array given an index.

void json_array::remove(uint index);

Arguments:

uint index: the index of the value to remove.

Example:

void main() {
	string data = """[47, 4, 584, 43, 8483]""";
	json_array@ arr = parse_json(data);
	alert("Initial", arr.stringify());
	arr.remove(2);
	alert("After removal", arr.stringify());
}

size

Return the size of the JSON array.

uint json_array::size();

Example:

void main() {
	string data = "[";
	for (int i = 0; i < random(10, 20); i++)
		data += i + ", ";
	// Strip off the trailing comma and space character, as they'll make the JSON throw a syntax error.
	data.erase(data.length() - 1);
	data.erase(data.length() - 1);
	data += "]";
	clipboard_set_text(data);
	json_array@ arr = parse_json(data);
	alert("Info", "The JSON array contains " + arr.size() + " items");
}

stringify

Return the JSON array as a string.

string json_array::stringify(int indent = 0, int step = -1);

Arguments:

int indent = 0: specifies how many spaces to use to indent the JSON. If 0, no indentation or formatting is performed.
int step = -1: the outwards indentation step, for example setting it to two would cause your outdents to only be two spaces. -1 (the default) keeps it how it is, normally you don't need to use this parameter.

Returns:

string: the JSON array as a string.

Example:

void main() {
	string data = """["Apple", "Banana", "Orange", "Lemon"]""";
	json_array@ arr = parse_json(data);
	alert("JSON array", arr.stringify(4));
}

Operators

get_opIndex

Get a value out of the JSON array with literal syntax, for example arr[2].

var@ json_array::get_opIndex(uint index) property;

Arguments:

uint index: the index of the value to get.

Returns:

var@: a handle to the object, or null if not found.

Example:

void main() {
	json_array@ cats = parse_json("""["Athena", "Willow", "Punk", "Franky", "Yoda", "Waffles"]""");
	alert("The third cat is", cats[2]);
	for (uint i = 0; i < cats.size(); i++)
		alert("Awww", "Hi " + cats[i]);
}

opCall

Get a value out of a JSON array using a query.

var@ json_array::opCall(string query);

Arguments:

string query: the JSON query (see the remarks section for details).

Returns:

var@: a handle to the object, or null if it couldn't be found.

Remarks:

Queries are formatted like so, using key names and indexes separated with ".":

world.player.0

It can be as nested as you like.

Example:

void main() {
	string data = """[[["Colorado", "Kansas", "Minnesota"]]]""";
	json_array@ arr = parse_json(data);
	string location = arr("0.0.0");
	alert("My favorite state is", location);
}

set_opIndex

Set a value in the JSON array at a particular position.

void json_array::set_opIndex(uint index, var@ value) property;

Arguments:

uint index: the index to insert the item at.
var@ value: the value to set.

Example:

void main() {
	json_array@ arr = parse_json("[]");
	arr[0] = "meow";
	alert("Info", "Cats say " + arr[0]);
}

Properties

empty

Determine if the JSON array is empty.

const bool json_array::empty;

Example:

void main() {
	json_array@ arr = parse_json("[]");
	json_array@ arr2 = parse_json("[1, 2, 3]");
	alert("First is empty", arr.empty ? "true" : "false");
	alert("Second is empty", arr2.empty ? "true" : "false");
}

escape_unicode

Determines the amount of escaping that occurs in JSON parsing.

bool json_array::escape_unicode;

Remarks:

If this property is true, escaping will behave like normal. If it's false, only the characters absolutely vital to JSON parsing are escaped.

json_object

Methods

clear

Clears the JSON object completely.

void json_object::clear();

Example:

void main() {
	string data = """{"numbers": [1, 2, 3, 4, 5]}""";
	json_object@ o = parse_json(data);
	alert("Before being cleared", o.stringify());
	o.clear();
	alert("After being cleared", o.stringify());
}

exists

Determine if a key exists in the JSON object.

bool json_object::exists(const string&in key) const;

Arguments:

const string&in key: the key to search for.

Returns:

bool: true if the key exists, false if not.

Example:

void main() {
	string data = """{"engine": "NVGT"}""";
	json_object@ o = parse_json(data);
	alert("Info", (o.exists("engine") ? "The key exists" : "The key does not exist"));
}

get_keys

Get a list of all the keys in the JSON object.

string[]@ json_object::get_keys();

Returns:

string[]@: a handle to an array of strings containing all the keys of the JSON object.

Remarks:

Note that this function isn't recursive, you only get the keys for the object you're running this function on, not any child objects.

Example:

void main() {
	string data = """{"thing": 1, "other_thing": "test", "another": true}""";
	json_object@ o = parse_json(data);
	string[]@ keys = o.get_keys();
	alert("The keys are", join(keys, ", "));
}

is_array

Determine if the value with the given key is a JSON array or not.

bool json_object::is_array(string key);

Arguments:

string key: the key to query.

Returns:

bool: true if the value with the specified key is a JSON array, false otherwise.

Example:

void main() {
	string data = """{"classes": ["json_object", "json_array"]}""";
	json_object@ o = parse_json(data);
	alert("Info", o.is_array("classes") ? "array": "nonarray");
}

is_null

Determine if the value with the given key is null.

bool json_object::is_null(string key);

Arguments:

string key: the key to query.

Returns:

bool: true if the value with the specified key is null.

Example:

void main() {
	string data = """{"brain": null}""";
	json_object@ o = parse_json(data);
	alert("Info", o.is_null("brain") ? "null" : "not null");
}

is_object

Determine if the value with the given key is a JSON object or not.

bool json_object::is_object(string key);

Arguments:

string key: the key to query.

Returns:

bool: true if the value with the specified key is a JSON object, false otherwise.

Example:

void main() {
	string data = """{"json_object": {\}\}""";
	json_object@ o = parse_json(data);
	alert("Info", o.is_object("json_object") ? "Object" : "Non-object");
}

remove

Remove a value from the JSON object given a key.

void json_object::remove(const string&in key);

Arguments:

const string&in key: the key of the value to remove.

Example:

void main() {
	string data = """{"name": "Quin"}""";
	json_object@ o = parse_json(data);
	alert("Initial", o.stringify());
	o.remove("name");
	alert("After removal", o.stringify());
}

set

Set a value in a JSON object.

void json_object::set(const string&in key, var@ value);

Arguments:

const string&in key: the key to give the value.
var@ value: a handle to the value to be set.

Example:

void main() {
	json_object@ o = parse_json("{}");;
	o.set("nvgt_user", true);
	alert("Info", (bool(o["nvgt_user"]) ? "You are an NVGT user" : "You are not a regular NVGT user"));
}

size

Return the size of the JSON object.

uint json_object::size();

Remarks:

Note that this function returns the number of top-level keys; it's not recursive.

Example:

void main() {
	string data = """{"numbers": [1, 2, 3, 4, 5]}""";
	json_object@ o = parse_json(data);
	alert("Info", "The json object's size is " + o.size());
}

stringify

Return the JSON object as a string.

string json_object::stringify(int indent = 0, int step = -1);

Arguments:

int indent = 0: specifies how many spaces to use to indent the JSON. If 0, no indentation or formatting is performed.
int step = -1: the outwards indentation step, for example setting it to two would cause your outdents to only be two spaces. -1 (the default) keeps it how it is, normally you don't need to use this parameter.

Returns:

string: the JSON object as a string.

Example:

void main() {
	string data = """{"name": "Quin", "age": 18}""";
	json_object@ o = parse_json(data);
	alert("JSON object", o.stringify(4));
}

Operators

get_opIndex

Get a value out of the JSON object with literal syntax, for example json["key"].

var@ json_object::get_opIndex(const string&in key) property;

Arguments:

const string&in key: the key of the object to get.

Returns:

var@: a handle to the object, or null if not found.

Example:

void main() {
	string data = """{"name": "Quin", "age": 18}""";
	json_object@ o = parse_json(data);
	alert("Info", o["name"] + " is " + o["age"]);
}

opCall

Get a value out of a JSON object using a query.

var@ json_object::opCall(const string&in query);

Arguments:

const string&in query: the JSON query (see the remarks section for details).

Returns:

var@: a handle to the object, null if not found.

Remarks:

Queries are formatted like so:

first_field.subfield.subfield

It can be as nested as you like.

This method also works on json_array's, and you access array indexes just with their raw numbers, like so:

world.players.0

Example:

void main() {
	string data = """{"countries":{"us":["Colorado", "Kansas", "Minnesota"]\}\}""";
	json_object@ o = parse_json(data);
	string locations = o("countries.us");
	alert("My favorite states are", locations);
}

set_opIndex

Set a value in the JSON object with a particular key.

void json_object::set_opIndex(const string&in key, var@ value) property;

Arguments:

const string&in key: the key of the object.
var@ value: the value to set.

Example:

void main() {
	json_object@ o = parse_json("{}");
	o["name"] = "Quin";
	alert("Hi", "I am " + o["name"]);
}

Properties

escape_unicode

Determines the amount of escaping that occurs in JSON parsing.

bool json_object::escape_unicode;

Remarks:

If this property is true, escaping will behave like normal. If it's false, only the characters absolutely vital to JSON parsing are escaped.

pack_file

A pack file stores many files inside one larger file, usually so that a game's sounds and other assets can be distributed together and optionally encrypted.

pack_file();

Remarks:

A pack_file object is inactive when created. Call create() to start writing a new pack, or open() to read an existing one. A pack is either being written or being read, never both: you cannot add files to a pack that was opened for reading, and you cannot read files out of a pack until it has been written, closed, and opened again.

Packs can be encrypted by passing a key to create(). The same key must then be passed to open(), otherwise opening fails.

Packs can also be embedded into your compiled game with the #pragma embed packname.dat directive. To open an embedded pack, put an asterisk before its name, for example open("*packname.dat"). For BGT compatibility, opening a pack called * opens the first embedded pack. This also works when you run the script from source, in which case the pack is read from disk instead.

Functions that load assets, such as sound::load(), accept a pack_interface handle. A pack_file converts to a pack_interface implicitly, so you can pass one directly or assign it to sound_default_pack. To get the pack_file back from a pack_interface handle, use cast<pack_file@>().

Files inside a pack are identified by name. Names are case sensitive, must be valid UTF-8, and must be unique within the pack.

This class replaces the older pack class, which is now only available through the legacy_sound plugin. The two classes use different file formats.

Example:

void main() {
	pack_file p;
	if (!p.create("example.dat")) {
		alert("Error", "Unable to create the pack.");
		return;
	}
	p.add_memory("greeting.txt", "Hello from inside a pack!");
	p.close();
	if (!p.open("example.dat")) {
		alert("Error", "Unable to open the pack.");
		return;
	}
	datastream@ ds = p.get_file("greeting.txt");
	alert("greeting.txt", ds.read());
	ds.close(); // The pack file can't be deleted while a stream still has it open.
	p.close();
	file_delete("example.dat");
}

Methods

add_file

Copy a file from disk into a pack that is open for writing.

bool pack_file::add_file(const string&in filename, const string&in internal_name);

Arguments:

const string&in filename: the path of the file on disk to add.
const string&in internal_name: the name the file should have inside the pack.

Returns:

bool: true if the file was added, false otherwise.

Remarks:

This fails if the pack was not opened with create(), if the file on disk can't be read, or if the pack already contains a file with the given internal name. Files cannot be replaced or removed once added.

The internal name can be anything, including a path such as sounds/step.ogg. Slashes have no special meaning inside a pack, they are simply part of the name.

Example:

void main() {
	file f;
	f.open("hello.txt", "wb");
	f.write("Hello from disk!");
	f.close();
	pack_file p;
	p.create("example.dat");
	if (!p.add_file("hello.txt", "texts/hello.txt")) alert("Error", "Unable to add the file.");
	p.close();
	p.open("example.dat");
	alert("texts/hello.txt", p.get_file("texts/hello.txt").read());
	p.close();
	file_delete("hello.txt");
	file_delete("example.dat");
}

add_memory

Add a file to a pack that is open for writing, using data from a string.

bool pack_file::add_memory(const string&in internal_name, const string&in data);

Arguments:

const string&in internal_name: the name the file should have inside the pack.
const string&in data: the contents of the new file.

Returns:

bool: true if the data was added, false otherwise.

Remarks:

This fails if the pack was not opened with create(), or if the pack already contains a file with the given internal name. Files cannot be replaced or removed once added.

Example:

void main() {
	pack_file p;
	p.create("example.dat");
	p.add_memory("level1.txt", "a maze of twisty little passages");
	alert("Adding a second file with the same name", p.add_memory("level1.txt", "something else") ? "succeeded" : "failed");
	p.close();
	file_delete("example.dat");
}

add_stream

Add a file to a pack that is open for writing, using data read from a datastream.

bool pack_file::add_stream(const string&in internal_name, datastream@ ds);

Arguments:

const string&in internal_name: the name the file should have inside the pack.
datastream@ ds: the stream to read the file's contents from.

Returns:

bool: true if the data was added, false otherwise.

Remarks:

The stream is read from its current position until its end, so anything before the current position is not included. This lets you add any kind of datastream to a pack, such as a file, a decoder, or a stream from another pack, without loading all of it into memory first.

This fails if the pack was not opened with create(), if the stream is null or can't be read from, or if the pack already contains a file with the given internal name.

Example:

void main() {
	datastream ds("HEADERthe actual data");
	ds.seek(6); // Skip the header.
	pack_file p;
	p.create("example.dat");
	p.add_stream("data.bin", ds);
	p.close();
	p.open("example.dat");
	alert("data.bin", p.get_file("data.bin").read());
	p.close();
	file_delete("example.dat");
}

close

Close the pack, finishing it first if it was being written.

bool pack_file::close();

Returns:

bool: true if a pack was open and is now closed, false if no pack was open.

Remarks:

When a pack that was opened with create() is closed, its table of contents is written to the file. A pack that was never closed cannot be opened again. Packs are also closed automatically when the pack_file object is destroyed, or when create() or open() is called on the same object.

Any datastreams previously returned by get_file() stay usable after the pack is closed.

Example:

void main() {
	pack_file p;
	p.create("example.dat");
	p.add_memory("data.txt", "some data");
	alert("Closing an open pack", p.close() ? "succeeded" : "failed");
	alert("Closing it again", p.close() ? "succeeded" : "failed");
	file_delete("example.dat");
}

create

Create a new pack file on disk and open it for writing.

bool pack_file::create(const string&in filename, const string&in key = "");

Arguments:

const string&in filename: the path of the pack file to create.
const string&in key = "": an optional key used to encrypt the pack. If empty, the pack is not encrypted.

Returns:

bool: true if the pack was created, false otherwise.

Remarks:

If a file already exists at the given path, it is replaced. If this object already had a pack open, that pack is closed first.

While the pack is open for writing, add files to it with add_file(), add_memory() or add_stream(). The pack is not complete until close() is called or the object is destroyed, because that is when its table of contents is written.

If you pass a key here, you must pass the same key to open() to read the pack later.

Example:

void main() {
	pack_file p;
	if (!p.create("secret.dat", "my password")) {
		alert("Error", "Unable to create the pack.");
		return;
	}
	p.add_memory("note.txt", "Nobody can read this without the key.");
	p.close();
	alert("Encrypted pack opens without the key", p.open("secret.dat") ? "yes" : "no");
	alert("Encrypted pack opens with the key", p.open("secret.dat", "my password") ? "yes" : "no");
	p.close();
	file_delete("secret.dat");
}

extract_file

Copy a file out of the pack and save it to disk.

bool pack_file::extract_file(const string&in internal_name, const string&in file_on_disk);

Arguments:

const string&in internal_name: the name of the file inside the pack.
const string&in file_on_disk: the path to save the file to. An existing file at this path is replaced.

Returns:

bool: true if the file was extracted, false otherwise.

Remarks:

This fails if the pack is not open for reading, if it doesn't contain the requested file, or if the destination can't be written.

Example:

void main() {
	pack_file p;
	p.create("example.dat");
	p.add_memory("readme.txt", "Thanks for playing!");
	p.close();
	p.open("example.dat");
	if (p.extract_file("readme.txt", "readme_extracted.txt")) {
		file f("readme_extracted.txt", "rb");
		alert("Extracted file", f.read());
		f.close();
		file_delete("readme_extracted.txt");
	}
	p.close();
	file_delete("example.dat");
}

file_exists

Determine whether a file with a given name exists in the pack.

bool pack_file::file_exists(const string&in filename);

Arguments:

const string&in filename: the internal name of the file to look for.

Returns:

bool: true if the pack contains the file, false if not or if no pack is open.

Remarks:

This works for packs opened with either create() or open(). Names are case sensitive, so music.ogg and Music.ogg are different files.

Example:

void main() {
	pack_file p;
	p.create("example.dat");
	p.add_memory("music.ogg", "not really music");
	alert("music.ogg exists", p.file_exists("music.ogg") ? "yes" : "no");
	alert("Music.ogg exists", p.file_exists("Music.ogg") ? "yes" : "no");
	p.close();
	file_delete("example.dat");
}

get_file

Get a datastream for reading a file from the pack.

datastream@ pack_file::get_file(const string&in filename, const string&in encoding = "", int byteorder = STREAM_BYTE_ORDER_NATIVE);

Arguments:

const string&in filename: the internal name of the file to read.
const string&in encoding = "": the text encoding to use when reading strings from the stream (see the datastream class).
int byteorder = STREAM_BYTE_ORDER_NATIVE: the byte order to use when reading binary numbers from the stream.

Returns:

datastream@: a stream for reading the file. If the file doesn't exist or the pack is not open for reading, an inactive stream is returned instead, so check its active property.

Remarks:

Each stream is independent of the pack_file object, so you can read several files at once, and a stream stays readable after the pack is closed. The stream supports seeking, and its positions are relative to the start of the file inside the pack.

Data is read from disk as you read from the stream rather than all at once, so this is suitable for large files.

Each stream keeps the pack file open on disk until the stream is closed or destroyed. On some platforms, including Windows, this means the pack can't be deleted or replaced while any of its streams are still in use.

Example:

void main() {
	pack_file p;
	p.create("example.dat");
	p.add_memory("numbers.txt", "0123456789");
	p.close();
	p.open("example.dat");
	datastream@ ds = p.get_file("numbers.txt");
	ds.seek(4);
	alert("3 characters from position 4", ds.read(3));
	datastream@ missing = p.get_file("missing.txt");
	alert("Stream for a missing file is active", missing.active ? "yes" : "no");
	ds.close(); // The pack file can't be deleted while a stream still has it open.
	p.close();
	file_delete("example.dat");
}

get_file_size

Get the size of a file in the pack.

int64 pack_file::get_file_size(const string&in filename);

Arguments:

const string&in filename: the internal name of the file.

Returns:

int64: the size of the file in bytes, or -1 if the file doesn't exist or no pack is open.

Remarks:

This works for packs opened with either create() or open().

Example:

void main() {
	pack_file p;
	p.create("example.dat");
	p.add_memory("data.txt", "1234567890");
	alert("Size of data.txt", p.get_file_size("data.txt") + " bytes");
	alert("Size of a missing file", p.get_file_size("missing.txt"));
	p.close();
	file_delete("example.dat");
}

list_files

Get the names of every file in the pack.

string[]@ pack_file::list_files() const;

Returns:

string[]@: a handle to an array containing the internal name of every file in the pack. The array is empty if no pack is open.

Remarks:

This works for packs opened with either create() or open(). The order of the names is not guaranteed, so sort the array if you need a particular order.

Example:

void main() {
	pack_file p;
	p.create("example.dat");
	p.add_memory("c.txt", "");
	p.add_memory("a.txt", "");
	p.add_memory("b.txt", "");
	string[]@ names = p.list_files();
	names.sort_ascending();
	alert("Files in the pack", join(names, ", "));
	p.close();
	file_delete("example.dat");
}

open

Open an existing pack file for reading.

bool pack_file::open(const string&in filename, const string&in key = "", uint64 pack_offset = 0, uint64 pack_size = 0);

Arguments:

const string&in filename: the path of the pack file to open, or the name of an embedded pack prefixed with an asterisk (see remarks).
const string&in key = "": the key the pack was encrypted with, or an empty string if it is not encrypted.
uint64 pack_offset = 0: the position in the file where the pack begins, if the pack is stored inside a larger file.
uint64 pack_size = 0: the size of the pack in bytes, if the pack is stored inside a larger file. Leave both this and pack_offset at 0 to treat the whole file as the pack.

Returns:

bool: true if the pack was opened, false otherwise.

Remarks:

Opening fails if the file doesn't exist, isn't a pack created by pack_file, is damaged, or if the key is wrong or missing. If this object already had a pack open, that pack is closed first, even if opening the new one fails.

To open a pack embedded with #pragma embed, prefix its name with an asterisk, for example open("*sounds.dat"). A filename of just * opens the first embedded pack, for BGT compatibility.

The pack_offset and pack_size arguments let you read a pack that is stored inside some other file. The data in that range must be an entire pack exactly as create() wrote it.

Example:

void main() {
	// Create a small pack so that there's something to open.
	pack_file p;
	p.create("example.dat");
	p.add_memory("a.txt", "first file");
	p.add_memory("b.txt", "second file");
	p.close();
	if (!p.open("example.dat")) {
		alert("Error", "Unable to open the pack.");
		return;
	}
	alert("Files in the pack", join(p.list_files(), ", "));
	p.close();
	file_delete("example.dat");
}

Properties

active

Determine whether the pack is currently open, either for reading or for writing.

const bool pack_file::active;

Example:

void main() {
	pack_file p;
	alert("Active before create", p.active ? "yes" : "no");
	p.create("example.dat");
	alert("Active after create", p.active ? "yes" : "no");
	p.close();
	file_delete("example.dat");
}

file_count

The number of files in the pack.

const int64 pack_file::file_count;

Remarks:

This is -1 if no pack is open. While a pack is being written, it counts the files added so far.

Example:

void main() {
	pack_file p;
	p.create("example.dat");
	p.add_memory("a.txt", "a");
	p.add_memory("b.txt", "b");
	alert("Files in the pack", p.file_count);
	p.close();
	file_delete("example.dat");
}

pack_name

The filename of the pack that is currently open.

const string pack_file::pack_name;

Remarks:

This is the path the pack was opened or created with, exactly as it was passed. For an embedded pack, it is the path of the file the pack was actually read from. It is empty if no pack has been opened yet.

Example:

void main() {
	pack_file p;
	p.create("example.dat");
	alert("Pack name", p.pack_name);
	p.close();
	file_delete("example.dat");
}

regexp

The regexp object allows for the easy usage of regular expressions in NVGT.

regexp(const string&in pattern, int options = RE_UTF8);

Arguments:

const string&in pattern: the regular expression's pattern (see remarks).
int options = RE_UTF8: a combination of any of the values from the regexp_options enum.

Remarks:

Regular expressions are a language used for matching, substituting, and otherwise manipulating text. To learn about the regular expression syntax that nVGT uses (called PCRE), see this link: https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions

Example:

void main() {
	regexp re("^[a-z]{2,4}$"); // Will match any lowercase alphabetical string between 2 and 4 characters in length.
	string compare = input_box("Text", "Enter the text to check against the regular expression.");
	if (compare.empty()) {
		alert("Regular expression tester", "You didn't type a string to test.");
		exit(1);
	}
	bool matches = re.match(compare);
	alert("The regular expression", matches ? "matches" : "does not match");
}

methods

match

Determine if the regular expression matches against a particular string or not.

bool regexp::match(const string&in subject, uint64 offset = 0);
bool regexp::match(const string&in subject, uint64 offset, int options);

Arguments (1):

const string&in subject: the string to compare against.
uint64 offset = 0: the offset to start the comparison at.

Arguments (2):

const string&in subject: the string to compare against.
uint64 offset: the offset to start the comparison at.
int options: any combination of the values found in the regexp_options enum.

Returns:

bool: true if the regular expression matches the given string, false if not.

Enums

regexp_options

This enum holds various constants that can be passed to the regular expression classes in order to change their behavior.

Notes:

Portions of this regexp_options documentation were Copied from POCO header files.

Options marked [ctor] can be passed to the constructor of regexp objects.
Options marked [match] can be passed to match, extract, split and subst.
Options marked [subst] can be passed to subst.

See the PCRE documentation for more information.

Constants:

RE_CASELESS: case insensitive matching (/i) [ctor]
RE_MULTILINE: enable multi-line mode; affects ^ and $ (/m) [ctor]
RE_DOTALL: dot matches all characters, including newline (/s) [ctor]
RE_EXTENDED: totally ignore whitespace (/x) [ctor]
RE_ANCHORED: treat pattern as if it starts with a ^ [ctor, match]
RE_DOLLAR_END_ONLY: dollar matches end-of-string only, not last newline in string [ctor]
RE_EXTRA: enable optional PCRE functionality [ctor]
RE_NOT_BOL: circumflex does not match beginning of string [match]
RE_NOT_EOL: $ does not match end of string [match]
RE_UNGREEDY: make quantifiers ungreedy [ctor]
RE_NOT_EMPTY: empty string never matches [match]
RE_UTF8: assume pattern and subject is UTF-8 encoded [ctor]
RE_NO_AUTO_CAPTURE: disable numbered capturing parentheses [ctor, match]
RE_NO_UTF8_CHECK: do not check validity of UTF-8 code sequences [match]
RE_FIRSTLINE: an unanchored pattern is required to match before or at the first newline in the subject string, though the matched text may continue over the newline [ctor]
RE_DUPNAMES: names used to identify capturing subpatterns need not be unique [ctor]
RE_NEWLINE_CR: assume newline is CR ('\r'), the default [ctor]
RE_NEWLINE_LF: assume newline is LF ('\n') [ctor]
RE_NEWLINE_CRLF: assume newline is CRLF ("\r\n") [ctor]
RE_NEWLINE_ANY: assume newline is any valid Unicode newline character [ctor]
RE_NEWLINE_ANY_CRLF: assume newline is any of CR, LF, CRLF [ctor]
RE_GLOBAL: replace all occurrences (/g) [subst]
RE_NO_VARS: treat dollar in replacement string as ordinary character [subst]

Functions

ascii_to_character

Return the character that corresponds to the given ascii value.

string ascii_to_character(uint8 ascii);

Arguments:

uint8 ascii: the ascii value to convert.

Returns:

string: the character for the given ascii value.

Example:

void main() {
	uint8 ascii = parse_int(input_box("ASCII value", "Enter the ascii value to convert."));
	alert("Info", ascii + " has a value of " + ascii_to_character(ascii));
}

character_to_ascii

Return the ascii value for the given character.

uint8 character_to_ascii(const string&in character);

Arguments:

const string&in character: the character to convert.

Returns:

uint8: the ascii value for the given character.

Remarks:

If a string containing more than one character is passed as input to this function, only the left-most character is checked.

If an empty string is passed, the function returns 0.

Example:

void main() {
	string character = input_box("Character", "Enter a character to convert");
	if (character.is_empty()) {
		alert("Error", "You did not type anything.");
		exit();
	}
	if (character.length() != 1) { // The user typed more than one character.
		alert("Error", "You must only type a single character.");
		exit();
	}
	alert("Info", character + " has an ascii value of " + character_to_ascii(character));
}

join

turn an array into a string, with each element being separated by the given delimiter.

string join(const string[]@ elements, const string&in delimiter);

Arguments:

const string[]@ elements: a handle to the array to join.
const string&in delimiter: the delimiter used to separate each element in the array (can be empty).

Returns:

string: the given array as a string.

Remarks:

If an empty array is passed, a blank string is returned.

The delimiter is not appended to the end of the last item in the returned string. For example if an array contains [1, 2, 3] and you join it with a delimiter of . (period), the result would be "1.2.3" without an extra delimiter appended.

Example:

void main() {
	string[] names = {"Sam", "Quin", "Patrick"};
	string people = join(names, ", ");
	alert("Info", people);
}

number_to_words

Convert a number into its string equivalent, for example, one thousand four hundred and fifty six.

string number_to_words(int64 the_number, bool include_and = true);

Arguments:

int64 the_number: the number to convert.
bool include_and = true: whether or not to include the word "and" in the output.

Returns:

string: the specified number, converted to a readable string.

Remarks:

At this time, this function only produces English results.

Example:

void main() {
	int64 num = random(1000, 100000);
	string result = number_to_words(num);
	alert("Info", num + " as a string is " + result);
}

regexp_match

Test if the text matches the specified regular expression.

bool regexp_match(const string&in text, const string&in pattern);

Arguments:

const string&in text: the text to compare against the regular expression.
const string&in pattern: the regular expression to match.

Returns:

bool: true if the text matches the given regular expression, false otherwise.

Remarks:

If you would like a lower level interface to regular_expressions in NVGT, check out the regexp class which this function more or less wraps.

To learn more about regular expressions, visit: https://en.wikipedia.org/wiki/Regular_expression

Example:

void main() {
	bool match = regexp_match("Test", "^[a-zA-Z]+$");
	alert("the regular expression", match ? "matches" : "does not match");
}

string_base32_decode

Decodes a string from base32.

string string_base32_decode(const string&in the_data);

Arguments:

const string&in the_data: The data that is to be decoded.

Returns:

String: The decoded string on success or an empty string on failure.

Remarks:

You can learn more about the base32 format here.

Example:

void main() {
	string text = input_box("Text", "Enter the text to decode.");
	if (text.is_empty()) {
		alert("Error", "You did not type any text.");
		exit();
	}
	alert("Info", string_base32_decode(text));
}

string_base32_encode

Encodes a string as base32.

string string_base32_encode(const string&in the_data);

Arguments:

const string&in the_data: The data that is to be encoded.

Returns:

String: The encoded string on success or an empty string on failure.

Remarks:

You can learn more about the base32 format here.

Example:

void main() {
	string text = input_box("Text", "Enter the text to encode.");
	if (text.is_empty()) {
		alert("Error", "You did not type any text.");
		exit();
	}
	alert("Info", string_base32_encode(text));
}

string_base32_normalize

Normalize a string to conform to the base32 spec.

string string_base32_normalize(const string&in the_data);

Arguments:

const string&in the_data: the string to normalize.

Returns:

string: the normalized string.

Remarks:

The primary thing this function does is to skip separators, convert all letters to uppercase, and make sure the length is a multiple of 8.

To learn more about base32, click here.

Example:

void main() {
	string text = input_box("Text", "Enter the text to normalize.");
	if (text.is_empty()) {
		alert("Error", "You didn't type anything.");
		exit();
	}
	alert("Info", string_base32_normalize(text));
}

string_base64_decode

Decodes a string which has previously been encoded in base64.

string string_base64_decode(const string&in the_data, string_base64_options options = STRING_BASE64_PADLESS);

Arguments:

const string&in the_data: The data that is to be decoded.
string_base64_options options = STRING_BASE64_PADLESS: A bitwise of options that control the behavior of the decoding (see remarks).

Returns:

String: The decoded string on success or an empty string on failure.

Remarks:

The following options may be passed to the options argument of this function:

STRING_BASE64_DEFAULT: The defaults passed to the string_base64_encode function.
STRING_BASE64_URL: Use base64 URL encoding as opposed to the / and = characters.
STRING_BASE64_PADLESS: Allows decoding even if the string does not end with = padding characters.

You can learn more about base64 here.

Example:

void main() {
	alert("example", string_base64_decode("aGVsbG8=")); // Should print "hello".
}

string_base64_encode

Encodes a string as base64.

string string_base64_encode(const string&in the_data, string_base64_options options = STRING_BASE64_DEFAULT);

Arguments:

const string&in the_data: The data that is to be encoded.
string_base64_options options = STRING_BASE64_DEFAULT: A bitwise of options that control the behavior of the encoding (see remarks).

Returns:

String: The encoded string on success or an empty string on failure.

Remarks:

The following options may be passed to the options argument of this function:

STRING_BASE64_DEFAULT: The default options (i.e. insert padding and do not use URL encoding).
STRING_BASE64_URL: Use base64 URL encoding as opposed to the / and = characters.
STRING_BASE64_PADLESS: Allows decoding even if the string does not end with = padding characters.

You can learn more about base64 here.

Example:

void main() {
	alert("example", string_base64_encode("Hello")); // Should print SGVsbG8=
}