MEMORY Object
Updated: Sep 5, 2009

The MEMORY object creates a RAM space often called a data "stream" which can
be used for about any computing purpose one might think of.

MEMORY properties and methods enable creation and manipulation of blocks of
data.  Please see hotmem.bas for example code.

As with FILE and other HotBasic stream objects, read and write methods get
or put data from the current .Position and when complete, set the .Position
to the first byte after the data transferred.

HotBasic opens the flood gates.  All LIST properties and methods can be
used on MEMORY or STRING objects.  And MEMORY properties and methods can be
used on any dimensioned STRING, LIST, or ARRAY.  Why?  We love you.


PROPERTIES (Read/Write):
~~~~~~~~~~ ~~~~~~~~~~~~~
Length     Length in bytes of LIST.  MemLength = MyMem.Length
           IF MyMem.Length THEN  'Memory is not empty

           MyMem.Length = x  'only if x <= MyMem.Ram

Position   Current position for next read/write

           MyMem.Position = x  'only if x <= MyMem.Length

Size       Length in bytes of LIST

  Note: .Size and .Length refer to the same property item updated as writes
  are done.  Hence, a reduced .Length can be assigned for a particular
  purpose, such as saving only an initial portion of the data.  However, such
  a changed .Length property should not be expected to remain unchanged after
  further programmatic writes.


PROPERTIES (Read Only String):
~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~
ReadBinStr (bytes) Same as .ReadStr

ReadLine   Reads line at current position

  For sequential retrieval of crlf-delimited items from any .Position,
  .ReadLine should be faster, expecially for long streams, since it does not
  require the step of locating the item based on index.

ReadStr    (bytes) Reads bytes number of bytes

  Note: bytes may be a variable, expression or immediate value.


PROPERTIES (Read Only Numeric):
~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~
Handle     Memory handle of object stream data

ItemCount  Item count of object stream; same as .LineCount

ItemUDT    (index) Reads UDT item at 0-based index; alias for .UDTItem 

LineCount  Line count of object stream

Pointer    Address of object stream data

Ram        Bytes of memory currently allocated for stream use

  Note: If more memory is required, it is automatically allocated as write
  methods add data to the stream object.  Use of .Clear or .Close is
  recommended when computing is completed on large streams to free memory that
  is not immediately used further by the application.  After .Close, the
  dimensioned stream still exists for further use.

ReadNum    (bytes) Reads bytes number of bytes

  Note: Bytes read are assigned to number which can be any numerical data type.
  Bytes should generally agree with the destination value length.

UDTItem    (index) Reads UDT item at 0-based index 

           MyUDT = MyMemory.UDTItem(3)  'get UDT at 0-based index 3

           .ReplaceUDT() and .UDTItem() allow random write/read access
           respectively, to UDTs previously written into a MEMORY stream.
           The index must be less than MyMemory.Length/sizeof(MyUDT)

METHODS    Arguments & Comments
~~~~~~~    ~~~~~~~~~~~~~~~~~~~~
Append     Appends result of one or more string expressions

  $APPTYPE CONSOLE: $TYPECHECK ON
  defstr a$, b$
  a$ = "HotBasic"
  b$ = "the Gold Standard"
  a$.Append space, b$, " for best executables"
  print a$
  PAUSE

  .Append is faster than the logically equivalent

  a$ = a$ + space + b$ + " for best exectables"

  which is done in two steps:  create concatenated string which is then
  assigned to the destination variable (a$ above).

AppendUDT  Appends one or more UDTs starting at the current .Position.
           Similar to .Append, except the arguments are UDTs, not STRINGs.

Clear      Clears data and frees allocated RAM if > about 256 bytes.
           E.g., s$.Clear 'same as s$="" or s$=NULL

Close      Clears data; same as .clear

CopyFrom   (stream, bytes) Copies bytes from stream

  Note: stream may be a STRING, MEMORY, ARRAY, LIST or FILE.
  Data copied starts at the .Position property of the source stream.

Decrypt    Decrypts data

Encrypt    Encrypts data

  Note: an optional key argument -- any numeric expression -- may be used with
  .Encrypt and .Decrypt.

  MyMemory.Encrypt key
  'code
  MyMemory.Decrypt key  'same key value as used with .Encrypt

ExtractRes (resource) Extracts resource to .Position in stream object

  Note: resource may be (1) Resource(n) where n is an immediate integer or
  (2) a quoted string for the resource descriptor used in $RESOURCE.
 
Initialize (bytes) Allocate object's buffer size to be > bytes.  Example:

  MyMemory.Initialize 1024

  sets MyMemory.Length = 0, MyMemory.RAM > 1024, and all bytes = 0.

  .Initialize is typically used to set a minimum buffer size to use the 
  object's address (@MyMemory) as an argument for a procedure.  Notice that,
  if a procedure (e.g., an API) puts data into MyMemory, the application
  needs to set MyMemory.Length accordingly to the size of the data inserted,
  else your application will continue to think that there is no data.

LoadArray  (array) Read array into object stream

LoadFromFile
           (filename$) Loads filename$ to current position

LoadFromHandle +
           (mem_obj_handle, bytes) Read bytes of data from a memory
           object identified by its handle.

  If bytes is 0, .LoadFromHandle assumes the data is a text string and uses the
  LEN function to set bytes to load.  If successful, .LoadFromHandle replaces
  object stream data with memory object data.
           
  MyMem.LoadFromHandle mem_obj_handle, bytes

  Note: a mem_obj_handle is often obtained from the OS.  E.g., PRINTER and
  PRINTDIALOG return such handles in .DevNames and .DevMode properties.

  $DEFINE dmLogPixels 116 
  DEFSTR devmode
  DEFWORD LogPixels
  PRINTER.Dialog
  devmode.LoadFromHandle PRINTER.DevMode, 140
  devmode.Position = dmLogPixels  'from devmode.inc
  LogPixels = devmode.ReadNum(2)
  PRINT "LogPixels = "; LogPixels

MemCopyFrom
           (stream, bytes) Copies bytes from object stream to argument
           stream

MemCopyTo  (stream, bytes) Copies bytes from argument stream to object
           stream

   Note: .CopyFrom, .MemCopyFrom and .MemCopyTo all copy bytes from the
   current position of the source stream.  However, .CopyFrom writes
   bytes to the destination current .Position, while .MemCopyFrom and
   .MemCopyTo both write to .Position = 0 in the destination stream.

Read       (var) Reads var from object stream

ReadUDT    (UDT) Reads UDT from object stream

ReplaceUDT (index, UDT) Replace 0-based index item with UDT.

           MyMemory.Replace 3, MyUDT  '0-based item 3 replaced with MyUDT

           .ReplaceUDT() and .UDTItem() allow random write/read access
           respectively, to UDTs previously written into a MEMORY stream.
           The index must be less than MyMemory.Length/sizeof(MyUDT)

SaveArray  (array) Writes array from object stream to array

SaveToFile
           (filename$) Save MEMORY to filename$
           If filename$ exists, filename$ is overwritten.

SaveToStream
           (stream) Save MEMORY to stream starting at stream .Position

Seek       (position) Sets .Position; Same as .Position =

Write      (var) Writes var to object stream

WriteBinStr
           (string$, bytes) Writes bytes from string$

WriteLine  (string$) Writes string$ appending CRLF

WriteNum   (var, bytes) Writes var as bytes of data

WriteStr   (string$, bytes) Writes bytes from string$

WriteUDT   (UDT) Writes UDT to object stream


###########

Note: Any dimensioned STRING may utilize any of the above properties and
methods.  E.g., s$.length is faster than LEN(s$).  The former just reads the
.Length property; the latter evaluates the length by looking for the first null
byte as would be customary for text-only string data.


+ PentHouse registered version

Copyright 2003-2009 James J Keene PhD
Original Publication: Oct 9, 2003