utils
*****

Types
=====

.. autonim:: private.types.FnPtr

-----------------------------

Lists
=====

.. autonim:: utils.List

A `List` is an array-like container with a length field. Adding new items will increase the length, but it cannot grow beyond its maximum capacity.

Lists have predictable performance, as they can be allocated statically, unlike Nim's built-in ``seq`` which is heap-allocated and can grow indefinitely.

.. tip::
   When compiling with `--boundChecks:on` the game will panic when the list grows too big or an out-of-bounds access occurs. To debug this situation, see :ref:`using a debugger <debugging>`.


Procs
-----

.. autonim:: utils.`[]`
.. autonim:: utils.`[]=`
.. autonim:: utils.cap
.. autonim:: utils.add
.. autonim:: utils.del
.. autonim:: utils.delete
.. autonim:: utils.insert
.. autonim:: utils.clear
.. autonim:: utils.isFull
.. autonim:: utils.contains

Unsafe procs
------------

These may be useful for optimisation, but they come with caveats which make them unsafe.
   
.. autonim:: utils.qcreate
.. autonim:: utils.qdel
.. autonim:: utils.qclear

Iterators
---------

.. autonim:: utils.items
.. autonim:: utils.mitems
.. autonim:: utils.pairs
.. autonim:: utils.mpairs

-----------------------------

Memory peek & poke
==================

These are like `volatileLoad <https://nim-lang.org/docs/volatile.html#volatileLoad.t%2Cptr.T>`_ and `volatileStore <https://nim-lang.org/docs/volatile.html#volatileStore.t%2Cptr.T%2CT>`_ from the Nim standard library, except they work even at the top level (and have nicer names).

.. autonim:: utils.peek
.. autonim:: utils.poke

-----------------------------

Memory copy / fill
==================

.. autonim:: private.gba.utils.memset16
.. autonim:: private.gba.utils.memcpy16
.. autonim:: private.gba.utils.memset32
.. autonim:: private.gba.utils.memcpy32

-----------------------------

Bit packing and duplication
===========================
 
These take a hex-value and duplicate it to all fields, like `0x88` -> `0x88888888`.

.. autonim:: utils.dup8
.. autonim:: utils.dup16
.. autonim:: utils.quad8
.. autonim:: utils.octup
.. autonim:: utils.bytes2hword
.. autonim:: utils.bytes2word
.. autonim:: utils.hword2word

-----------------------------

Math helpers
============
.. autonim:: utils.isPowerOfTwo
.. autonim:: utils.logPowerOfTwo
.. autonim:: utils.octant
.. autonim:: utils.octantRot

-----------------------------

Random numbers
==============

Uses a simple `XorShift <https://en.wikipedia.org/wiki/Xorshift>`_ algorithm, which is adequate for most games.

.. warning::
   Any range supplied to these procs should be less than 2^16 (`65536`).
   
   For example, the following will all give *inadequate* results:
   
   * `rand(max=999999)`
   * `rand(fp(-300)..fp(300))`
   * `rand(Natural)`
   
   If this is a problem, you could try `rand() mod n` instead (but that's expensive and leads to an uneven distribution of numbers). In the fixed-point case, you could first get a random integer and then convert it to fixed, e.g. `rand(-300..300).fp`.

.. autonim:: utils.seed
.. autonim:: utils.rand
.. autonim:: utils.rand_2
.. autonim:: utils.rand_3
.. autonim:: utils.rand_4
.. autonim:: utils.rand_5
.. autonim:: utils.pickRandom
.. autonim:: utils.pickRandom_2

-----------------------------

Compile-time helpers
====================

.. autonim:: utils.readBin