[SparForte][Banner]
[Top Main Menu] Intro | Tutorials | Reference | Packages | Examples | Contributors   [Back Page]      [Next Page]  

Hash_Io Package

The SparForte built-in hash_io package contains subprograms to create hash table files. btree_io is better for most applications. hash_io should perform better on low-memory systems with very large amount of data.

Introduced: SparForte 2.0

GCC Ada Equivalent: none

A B-tree file is a collection of data nodes stored to disk. Each node stores a value called an element. Each value is referenced by a key. Each file can only hold one kind of element (unless universal types are used).

The programmer can traverse forward or reverse through the file. File positions are designated by cursors.

This package is implemented using the Berkeley database. Creating a file will also create several auxillary files in the same directory. The files in one directory will share the same Berkeley environment.

This package includes three new types:

  • hash_io.file - a B-tree file
  • hash_io.cursor - a B-tree cursor

bdb.db_error constants are also defined (e.g. bdb.DB_OK ), though not all errors for all versions of Berkeley DB are defined and operating system error codes (e.g. EINVAL, ENOENT) may also be returned.

It is possible to open the file with the wrong (or a different) file data type but this is not recommended.

=> type clouds is (fog, cumulus, stratus, cirrus, cumulonimbus )
=> hash_io.new_file( f, clouds )
=> (Assuming f is a new hash_io.file variable)
=> hash_io.create( f, "clouds.hash", 80, 80 )
=> ? hash_io.is_open( f )
true
=> ? hash_io.name( f )
clouds.hash
=> ls
clouds.hash  __db.001	__db.002  __db.003  __db.004
=> hash_io.set( f, "Toronto", fog )
=> hash_io.set( f, "New York", cirrus )
=> hash_io.set( f, "Moscow", cumulonimbus )
=> ? hash_io.has_element( f, "Tokyo" )
false
=> hash_io.get( f, "New York", c )
=> (Assuming c is a new clouds variable)
=> ? c
cirrus
=> hash_io.add( f, "New York", cumulus )
=> hash_io.get( f, "New York", c )
=> (Assuming c is a new clouds variable)
=> ? c
cirrus
=> hash_io.close( f )
 
Example: Using hash_io to create a file of cities and their clouds
type person_type is record
   first_name : string;
   age  : natural;
end record;

person : person_type;

f : hash_io.file;

hash_io.new_file( f, person_type );
hash_io.create( f, "person.hash", 80, 80 );

person.first_name := "John";
person.age  := 18;
hash_io.add( f, person.first_name, person );

person.first_name := "Sue";
person.age  := 21;
hash_io.add( f, person.first_name, person );

person.first_name := "Al";
person.age  := 42;
hash_io.add( f, person.first_name, person );

declare
  c : hash_io.cursor;
  key : string;
begin
  hash_io.new_cursor( c, person_type );
  hash_io.open_cursor( f, c );
  hash_io.get_first( f, c, key, person );
  put( person.first_name ) @ ( " /" ) @ (person.age);
  new_line;

  loop
    hash_io.get_next( f, c, key, person );
    put( person.first_name ) @ ( " /" ) @ (person.age);
    new_line;
  end loop;
exception when others =>
  hash_io.close_cursor( f, c );
  put_line( "no more people" );
end;

hash_io.close( f );
 
Example: Using hash_io to sort records

hash_io.add( f, k, v )

 

Put value v under key k in the file. If the key already exists, do nothing.

Example

hash_io.add( fruit, "apples", 15 );

Parameters

Param Mode Type Default Description
f in out hash_io.file required the file
k in string required the key
v in file value type required the value

Exceptions

An exception is raised if the value is the wrong type
An exception is raised for a deadlock
An exception is raised if the files are read-only access
An exception is raised if the B-Tree is too large

Restrictions

Not allowed in a restricted shell

See Also

hash_io.set
hash_io.replace

Compare With

Ada: N/A (AdaScript extension)

Implementation Note

This is in accordance with memcached.

hash_io.append( f, k, v )

 

Append string value v to the value under key k in the file. If the key does not exist, do nothing.

Example

hash_io.set( fruit_unit, "apples", "bushel" );
hash_io.append( fruit_unit, "apples", "s" );

Parameters

Param Mode Type Default Description
f in out hash_io.file required the file
k in string required the key
v in file value type required the string to append

Exceptions

An exception is raised if the value is the wrong type
An exception is raised for a deadlock
An exception is raised if the files are read-only access
An exception is raised if the value type is not a string

Restrictions

Not allowed in a restricted shell

See Also

hash_io.prepend

Compare With

Ada: N/A (AdaScript extension)

Implementation Note

This is in accordance with memcached.

hash_io.clear( f )

 

Release memory allocated for f. (This is automatically done when the variable is destroyed.)

Example

hash_io.clear( fruit );

Parameters

Param Mode Type Default Description
f in out hash_io.file required the file

Exceptions

-

Restrictions

-

See Also

hash_io.create
hash_io.open

Compare With

Ada: N/A (AdaScript extension)
C: DB->close
PHP: dba_close

hash_io.close( f )

 

Close the hash file f.

Example

hash_io.close( fruit );

Parameters

Param Mode Type Default Description
f in out hash_io.file required the file

Exceptions

-

Restrictions

-

See Also

hash_io.create
hash_io.open

Compare With

Ada: N/A (AdaScript extension)
C: DB->close
PHP: dba_close

hash_io.close_cursor( f, c )

 

Close the cursor c associated with file f.

Example

hash_io.close( fruit );

Parameters

Param Mode Type Default Description
f in out hash_io.file required the file

Exceptions

-

Restrictions

-

See Also

hash_io.create
hash_io.open

Compare With

Ada: N/A (AdaScript extension)
C: DB->close
PHP: dba_close

hash_io.create( f, p, kl, vl )

 

Create a new B-tree file f named p. Maximum key length is kl bytes and maximum value length is vl bytes. If the database exists, it is overwritten. If --verbose is used, BDB verbose error messages are enabled. If the file name is an empty string, the B-tree will be stored in memory and any supporting files will be stored in the current directory.

Example

hash_io.create( fruit, "fruit.hash", 80, 80 );

Parameters

Param Mode Type Default Description
f in out hash_io.file required the file
p in string required the pathname
kl in positive required the max key length
vl in positive required the max value length

Exceptions

An exception is raised for a database created in an incompatible version of BDB
An exception is raised for a deadlock

Restrictions

Not allowed in a restricted shell

See Also

hash_io.open

Compare With

Ada: N/A (AdaScript extension)
C: db_env_create, DB_ENV->open, db_create, DB->open
PHP: dba_open

Implementation Note

This maximum lengths are for allocating space to convert SparForte strings into the C strings used by Berkeley DB.

hash_io.decrement( f, k [,n] )

 

Reduce the numeric value under key k in the file by one (or n). If the key does not exist, do nothing.

Example

hash_io.decrement( fruit, "apples" );

Parameters

Param Mode Type Default Description
f in out hash_io.file required the file
k in string required the key
n in file value type 1 the amount to decrement

Exceptions

An exception is raised if the value is the wrong type
An exception is raised for a deadlock
An exception is raised if the files are read-only access
An exception is raised if the value type is not numeric

Restrictions

Not allowed in a restricted shell

See Also

hash_io.increment

Compare With

Ada: N/A (AdaScript extension)

Implementation Note

This is in accordance with memcached.

hash_io.delete( f )

 

Delete the file and associated files.

Example

hash_io.delete( fruit );

Parameters

Param Mode Type Default Description
f in out hash_io.file required the file

Exceptions

-

Restrictions

Not allowed in a restricted shell

See Also

hash_io.create

Compare With

Ada: N/A (AdaScript extension)
C: db_remove
PHP: ?

hash_io.flush( f )

 

Write all cached data to disk.

Example

hash_io.flush( fruit );

Parameters

Param Mode Type Default Description
f in out hash_io.file required the file

Exceptions

-

Restrictions

-

See Also

-

Compare With

Ada: N/A (AdaScript extension)
C: DB->sync
PHP: ?

hash_io.get( f, k, v )

 

Get the value under key k in the file. An exception is raised if k does not exist.

Example

hash_io.get( fruit, "apples", val );

Parameters

Param Mode Type Default Description
v out file value type required the value
f in out hash_io.file required the file
k in string required the key

Exceptions

An exception is raised on out-of-memory
An exception is raised for a deadlock
An exception is raised if the key is not found

See Also

-

Compare With

Ada: Gnat.Dynamic_Hash_Tables.Get
C: DB->get
PHP: dbm_fetch

hash_io.get_first( f, c, k, v )

 

Iterate through the file. Return the first value in the file. The order is the alphabetical order of the keys. An exception is thrown if the file is empty.

Example

hash_io.get_first( fruit, cursor, first_key, first_value );

Parameters

Param Mode Type Default Description
f in out hash_io.file required the file
c in out hash_io.cursor required the cursor
k out string required the first key
v out file value type required the first value

Exceptions

?

Restrictions

Not allowed in a restricted shell

See Also

hash_io.get_next

Compare With

Ada: bdb.get

Implementation Note

The name reflects dynamic_hash_tables.

hash_io.get_last( f, c, k, v )

 

Iterate through the file. Return the last value in the file. The order is the alphabetical order of the keys. An exception is thrown if the file is empty.

Example

hash_io.get_last( fruit, cursor, last_key, last_value );

Parameters

Param Mode Type Default Description
f in out hash_io.file required the file
c in out hash_io.cursor required the cursor
k out string required the last key
v out file value type required the last value

Exceptions

?

Restrictions

Not allowed in a restricted shell

See Also

hash_io.get_prev

Compare With

Ada: bdb.get

Implementation Note

The name reflects dynamic_hash_tables.

hash_io.get_next( f, c, k, v )

 

Iterate through the file. Return the next value in the file. The order is the alphabetical order of the keys. An exception is thrown if the file is empty. Iteration is started with get_first.

Example

hash_io.get_next( fruit, cursor, next_key, next_value );

Parameters

Param Mode Type Default Description
f in out hash_io.file required the file
c in out hash_io.cursor required the cursor
k out string required the next key
v out file value type required the next value

Exceptions

?

Restrictions

Not allowed in a restricted shell

See Also

hash_io.get_next

Compare With

Ada: bdb.get

Implementation Note

The name reflects dynamic_hash_tables.

hash_io.get_previous( f, c, k, v )

 

Iterate through the file. Return the previous value in the file. The order is the alphabetical order of the keys. An exception is thrown if the file is empty. Iteration is started with get_last.

Example

hash_io.get_previous( fruit, cursor, prev_key, prev_value );

Parameters

Param Mode Type Default Description
f in out hash_io.file required the file
c in out hash_io.cursor required the cursor
k out string required the previous key
v out file value type required the previous value

Exceptions

?

Restrictions

Not allowed in a restricted shell

See Also

hash_io.get_next

Compare With

Ada: bdb.get

Implementation Note

The name reflects dynamic_hash_tables.

b := hash_io.has_element( f, k )

 

Determine if key k is in the file.

Example

if hash_io.has_element( fruit, "apples" ) then ...

Parameters

Param Mode Type Default Description
b return value boolean required true if there is an element
f in out hash_io.file required the file
k in string required the key

Exceptions

-

See Also

Ada: N/A (AdaScript extension)

Compare With

C: DB->exists

hash_io.increment( f, k [,n] )

 

Increase the numeric value under key k in the file by one (or n). If the key does not exist, do nothing.

Example

hash_io.increment( fruit, "apples" );

Parameters

Param Mode Type Default Description
f in out hash_io.file required the file
k in string required the key
n in file value type 1 the amount to increment

Exceptions

An exception is raised if the value is the wrong type
An exception is raised if out of memory
An exception is raised if the value type is not numeric

Restrictions

Not allowed in a restricted shell

See Also

hash_io.decrement

Compare With

Ada: N/A (AdaScript extension)

Implementation Note

This is in accordance with memcached.

b := hash_io.is_open( f )

 

True if file f has been openned.

Example

if hash_io.is_open( fruit ) then ...

Parameters

Param Mode Type Default Description
b return value boolean required true if the file is open
f in out hash_io.file required the file

Exceptions

-

See Also

Ada: N/A (AdaScript extension)

Compare With

-

e := hash_io.last_error( f )

 

Return the error code from the last Berkeley DB action.

Example

if hash_io.last_error /= hash_io.DB_OK then ...

Parameters

Param Mode Type Default Description
e return value hash_io.db_error required the last error code
f in hash_io.file required the file

Exceptions

-

See Also

Ada: N/A (AdaScript extension)

Compare With

-

hash_io.new_cursor( c, t )

 

Initialize a new cursor, assigning the type for the values in the file. The type may be an array, record, scalar or a unversal type.

Example

hash_io.new_cursor( fruit, natural );

Parameters

Param Mode Type Default Description
c in out hash_io.cursor required the cursor
t in the value type required the type of values

Exceptions

An exception is raised if out of memory

Compare With

Ada: N/A (AdaScript extension)

Implementation Note

Allocates a resource for the list.

hash_io.new_file( f, t )

 

Initialize a new file, assigning the type for the values in the file. The type may be an array, record, scalar or a unversal type.

Example

hash_io.new_file( fruit, natural );

Parameters

Param Mode Type Default Description
f in hash_io.file required the file
t in the value type required the type of values

Exceptions

An exception is raised if out of memory

Compare With

Ada: N/A (AdaScript extension)

Implementation Note

Allocates a resource for the list.

hash_io.open( f, p, kl, vl )

 

Open a new B-tree file f named p. Maximum key length is kl bytes and maximum value length is vl bytes. If no database exists, an exception is raised. If --verbose is used, BDB verbose error messages are enabled.

Example

hash_io.open( fruit, "fruit.hash", 80, 80 );

Parameters

Param Mode Type Default Description
f in out hash_io.file required the file
p in string required the pathname
kl in positive required the max key length
vl in positive required the max value length

Exceptions

An exception is raised for a database created in an incompatible version of BDB
An exception is raised for a deadlock

Restrictions

Not allowed in a restricted shell

See Also

hash_io.create

Compare With

Ada: N/A (AdaScript extension)
C: db_env_create, DB_ENV->open, DB->open
PHP: dba_open

Implementation Note

This maximum lengths are for allocating space to convert SparForte strings into the C strings used by Berkeley DB.

hash_io.prepend( f, k, v )

 

Prepend string value v to the value under key k in the file. If the key does not exist, do nothing.

Example

hash_io.set( fruit_unit, "apples", "ushels" );
hash_io.prepend( fruit_unit, "apples", "b" );

Parameters

Param Mode Type Default Description
f in hash_io.file required the file
k in string required the key
v in file value type required the string to prepend

Exceptions

An exception is raised if the value is the wrong type
An exception is raised if out of memory
An exception is raised if the value type is not a string

Restrictions

Not allowed in a restricted shell

See Also

hash_io.append

Compare With

Ada: N/A (AdaScript extension)

Implementation Note

This is in accordance with memcached.

hash_io.raise_exceptions( f, b )

 

Determine if Berkeley errors are raised as exceptions or if the programmer will check for errors with last_error as required. The default is to raise exceptions. If --trace is used, the location in the SparForte source code is included with the error message.

Example

hash_io.raise_exceptions( fruit, true );

Parameters

Param Mode Type Default Description
f in hash_io.file required the file
b in boolean required true if errors will be raised

Exceptions

An exception is raised if the value is the wrong type
An exception is raised if out of memory

See Also

hash_io.will_raise

Compare With

Ada: ?

hash_io.remove( f, k )

 

Delete a key and the associated value from the file.

Example

hash_io.remove( fruit, "bad apples" );

Parameters

Param Mode Type Default Description
f in hash_io.file required the file
k in string required the key to delete

Exceptions

-

Restrictions

Not allowed in a restricted shell

See Also

dynamic_hash_tables.reset
dynamic_hash_tables.set

Compare With

Ada: N/A (AdaScript extension)

Implementation Note

This is in accordance with memcached.

hash_io.replace( f, k, v )

 

Replace the value v under key k in the file. If the key does not exist, do nothing.

Example

hash_io.replace( fruit, "apples", 23 );

Parameters

Param Mode Type Default Description
f in hash_io.file required the file
k in string required the key
v in file value type required the new value

Exceptions

An exception is raised if the value is the wrong type
An exception is raised if out of memory

Restrictions

Not allowed in a restricted shell

See Also

hash_io.set
hash_io.add

Compare With

Ada: N/A (AdaScript extension)

Implementation Note

This is in accordance with memcached.

hash_io.set( f, k, v )

 

Assign the value v to the key k in the file. If the key does not exist, create it.

Example

hash_io.set( fruit, "apples", 21 );

Parameters

Param Mode Type Default Description
f in hash_io.file required the file
k in string required the key
v in file value type required the new value

Exceptions

An exception is raised if the value is the wrong type
An exception is raised if out of memory

Restrictions

Not allowed in a restricted shell

See Also

hash_io.add
hash_io.replace
hash_io.remove

Compare With

Ada: DB->put

hash_io.truncate( f )

 

Erase all data from the file.

Example

hash_io.truncate( fruit );

Parameters

Param Mode Type Default Description
f in out hash_io.file required the file

Exceptions

-

Restrictions

Not allowed in a restricted shell

See Also

-

Compare With

Ada: N/A (AdaScript extension)
C: DB->truncate>sync

b := hash_io.will_raise( f )

 

True if Berkeley errors will be raised as exceptions.

Example

if hash_io.is_open( fruit ) then ...

Parameters

Param Mode Type Default Description
b return value boolean required true if the file is open
f in out hash_io.file required the file

Exceptions

-

See Also

Ada: N/A (AdaScript extension)

Compare With

-

 
[Right Submenu]

 Summary

 arrays

 btree_io

 calendar

 cgi

 chains

 command_line

 db/ postgresql

 dbm

 directory_operations

 doubly_linked...

 dynamic_hash_...

 enums

 exceptions

 files

 gnat.cgi

 gnat.crc32

 hash_io

 lock_files

 memcache

 memcache.highread

 mysql

 mysqlm

 numerics

 os

 pen

 pen (OpenGL)

 records

 sound

 source_info

 stats

 strings

 System

 teams

 templates

 text_io

 units

[Back to Top] Back To Top [Small Forte Symbol]