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

Doubly_Linked_Lists Package

The SparForte built-in doubly_linked_lists package contains subprograms to create and manage ordered, unindexed, linked lists.

Introduced: SparForte 1.5

GCC Ada Equivalent: Ada.Containers.Doubly_Linked_Lists

A list is a dynamic collection of list nodes. Each node stores a value called an element. Each list can only hold one kind of element (though it can be a universal type). The programmer can traverse forward or reverse through the list. List positions are designated by cursors.

This package includes four new types:

  • containers.count_type
  • containers.hash_type
  • doubly_linked_lists.list
  • doubly_linked_lists.cursor
=> type fruit_string is new string
=> doubly_linked_lists.new_list( fruit, fruit_string )
=> (Assuming fruit is a new doubly_linked_lists.list variable)
=> doubly_linked_lists.append( fruit, "apple" );
=> doubly_linked_lists.append( fruit, "blueberry" )
=> doubly_linked_lists.append( fruit, "cherry" )
=> ? doubly_linked_lists.length( fruit )
 3
=> ? doubly_linked_lists.first_element( fruit )
apple
=> ? doubly_linked_lists.contains( fruit, "pineapple" )
false
=> doubly_linked_lists.new_cursor( c, fruit_string )
=> (Assuming c is a new doubly_linked_lists.cursor variable)
=> doubly_linked_lists.first( fruit, c )
=> doubly_linked_lists.next( c )
=> ? doubly_linked_lists.element( c )
blueberry
 
Example: Using doubly_linked_lists to create a list of fruit

doubly_linked_lists.append( l, e )

 

Queue list element e at the end of the list.

Example

doubly_linked_lists.append( l, "zebra" )

Parameters

Param Mode Type Default Description
l in out doubly_linked_lists.list required the list
e in list element type required the element to queue

Exceptions

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

See Also

doubly_linked_lists.prepend

Compare With

Ada: Ada.Containers.Doubly_Linked_Lists.Append

Implementation Note

-

s := doubly_linked_lists.assemble( l [,d [,f]] )

 

Apply strings.image to each element in the list. Concatenate the strings together to form a new string, separated by delimiter string d and ending with optional string f. An list will result in an empty string (but f will be appended even if the string is empty).

Example

echo( doubly_linked_lists.assemble( lines ) ) | wc;

Parameters

Param Mode Type Default Description
s return value universal_string required the string image of the list
l in doubly_linked_lists.list required the list
d in universal_string ASCII.LF the delimiter
f in universal_string null_unbounded_string the end of the string

Exceptions

An exception is raised if out of memory

See Also

doubly_linked_lists.disassemble

Compare With

Ada: N/A (AdaScript extension)

Implementation Note

-

doubly_linked_lists.assign( l1, l2 )

 

Overwrite the contents of list l1 with a copy of l2.

Example

doubly_linked_lists.assign( destination_list, source_list )

Parameters

Param Mode Type Default Description
l1 in out doubly_linked_lists.list required the destination list
l2 in doubly_linked_lists.list required the source list

Exceptions

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

See Also

doubly_linked_lists.move

Compare With

Ada: Ada.Containers.Doubly_Linked_Lists.Assign

Implementation Note

-

doubly_linked_lists.clear( l )

 

Delete the contents of list l.

Example

doubly_linked_lists.clear( animal_list )

Parameters

Param Mode Type Default Description
l in out doubly_linked_lists.list required the list to erase

Exceptions

-

See Also

doubly_linked_lists.delete

Compare With

Ada: Ada.Containers.Doubly_Linked_Lists.Clear

Implementation Note

-

b := doubly_linked_lists.contains( l, e )

 

Return true if the list contains list element e.

Example

if doubly_linked_lists.contains( animal_list, "hyena" ) then ...

Parameters

Param Mode Type Default Description
b return value boolean required true if in list
l in doubly_linked_lists.list required the list
e in list element type required the element to find

Exceptions

An exception is raised if the element is the wrong type

See Also

doubly_linked_lists.find
doubly_linked_lists.reverse_find

Compare With

Ada: Ada.Containers.Doubly_Linked_Lists.Contains

Implementation Note

-

doubly_linked_lists.delete( l, c,[, n] )

 

Remove the list element at cursor position c from the list. If n exists, remove n items instead of one

Example

doubly_linked_lists.delete( animal_list, elephant_position )

Parameters

Param Mode Type Default Description
l in out doubly_linked_lists.list required the list
c in out doubly_linked_lists.cursor required the position to delete
n in containers.count_type 1 the number of positions

Exceptions

An exception is raised if the element type does not match

See Also

doubly_linked_lists.delete_first
doubly_linked_lists.delete_last

Compare With

Ada: Ada.Containers.Doubly_Linked_Lists.Delete

Implementation Note

-

doubly_linked_lists.delete_first( l, [, n] )

 

Remove the list element from the start of the list. If n exists, remove n items instead of one.

Example

doubly_linked_lists.delete_first( animal_list )

Parameters

Param Mode Type Default Description
l in out doubly_linked_lists.list required the list
n in containers.count_type 1 the number of positions

Exceptions

An exception is raised if there are no more elements.

See Also

doubly_linked_lists.delete
doubly_linked_lists.delete_last

Compare With

Ada: Ada.Containers.Doubly_Linked_Lists.Delete_First

Implementation Note

-

doubly_linked_lists.delete_last( l, [, n] )

 

Remove the list element from the end of the list. If n exists, remove n items instead of one.

Example

doubly_linked_lists.delete_last( animal_list )

Parameters

Param Mode Type Default Description
l in out doubly_linked_lists.list required the list
n in containers.count_type 1 the number of positions

Exceptions

An exception is raised if there are no more elements.

See Also

doubly_linked_lists.delete
doubly_linked_lists.delete_first

Compare With

Ada: Ada.Containers.Doubly_Linked_Lists.Delete_Last

Implementation Note

-

doubly_linked_lists.disassemble( s, l, [,d [,f]] )

 

Convert the string to a list of strings. Each string is deliminted by string d (default line feed) and optional string f will be removed from the end of the string before processing. An empty string will result in an empty list.

Example

doubly_linked_lists.disassemble( `ls;`, lines ) );

Parameters

Param Mode Type Default Description
s return value universal_string required the string image of the list
l in doubly_linked_lists.list required the list
d in universal_string ASCII.LF the delimiter
f in universal_string null_unbounded_string the end of the string

Exceptions

An exception is raised if out of memory

See Also

doubly_linked_lists.disassemble

Compare With

Ada: N/A (AdaScript extension)

Implementation Note

-

e := doubly_linked_lists.element( c )

 

Return the list element at the cursor.

Example

put_line( doubly_linked_lists.element( orca_position ) );

Parameters

Param Mode Type Default Description
e return value list element type required the element
c in doubly_linked_lists.cursor required the cursor

Exceptions

An exception is raised if there is no element

See Also

-

Compare With

Ada: Ada.Containers.Doubly_Linked_Lists.Element

Implementation Note

-

doubly_linked_lists.find( l, e, c )

 

Move the cursor to the location of e in the list Start from the beginning. doubly_linked_lists.has_element will be false if the element is not found.

Example

doubly_linked_lists.find( animal_list, "bear" );

Parameters

Param Mode Type Default Description
l in out doubly_linked_lists.list required the list
e in out list element type required the element to find
c int out doubly_linked_lists.cursor required the position of the element

Exceptions

An exception is raised if the element is the wrong type

See Also

doubly_linked_lists.reverse_find

Compare With

Ada: Ada.Containers.Doubly_Linked_Lists.Find

Implementation Note

Ada version is a function.

doubly_linked_lists.first( l, c )

 

Move the cursor to the first element in the list. doubly_linked_lists.has_element will be false if the list is empty.

Example

doubly_linked_lists.first( animal_list, the_cursor );

Parameters

Param Mode Type Default Description
l in out doubly_linked_lists.list required the list
c in out doubly_linked_lists.cursor required the cursor

Exceptions

An exception is raised if the element type is the wrong type

See Also

doubly_linked_lists.last

Compare With

Ada: Ada.Containers.Doubly_Linked_Lists.First

Implementation Note

Ada version is a function.

e := doubly_linked_lists.first_element( l )

 

Return the first list element.

Example

animal := doubly_listed_lists.first_element( animal_list );

Parameters

Param Mode Type Default Description
e return value list element type required the element
l in doubly_linked_lists.list required the list

Exceptions

An exception is raised if there is no element

See Also

doubly_linked_lists.last_element

Compare With

Ada: Ada.Containers.Doubly_Linked_Lists.First_Element

Implementation Note

-

doubly_linked_lists.flip( l )

 

Reverse the order of the list elements.

Example

doubly_listed_lists.flip( animal_list );

Parameters

Param Mode Type Default Description
l in out doubly_linked_lists.list required the list

Exceptions

-

See Also

doubly_linked_lists.reverse_elements

Compare With

Ada: Ada.Containers.Doubly_Linked_Lists.Reverse_Elements

Implementation Note

This is a renaming of reverse_elements to correspond with arrays.flip.

b := doubly_linked_lists.has_element( c )

 

True if the cursor is positioned at a list element.

Example

if doubly_listed_lists.has_element( list_position ) then ...

Parameters

Param Mode Type Default Description
b return value boolean required true if there's an element
c in doubly_linked_lists.cursor required the cursor

Exceptions

An exception is raised if there is no element

See Also

-

Compare With

Ada: Ada.Containers.Doubly_Linked_Lists.Has_Element

Implementation Note

-

doubly_linked_lists.insert_before( l, c [, n] ) | ( l, c, e [, n] )

 

Insert element e before the cursor c. If no element is given, a node is inserted with an unknown element. If the cursor does not point at an element, the element is appended. If n is given, insert n copies instead of one.

Example

doubly_listed_lists.insert_before( animal_list, porpose_position, "penguin" );

Parameters

Param Mode Type Default Description
l in out doubly_linked_lists.list required true if there's an element
c in doubly_linked_lists.cursor required the cursor to insert before
e in list element type unknown value the element
n in containers.count_type 1 the number of elements

Exceptions

An exception is raised if out of memory

See Also

doubly_linked_lists.insert_before_and_mark

Compare With

Ada: Ada.Containers.Doubly_Linked_Lists.Insert

Implementation Note

Ada is Doubly_Linked_Lists.Insert but insert is a SparForte reserved word.

doubly_linked_lists.insert_before_and_mark( l, c, c2 [, n] ) | ( l, c, e, c2 [, n] )

 

Insert element e before the cursor c and position cursor c2 to the element inserted. If no element is given, a node is inserted with an unknown element. If the cursor does not point at an element, the element is appended. If n is given, insert n copies instead of one.

Example

doubly_listed_lists.insert_before( animal_list, porpose_position, "penguin" );

Parameters

Param Mode Type Default Description
l in out doubly_linked_lists.list required true if there's an element
c in doubly_linked_lists.cursor required the cursor to insert before
e in list element type unknown value the element
c2 out doubly_linked_lists.cursor required the cursor to first element inserted
n in containers.count_type 1 the number of elements

Exceptions

An exception is raised if out of memory

See Also

doubly_linked_lists.insert_before

Compare With

Ada: Ada.Containers.Doubly_Linked_Lists.Insert

Implementation Note

Ada is Doubly_Linked_Lists.Insert but insert is a SparForte reserved word. This is broken into two functions to make parsing easier.

b := doubly_linked_lists.is_empty( l )

 

Return true if the list has no elements.

Example

if doubly_linked_lists.is_empty( animal_list ) then ...

Parameters

Param Mode Type Default Description
b return value boolean required true if empty
l in doubly_linked_lists.list required the list

Exceptions

-

See Also

doubly_linked_lists.contains

Compare With

Ada: Ada.Containers.Doubly_Linked_Lists.Is_Empty

Implementation Note

-

e := doubly_linked_lists.last_element( l )

 

Return the last list element.

Example

animal := doubly_listed_lists.last_element( animal_list );

Parameters

Param Mode Type Default Description
e return value list element type required the element
l in doubly_linked_lists.list required the list

Exceptions

An exception is raised if there is no element

See Also

doubly_linked_lists.first_element

Compare With

Ada: Ada.Containers.Doubly_Linked_Lists.Last_Element

Implementation Note

-

n := doubly_linked_lists.length( l )

 

Return the number of elements in the list.

Example

if doubly_listed_lists.length( animal_list ) > 10 then ...

Parameters

Param Mode Type Default Description
n return value containers.count_type required the number of elements
l in doubly_linked_lists.list required the list

Exceptions

-

See Also

doubly_linked_lists.is_empty

Compare With

Ada: Ada.Containers.Doubly_Linked_Lists.Length

Implementation Note

-

doubly_linked_lists.move( l1, l2 )

 

Overwrite the contents of list l1 with a copy of l2 and erase l2.

Example

doubly_linked_lists.move( destination_list, source_list )

Parameters

Param Mode Type Default Description
l1 in out doubly_linked_lists.list required the destination list
l2 in out doubly_linked_lists.list required the source list

Exceptions

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

See Also

doubly_linked_lists.assign

Compare With

Ada: Ada.Containers.Doubly_Linked_Lists.Move

Implementation Note

-

doubly_linked_lists.new_cursor( c, t )

 

Initialize a new cursor, assigning the element type for the cursor. The element type must be a scalar type, and it may be a universal type.

Example

doubly_linked_lists.new_cursor( animal_position, string );

Parameters

Param Mode Type Default Description
c out doubly_linked_lists.cursor required the cursor to initialize
t in the element type required the type of element

Exceptions

-

See Also

-

Compare With

Ada: N/A (AdaScript extension)

Implementation Note

Allocates a resource for the cursor.

doubly_linked_lists.new_list( l, t )

 

Initialize a new list, assigning the element type for the list. The element type must be a scalar type, and it may be a universal type.

Example

doubly_linked_lists.new_list( animal_position, string );

Parameters

Param Mode Type Default Description
l out doubly_linked_lists.list required the list to initialize
t in the element type required the type of element

Exceptions

-

See Also

-

Compare With

Ada: N/A (AdaScript extension)

Implementation Note

Allocates a resource for the list.

doubly_linked_lists.next( c )

 

Move the cursor to the next element in the list. doubly_linked_lists.has_element will be false if the end of the list is reached. Moving when there is no element will not move the cursor.

Example

doubly_linked_lists.next( animal_position );

Parameters

Param Mode Type Default Description
c in out doubly_linked_lists.cursor required the cursor to move

Exceptions

-

See Also

doubly_linked_lists.previous

Compare With

Ada: Ada.Containers.Doubly_Linked_Lists.Next

Implementation Note

Ada version is a function.

doubly_linked_lists.prepend( l, e )

 

Push list element e on the front of the list.

Example

doubly_linked_lists.prepend( l, "albatross" )

Parameters

Param Mode Type Default Description
l in out doubly_linked_lists.list required the list
e in list element type required the element to push

Exceptions

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

See Also

doubly_linked_lists.append

Compare With

Ada: Ada.Containers.Doubly_Linked_Lists.Prepend

Implementation Note

-

doubly_linked_lists.previous( c )

 

Move the cursor to the previous element in the list. doubly_linked_lists.has_element will be false if the start of the list is reached. Moving when there is no element will not move the cursor.

Example

doubly_linked_lists.previous( animal_position );

Parameters

Param Mode Type Default Description
c in out doubly_linked_lists.cursor required the cursor to move

Exceptions

-

See Also

doubly_linked_lists.next

Compare With

Ada: Ada.Containers.Doubly_Linked_Lists.Previous

Implementation Note

Ada version is a function.

doubly_linked_lists.replace_element( l, c, e )

 

Replace the list element at the cursor position with e.

Example

doubly_linked_lists.replace_element( animal_list, dog_position, "collie" );

Parameters

Param Mode Type Default Description
l in out doubly_linked_lists.list required the list
c in doubly_linked_lists.cursor required the cursor
e in list element type required the element to assign

Exceptions

An exception is raised if the element is the wrong type

See Also

-

Compare With

Ada: Ada.Containers.Doubly_Linked_Lists.Replace_Element

Implementation Note

-

doubly_linked_lists.reverse_elements( l )

 

Reverse the order of the list elements.

Example

doubly_listed_lists.reverse_elements( animal_list );

Parameters

Param Mode Type Default Description
l in out doubly_linked_lists.list required the list

Exceptions

-

See Also

doubly_linked_lists.flip

Compare With

Ada: Ada.Containers.Doubly_Linked_Lists.Reverse_Elements

Implementation Note

-

doubly_linked_lists.reverse_find( l, e, c )

 

Move the cursor to the location of e in the list. Start from the end of the list. doubly_linked_lists.has_element will be false if the element is not found.

Example

doubly_linked_lists.reverse_find( animal_list, "bear", bear_position );

Parameters

Param Mode Type Default Description
l in out doubly_linked_lists.list required the list
e in out list element type required the element to find
c int out doubly_linked_lists.cursor required the position of the element

Exceptions

An exception is raised if the element is the wrong type

See Also

doubly_linked_lists.find

Compare With

Ada: Ada.Containers.Doubly_Linked_Lists.Reverse_Find

Implementation Note

Ada version is a function.

doubly_linked_lists.splice( l1, c, l2 [,c2] ) | ( l1, c, c2 )

 

For (l1, c, l2), move the all the elements of l2 to list l1 before cursor c. If l1 and l2 are the same list, nothing happens.
For (l1, c, l2, c2), move the element of l2 at cursor c2 before cursor c in list l1. If both lists and cursors are the same, nothing happens.
For (l1, c, c2), move the element at cursor c2 in list l1 to new position c. If both cursors are the same, nothing happens.

Example

doubly_linked_lists.splice( animal_list, cat_position, dog_position );

Parameters

Param Mode Type Default Description
l1 in out doubly_linked_lists.list required the target list
l2 in out doubly_linked_lists.list required the source list
c in out doubly_linked_lists.cursor required the target cursor
c2 in out doubly_linked_lists.cursor required the source cursor

Exceptions

An exception is raised if the element type is the wrong type. The element types must be the same for all lists and cursors.

See Also

-

Compare With

Ada: Ada.Containers.Doubly_Linked_Lists.Splice

Implementation Note

Ada version does not necessarily treat all parameters as in out mode.

doubly_linked_lists.swap( l, c1, c2 )

 

Swap the elements at cursor c1 and c2.

Example

doubly_linked_lists.swap( animal_list, cat_position, dog_position );

Parameters

Param Mode Type Default Description
l in out doubly_linked_lists.list required the list
c1 in doubly_linked_lists.cursor required the first cursor
c2 in doubly_linked_lists.cursor required the second cursor

Exceptions

An exception is raised if the element type is the wrong type.
An exception is raised if a cursor points at no element

See Also

doubly_linked_lists.swap_links

Compare With

Ada: Ada.Containers.Doubly_Linked_Lists.Swap

Implementation Note

-

doubly_linked_lists.swap_links( l, c1, c2 )

 

Swap the elements at cursor c1 and c2 by swapping internal pointers. This is usually faster than doubly_linked_lists.swap but causes the cursor positions to be swapped in the list as well.

Example

doubly_linked_lists.swap_links( animal_list, cat_position, dog_position );

Parameters

Param Mode Type Default Description
l in out doubly_linked_lists.list required the list
c1 in doubly_linked_lists.cursor required the first cursor
c2 in doubly_linked_lists.cursor required the second cursor

Exceptions

An exception is raised if the element type is the wrong type.
An exception is raised if a cursor points at no element.

See Also

doubly_linked_lists.swap

Compare With

Ada: Ada.Containers.Doubly_Linked_Lists.Swap_Links

Implementation Note

-

 
[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]