peek

Definition: integer i = peek(atom a)
-- or --
sequence s = peek({a, i})
Description: Return a single byte value in the range 0 to 255 from machine address a in memory, or return a sequence containing i consecutive byte values starting at address a.

There are in fact nine further variations of the peek function:

      peek1s  peek2s  peek4s  peek8s
      peek1u  peek2u  peek4u  peek8u
      peekNS

which from left to right retrieve bytes, words, dwords, and qwords, with the first row obtaining signed values and the second unsigned.

The peekNS routine takes three parameters: (a or {a,i}), size, and signed, eg peek4u(a)==peekNS(a,4,false).

The peek routine is actually an alias of peek1u, and when passed a parameter of {a,i} returns a string, whereas when given the same parameter all the others, including peek1s, return a dword-sequence.
Comments: The peek8s/u routines are not intended for use on 32-bit; for more details see the Technicalia dropdown below.

The 32-bit values returned by peek4s/u() may be too large for the 32-bit phix integer type (31-bits), so you should use atom variables, likewise for 64-bit values returned by peek8s() on 64-bit phix.

For similar reasons all variables that hold an address should also be declared as atoms.

When passed an atom parameter, peek(1|2)(s|u) (and peek4(s|u) on 64-bit) are however guaranteed to return an integer, should that help any.

Historically the peek({a,i}) form was faster than reading one byte at a time in a loop, however recent optimisations mean that is no longer necessarily (but will more often than not be) true. Specifically, when the overhead of subscripting to extract the individual elements of a sequence result that might otherwise not exist is taken into account, then individual peeks in a loop is likely to be faster. Of course if you are retreiving a string/sequence, and keeping a copy of it anyway, then whether or not you examine the individual characters/elements the peek({a,i}) form will almost certainly be faster.

Remember that peek always takes just one argument, which in the second form is actually a 2-element sequence (except for peekNS, which takes 3 parameters).
Example: The following are equivalent:
-- method 1
s = {peek(addr), peek(addr+1), peek(addr+2), peek(addr+3)}
-- method 2
s = peek({addr, 4})
See Also: poke, allocate, free, call, machine_bits