# poke

Definition: | poke(atom a, object x)
Description: | If x is an atom, write a single byte value to memory address a. If x is a sequence, write a sequence of byte values to consecutive memory locations starting at location a.
pwa/p2js: | Not supported.
Comments: | There are in fact 5 other variations of the poke routine:
          poke1  poke2  poke4  poke8  pokeN
which write byte/word/dword/qword value(s) to memory. The poke procedure is an alias of poke1. The pokeN routine has 3 parameters: address, value, and size(1|2|4|8). The poken procedure is a simple hll wrapper of pokeN() that defaults size to machine_word() For poke (/poke1) the lower 8 bits of each byte value, i.e. and_bits(x, #FF), are stored in memory, and likewise for poke2/4/8, the lower 16/32/64 bits of each word/dword/qword value. The poke8 function is only intended for use on 64-bit architectures, see technicalia. It is faster to write several bytes at once by poking a sequence of values, than it is to write one byte at a time in a loop.
Example: |
    a = allocate(100)   -- allocate 100 bytes in memory
    -- poke one byte at a time:
    poke(a,97)
    poke(a+1,98)
    poke(a+2,99)
    -- poke 3 bytes at once:
    poke(a,{97,98,99})
Implementation: | via :%opPokeN in builtins\VM\pMem.e (an autoinclude) - be warned however it is low-level complicated stuff that you do not need to know. The poken routine is (trivially) implemented in builtins\peekns.e (an autoinclude), see also the notes in peek.
See Also: | peek, allocate, free, call
Technicalia | Invoking poke8 on 32-bit may cause some loss of precision, and special care must be taken with the results from peek8s/u. Further note that attempts to code 64-bit literals in a 32-bit program are likely to miss, for example "#8000000000000000" actually ends up as #7FFFFFFFFFFFFC00, however better results may be achieved by coding the value as "#80000000*#100000000". (In truth that is probably a fixable bug, but one I have no time or inclination to investigate right now, especially given that say #8000000000000001 simply cannot be stored, at least not in a single atom, on 32-bit, as per peek8s/u.)