\nchar haystack = "Hello World";\nint font = <font index>;\n\nint result = strwidth(haystack, font);\n<\/pre><\/div>\n\n\nAccepts a string and a font index. Returns the total width in pixels. For example, if the font’s character width is 10 pixels and the string has 11 characters, the width returned is 110 pixels.<\/p>\n\n\n\n
Arrays\u200b<\/h2>\n\n\n\n
OpenBOR supports indexed and string-keyed arrays. In actuality, an OpenBOR array is a defined object occupying the global space, so you will need to treat it as such for purposes of initializing, referencing, and cleanup (see free()).<\/p>\n\n\n\n
While they may behave similarly in script, under the hood the two types of arrays behave very differently, and you should tailor your data structures and scripts accordingly.<\/p>\n\n\n\n
Indexed<\/h3>\n\n\n\n
Indexed arrays are essentially C arrays, meaning they are zero indexed, concurrent groups of elements with a contiguous space allocated in the hardware platform’s memory. This makes indexed arrays blazing fast and memory efficient for accessing and modifying existing elements. However, arrays cannot be resized without reallocating a whole new array and copying existing elements over, so it is important to figure out how many elements you will need and avoid inserts or deletes during gameplay. <\/p>\n\n\n\n
String-Keyed<\/h3>\n\n\n\n
Sometimes called literal arrays. String-keyed arrays are not actually arrays all, but a double linked list with hash map acceleration. They are thus not less memory efficient and not as fast as indexed arrays, but are highly flexible and can shrink or grow without penalty.<\/p>\n\n\n\n
Switching Types<\/h3>\n\n\n\n
You do not actually switch array types. When you allocate an array, OpenBOR creates the indexed array first. If you then add()<\/code> or set()<\/code> with a string key, OpenBOR builds the linked list along-side the original indexed array. This is why when planning to use string keys, you should allocate 0<\/code>.<\/p>\n\n\n\nWarning: It is technically possible to treat an array as both index and string-keyed \u2013 but you should never do this. Treat an array as either string-keyed or indexed, not both. Mixing them can produce confusing size results, broken assumptions, erroneous output, and hard-to-track bugs.<\/p>\n\n\n\n
Tips<\/h3>\n\n\n\n\n- Don’t forget indexed keys are 0 indexed.<\/li>\n\n\n\n
- You can nest array pointers to create multidimensional data structures. Nested arrays can safely have different key types than their parents. <\/li>\n<\/ul>\n\n\n\n
Functions<\/h3>\n\n\n\nadd()\u200b<\/h4>\n\n\n\nvoid key = 0; \/\/ Int or string.\nvoid value = 0; \/\/ Any value type.\n\nadd(void array_pointer, index, value);\n<\/pre><\/div>\n\n\n
\n- Indexed \u2013<\/strong> Inserts value at
key<\/code>. Key must be from 0<\/code> through size(array_pointer)<\/code>. Resizes the array by one and shifts all indexes from key<\/code> upward. <\/li>\n\n\n\n- String-Keyed \u2013<\/strong> Creates a named entry for
key<\/code> with value<\/code>, or updates value<\/code> if key<\/code> already exists. Same behavior as set()<\/code>.<\/li>\n<\/ul>\n\n\n\narray()\u200b<\/h4>\n\n\n\nvoid array_pointer = array(int size);\n<\/pre><\/div>\n\n\nAllocates an array with int size<\/code> initial indexed elements and returns the array pointer.<\/p>\n\n\n\n\n- Indexed \u2013<\/strong> Allocate the number of elements you expect to use.<\/li>\n\n\n\n
- String-Keyed \u2013<\/strong> Use
array(0)<\/code>, because string-keyed entries are stored separately from indexed block.<\/li>\n<\/ul>\n\n\n\ndelete()\u200b<\/h4>\n\n\n\nvoid index = 0; \/\/ Int or string.\n\ndelete(void array_pointer, index);\n<\/pre><\/div>\n\n\n
\n- Indexed \u2013<\/strong> Deletes the target element, resizes the array, and shifts all higher indexes down.<\/li>\n\n\n\n
- String-Keyed \u2013<\/strong> Removes the named entry for
key<\/code>.<\/li>\n<\/ul>\n\n\n\nAvoid using delete()<\/code> during active gameplay. For indexed arrays, delete()<\/code> causes resizing and shifting. For string-keyed arrays, it changes the named list structure. Both create avoidable memory churn.
Tip: <\/strong>You can set NULL()<\/code> to clear a value without churn. <\/p>\n\n\n\nget()\u200b<\/h4>\n\n\n\nvoid key = 0; \/\/ Int or string.\n\nvoid value = get(void array_pointer, key); \/\/ Can return any type.\n<\/pre><\/div>\n\n\nReturns value at key<\/code>, or NULL()<\/code> if the entry does not exist.<\/p>\n\n\n\n\n- String-Keyed<\/strong> \u2013 Retrieves by string key.<\/li>\n\n\n\n
- Indexed<\/strong> \u2013 Retrieves by integer index.<\/li>\n<\/ul>\n\n\n\n
isArray()\u200b<\/h4>\n\n\n\nint value = isarray(void object_pointer);\n<\/pre><\/div>\n\n\nVersion 4.0+ only. Returns 1<\/code> if pointer is an array. 0<\/code> otherwise.<\/p>\n\n\n\nisFirst()\u200b<\/h4>\n\n\n\nint value = isfirst(void array_pointer);\n<\/pre><\/div>\n\n\nString-keyed only. Returns 1<\/code> if the internal cursor is at first node. 0<\/code> otherwise.<\/p>\n\n\n\nislast()\u200b<\/h4>\n\n\n\nint value = islast(void array_pointer);\n<\/pre><\/div>\n\n\nString-Keyed only.Returns 1<\/code> if the internal cursor is at last node. 0<\/code> otherwise.<\/p>\n\n\n\nkey()\u200b<\/h4>\n\n\n\nvoid value = key(void array_pointer); \/\/ String.\n<\/pre><\/div>\n\n\nString-Keyed only. Returns the string key at current cursor position.<\/p>\n\n\n\n
next()\u200b<\/h4>\n\n\n\nint success = next(void array_pointer);\n<\/pre><\/div>\n\n\nString-Keyed only. Attempts to move cursor to next node in order. Returns 1<\/code> on success, 0<\/code> if already at last node.<\/p>\n\n\n\nprevious()\u200b<\/h4>\n\n\n\nint success = previous(void array_pointer);\n<\/pre><\/div>\n\n\nString-keyed only. Attempts to move cursor to previous node in order. Returns 1<\/code> on success, 0<\/code> if already at first node.<\/p>\n\n\n\nreset()\u200b<\/h4>\n\n\n\nint success = reset(void array_pointer);\n<\/pre><\/div>\n\n\nString-Keyed only. Attempts to move cursor to first node in order. Returns 1<\/code> on success, 0<\/code> if array has no nodes.<\/p>\n\n\n\nset()\u200b<\/h4>\n\n\n\nvoid key = 0; \/\/ Int or string.\nvoid value = 0; \/\/ Any type.\n\nset(void array_pointer, index, value);\n<\/pre><\/div>\n\n\n
\n- Indexed \u2013<\/strong> Set target
key<\/code> to value. If key<\/code> does not exist, resizes array to accommodate key<\/code> before setting value.<\/li>\n\n\n\n- String-Keyed \u2013<\/strong> Creates a named entry for
key<\/code> with value<\/code>, or updates value<\/code> if key<\/code> already exists. Same behavior as add()<\/code>.<\/li>\n<\/ul>\n\n\n\nFor indexed arrays, prefer set()<\/code> over add()<\/code> when you already know the slot you want to write.<\/p>\n\n\n\nsize()\u200b<\/h4>\n\n\n\nint array_size = size(void array_pointer);\n<\/pre><\/div>\n\n\n
\n- Indexed \u2013<\/strong> Returns current number of elements in the array.<\/li>\n\n\n\n
- String-Keyed \u2013<\/strong> Returns number of named entries.<\/li>\n<\/ul>\n\n\n\n
Caution: If you mistakenly allocate >0<\/code> entries to an array you intend for string keys, size()<\/code> will return that allocated number of elements until you add or set a string-keyed node. Always allocate 0<\/code> for string-keyed arrays, and never mix key types.<\/p>\n\n\n\nvalue()\u200b<\/h4>\n\n\n\nvoid value = value(void array_pointer); \/\/ Any type.\n<\/pre><\/div>\n\n\nString-Keyed only.Returns value at current cursor position.<\/p>\n\n\n\n
Cleanup<\/h2>\n\n\n\nDeleting Variables<\/h3>\n\n\n\n
To delete any variable, assign it a NULL()<\/code> value. OpenBOR will destroy the variable and free the memory it used.<\/p>\n\n\n\nsetglobalvar("some_name", NULL())\n<\/pre><\/div>\n\n\nYou can also remove an string-keyed array element by setting its value to NULL()<\/code>. The node will remain allocated until the array is freed, but OpenBOR will treat it as removed for purposes of size()<\/code> and iteration.<\/p>\n\n\n\nIndexed array elements can cleared, but not removed with NULL()<\/code>. <\/p>\n\n\n\nFreeing Objects<\/h3>\n\n\n\n
If the variable was pointing to an object of some type (i.e. a pointer), you may first want to delete the object it is pointing to. Otherwise, the object continues to exist in memory with no variable to reference it. To do this, use the free()<\/code> function. In the example below, we load a sprite into memory, then delete the sprite, and afterward delete the variable that pointed to it.<\/p>\n\n\n\nvoid load_sprite() {\n\n\/* Load sprite into memory and get its pointer so we can work with it. *\/\n void sprite = loadsprite("data\/some_folder\/some_sprite.png");\n\n\/* Store the pointer into a localvar so other functions can use it. *\/\n setlocalvar("sprite_name", sprite);\n\n}\n\nvoid free_sprite() {\n\n\/* Get the sprite pointer so we can work with it. *\/\n void sprite = getlocalvar("sprite_name");\n\n\/* Remove the sprite from memory. *\/\n free(sprite);\n\n\/* Delete the variable that held sprite pointer. *\/\n setlocalvar("sprite_name", NULL());\n}\n<\/pre><\/div>\n\n\nLimitations<\/h2>\n\n\n\nVariables In Use<\/h3>\n\n\n\n
There is no hard code limit for the number of variables you may have in use. It’s still a good idea to only allocate what you need and clean up what you don’t, since every active variable consumes memory.<\/p>\n\n\n\n
Variable Length<\/h3>\n\n\n\n
Prior to release 4539, variables in OpenBOR Script were limited to 63 characters in length. Note that’s length<\/em>, not value<\/em> – so it really only matters for strings. Should the length exceed 63, the remaining characters are truncated and lost. As of 4539+ the limit is now 127.<\/p>\n","protected":false},"excerpt":{"rendered":"Variables are named identifiers that contain a value. They are a basic building block of script.<\/p>\n","protected":false},"author":1,"featured_media":1322,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_jetpack_memberships_contains_paid_content":false,"footnotes":""},"categories":[328,2],"tags":[383,388,387,376,385,372,371,373,396,395,394,393,375,390,391,386,370,369,374,384,377,366,368,378,379,381,380,382,365,392,389,4,3],"class_list":["post-4","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-openbor","category-script","tag-array","tag-func_add","tag-obor_func_delete","tag-obor_func_free-2","tag-obor_func_get","tag-obor_func_getentityvar-2","tag-obor_func_getglobalvar-2","tag-obor_func_getlocalvar-2","tag-obor_func_isarray","tag-obor_func_isfirst","tag-obor_func_islast","tag-obor_func_key","tag-obor_func_null-2","tag-obor_func_previous","tag-obor_func_reset","tag-obor_func_set","tag-obor_func_setentityvar-2","tag-obor_func_setglobalvar-2","tag-obor_func_setlocalvar-2","tag-obor_func_size","tag-obor_func_strinfirst","tag-obor_func_string_to_float","tag-obor_func_string_to_int","tag-obor_func_strinlast","tag-obor_func_strleft","tag-obor_func_strlength","tag-obor_func_strright","tag-obor_func_strwidth","tag-obor_func_typeof-2","tag-obor_func_value","tag-next","tag-openbor-script","tag-variables"],"revision_note":"","jetpack_featured_media_url":"https:\/\/i0.wp.com\/chronocrash.com\/obor\/wiki\/wp-content\/uploads\/2023\/12\/c_scripting.png?fit=100%2C100&ssl=1&wsr","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/chronocrash.com\/obor\/wiki\/wp-json\/wp\/v2\/posts\/4","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/chronocrash.com\/obor\/wiki\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/chronocrash.com\/obor\/wiki\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/chronocrash.com\/obor\/wiki\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/chronocrash.com\/obor\/wiki\/wp-json\/wp\/v2\/comments?post=4"}],"version-history":[{"count":4,"href":"https:\/\/chronocrash.com\/obor\/wiki\/wp-json\/wp\/v2\/posts\/4\/revisions"}],"predecessor-version":[{"id":1463,"href":"https:\/\/chronocrash.com\/obor\/wiki\/wp-json\/wp\/v2\/posts\/4\/revisions\/1463"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/chronocrash.com\/obor\/wiki\/wp-json\/wp\/v2\/media\/1322"}],"wp:attachment":[{"href":"https:\/\/chronocrash.com\/obor\/wiki\/wp-json\/wp\/v2\/media?parent=4"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/chronocrash.com\/obor\/wiki\/wp-json\/wp\/v2\/categories?post=4"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/chronocrash.com\/obor\/wiki\/wp-json\/wp\/v2\/tags?post=4"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}