Directory (DIR)


Data Structures

struct  DirItem
 A C structure for creating directories. More...

Functions

SatAddr DIRfirstEntry (SatAddr dir)
 Get the first entry in a directory.
SatAddr DIRnextEntry (SatAddr entry)
 Get the next entry in a directory.
bool DIRdecodeEntry (SatAddr entry, char *name, SatAddr *obj)
 Decode a directory entry.
int DIRentryNameLen (SatAddr entry)
SatAddr DIRfindEntryByName (SatAddr dir, const char *name)
 Find a directory entry by name.
SatAddr DIRfindEntryByIdnt (SatAddr dir, SatAddr idnt)
 Find a directory entry from an IDNT object.
SatAddr DIRfindObByName (SatAddr dir, const char *name)
 find a directory object by name.
SatAddr DIRfindObByIdnt (SatAddr dir, SatAddr idnt)
 find a directory object from an IDNT object
void DIRinit (SatAddr dst)
 Create an empty directory.
SatAddr makeDIR (int nibbles)
 Make an empty directory with "nibbles" nibbles of free space.
bool DIRadd (SatAddr src, const char *name, SatAddr obj)
 Add an entry to a DIR.
DirItemDIRdecode (SatAddr src)
 Decode an entire directory.
SatAddr DIRencode (struct DirItem *head, SatAddr dst)
 Encode an entire directory.
int DIRchangeByName (SatAddr dir, const char *name, SatAddr obj)
 Overwrite the variable in a directory with an object of the same size.
int DIRchangeByIdnt (SatAddr dir, SatAddr idnt, SatAddr obj)
 Same as DIRchangeByName(), but uses a global identifier object (idnt) to lookup the name.
int DIRnibbles (SatAddr dir)
 Return the size in nibbles of the DIR at src.
SatAddr DIRdirForEntry (SatAddr entry)
 Get the DIR object that a encloses a directory entry.
SatAddr DIRparentDir (SatAddr dir)
 Get the parent of a directory.
SatAddr getHOME ()
 Get the Saturn address of the HOME directory.
SatAddr getCWD ()
 Get the Saturn address of the current directory.
bool isDIR (SatAddr src)
 is the object at src a DIR?

Detailed Description

A directory contains a bunch of "entries" that consist of name/value pairs. Use DIRfirstEntry() and DIRnextEntry() to go through the entries. Then you can use DIRdecode() to extract the name and object within each entry.

Function Documentation

bool DIRadd ( SatAddr  src,
const char *  name,
SatAddr  obj 
)

Add an entry to a DIR.

The DIR must have enough space for the new entry.

Parameters:
src The DIR object to add to
name Null-terminated string of the new entry's name
obj Saturn address if the object. The object will be copied to the directory.

int DIRchangeByName ( SatAddr  dir,
const char *  name,
SatAddr  obj 
)

Overwrite the variable in a directory with an object of the same size.

Parameters:
dir Saturn address of a DIR object.
name null-terminated string containing the name of the directory entry to change.
obj Saturn address of the replacement object. This object must be the same size as the existing object associated with "name."
Returns:
0 on success. -1 if there is no entry for "name" in dir or dir isn't a DIR object, -2 if "obj" is not the same size as the existing object for "name".

struct DirItem* DIRdecode ( SatAddr  src  ) 

Decode an entire directory.

Parameters:
src The DIR object to decode
Returns:
a DirItem list of the objects in the directory. This is allocated on the heap and the caller must free it.

bool DIRdecodeEntry ( SatAddr  entry,
char *  name,
SatAddr obj 
)

Decode a directory entry.

Parameters:
entry The directory entry, which is the return value from a previous call to DIRfirstEntry() or DIRnextEntry()
name If non-null then the name of the directory entry will be stored here as a null-terminated string. Name must point to enough space to store the name. 256 bytes is always enough. You can also use DIRentryNameLen() to get the exact length
obj If non-null, then the Saturn address of the DIR entry's object will be stored here.
Returns:
true on success, false if entry is not a directory entry.

SatAddr DIRdirForEntry ( SatAddr  entry  ) 

Get the DIR object that a encloses a directory entry.

Parameters:
entry Saturn address of a directory entry returned by DIRfirstEntry(), DIRnextEntry(), DIRfindEntryByIdnt(), etc
Returns:
The directory that the entry is in, or 0 on error.
Warning:
This won't work properly if "entry" is located in a copy of the home directory and the copy has multiple libraries attached to it.

SatAddr DIRencode ( struct DirItem head,
SatAddr  dst 
)

Encode an entire directory.

Parameters:
head Pointer to a DirItem list that represents the items to go in the directory.
dst The Saturn address where the DIR should be stored. If dst is zero (the expected case) then space is allocated for the DIR in tempOb. Otherwise dst must point to sufficient space for the DIR.
Returns:
Saturn address of the directory, or zero if an error occurred.
DIRencode() does not modify or free the DirItem list.

int DIRentryNameLen ( SatAddr  entry  ) 

Get the number of characters in a directory entry name

Parameters:
entry The directory entry, which is the return value from a previous call to DIRfirstEntry() or DIRnextEntry()
Returns:
The number of characters in the directory entry's name. You can create a buffer with this many bytes, plus 1 for the terminating null, and pass the buffer as the name parameter in DIRdecodeEntry().

SatAddr DIRfindEntryByIdnt ( SatAddr  dir,
SatAddr  idnt 
)

Find a directory entry from an IDNT object.

Parameters:
dir A DIR object
idnt Saturn address of an IDNT object (a global identifier)
Returns:
The Saturn address of the directory entry or 0 if no entry was found. Unlike RCL, this searches in the dir specified only, not the parent directories.
See also:
DIRfindEntryByName()

SatAddr DIRfindEntryByName ( SatAddr  dir,
const char *  name 
)

Find a directory entry by name.

Parameters:
dir A DIR object
name A null-terminated string that is the name to find.
Returns:
The Saturn address of the directory entry or 0 if no entry was found. Unlike RCL, this searches in the dir specified only, not the parent directories.
See also:
DIRfindEntryByIdnt() DIRfindObByName(), DIRfindObByIdnt()

SatAddr DIRfindObByIdnt ( SatAddr  dir,
SatAddr  idnt 
)

find a directory object from an IDNT object

This is like DIRfindEntryByIdnt, except it returns the Saturn address of the object in the entry, not just the entry.

See also:
DIRfindEntryByName(), DIRfindEntryByIdnt(), DIRfindObByName()

SatAddr DIRfindObByName ( SatAddr  dir,
const char *  name 
)

find a directory object by name.

This is like DIRfindEntryByName, except it returns the Saturn address of the object in the entry, not just the entry.

See also:
DIRfindEntryByName(), DIRfindEntryByIdnt(), DIRfindObByIdnt()

SatAddr DIRfirstEntry ( SatAddr  dir  ) 

Get the first entry in a directory.

Parameters:
dir Saturn address of a DIR object
Returns:
Saturn address of the first DIR entry or zero if the DIR is empty or dir is not a DIR object
See also:
DIRnextEntry(), DIRdecode()

void DIRinit ( SatAddr  dst  ) 

Create an empty directory.

Parameters:
dst Saturn address where the directory should go.
Warning:
If dst is in TEMPOB then you must fill the space allocated completely. Otherwise the garbage collector will fail the next time it runs and you calculator will probably hang or reboot.

SatAddr DIRnextEntry ( SatAddr  entry  ) 

Get the next entry in a directory.

Parameters:
entry The return value from a previous call to DIRfirstEntry() or DIRnextEntry()
Returns:
Saturn address of the next directory entry, or zero if there are no more or if an error occurs.

int DIRnibbles ( SatAddr  dir  ) 

Return the size in nibbles of the DIR at src.

Parameters:
src the Saturn address of a DIR object
Returns:
the size of the DIR in nibbles, or zero if src is not a DIR

SatAddr DIRparentDir ( SatAddr  dir  ) 

Get the parent of a directory.

Parameters:
dir Saturn address of a DIR object
Returns:
Saturn address of dir's parent DIR object, or zero if "dir" is the HOME directory or if an error occurrs, such as when "dir" isn't a DIR object.

bool isDIR ( SatAddr  src  ) 

is the object at src a DIR?

Parameters:
src Saturn address of an object
Returns:
true if the object at src is a DIR.

SatAddr makeDIR ( int  nibbles  ) 

Make an empty directory with "nibbles" nibbles of free space.

Parameters:
nibbles the number of nibbles to allocate
Returns:
The empty directory.


Generated on Sat Apr 3 16:38:31 2010 for HPObjects by  doxygen 1.5.0