1. Introduction
2. 2D
Geometry
3. 3D
Geometry
4. DXF
5. Display
6. Lists
7. Home
Copyright
(c) 1988-2009 Building Block Software, Inc. All rights reserved.
CAD/CAM
Developer's Kit/3D
Overview
========
The
Building Block Software CAD/CAM Developer's Kits (CCDK) provide
functions
that enable your programs to build and manage
lists of data. These
functions
are collectively called "CCDK/Lists".
Fundamental
Concepts
====================
Introduction
------------
This
section discusses list management without getting into any programming
details. The purpose of this section is to provide
a basis for the sections
of this
reference that present programming
information.
List
Objects
------------
The two
object types used for list management are:
* list
* item
A list
is an ordered collection of objects.
An item
marks a location on a list.
A CCDK
list is a doubly-linked list, and provides a
number of features that
are
important for CAD/CAM and other
applications. These features
are:
* the
ability to navigate forwards and backwards
* the
ability to delete the first object on the list without changing the
address that refers to the head of the list
* the
ability of an object to be on more than one list at a time
* the
ability of an object to be on a list more than once
List
Operations
---------------
The
list operations supported by CCDK/Lists are:
*
construction
*
traversal
*
iteration
Construction
operations create and modify lists.
Traversal
operations step forwards and backwards along lists.
Iteration
operations apply a function to each object on a list.
Object
Types
------------
CCDK/Lists
provides the following two types for list
management:
______________________________________________________________________________
| Type |
Meaning |
|----------------------------------------------------------------------------|
|
DML_LIST | a
list |
|
DML_ITEM | a list item; an object
that |
| |
represents a position on a list |
------------------------------------------------------------------------------
These
types are defined in the header file dmldefs.h.
Attributes
of lists and items should be accessed using functions. Therefore
no
access macros are provided.
Functions
and Action Macros By Category
=======================================
Introduction
------------
This section
presents CCDK/Lists functions grouped according to the
operations
they perform.
Category
Overview
-----------------
List
functions are divided into the following
categories:
*
construction
*
traversal
*
iteration
Construction
functions create and modify lists.
Traversal
functions step along locations on lists.
Iteration
functions apply "actions" to objects on lists.
All
CCDK/Lists functions have the prefix dml, an acronym for "data
management
- lists". Include the header file
dmldefs.h when using any list
functions.
List
Construction
-----------------
The
following functions create lists:
______________________________________________________________________________
|
Function | Use |
|----------------------------------------------------------------------------|
|
dml_create_list |
to create a new list |
|
dml_insert_after |
to insert an item after a given |
| |
item |
|
dml_insert_prior |
to insert an item before a given |
| |
item |
|
dml_append_data |
to add an item to the end of a |
| |
list |
|
dml_remove_item |
to remove an item from a list |
| dml_remove_first | to delete the first
item of a list |
|
dml_remove_last |
to delete the last item of a list |
|
dml_clear_list |
to remove all items from a list |
|
dml_remove_data | to locate the item that
references |
| | a data
record and to remove this |
| | item
from the list |
|
dml_kill_data | to locate the item that references |
| | a data
record, to remove this |
| | item
from the list, and to free |
| | the
data record |
|
dml_append_list |
to append one list to another by |
| |
transferring all items from one |
| | list
to the other list |
|
dml_reverse_list |
to reverse a list |
|
dml_create_copy |
to create a copy of a list |
|
dml_free_list |
to free a list |
| dml_destroy_list | to free all of the
objects on a |
| | list
as well as the list |
------------------------------------------------------------------------------
To put
objects onto a list, the list must first be created with the
dml_create_list
function.
Putting
objects on lists does not affect the objects in any way. An object
may be
on more than one list at a time, and may be on one list more than
once.
Lists
occupy allocated memory and must be freed when they are no longer
needed;
dml_free_list and dml_destroy_list are
provided for this purpose.
dml_destroy_list
should be used with caution because it
frees the objects on
a list
as well as the list itself. If you mean
only to free a list, but to
leave
the objects on the list intact, use
dml_free_list.
The
following functions create lists from arrays, and arrays from lists:
a list;
the objects must all have the same size
the
objects must all have the same size
The
following functions sort lists:
List
Traversal
--------------
The
following functions traverse lists and access
objects stored on lists:
______________________________________________________________________________
|
Function |
Use |
|----------------------------------------------------------------------------|
|
dml_first |
to obtain the first item on a list |
|
dml_last | to obtain the last item on a
list |
|
dml_prev |
to obtain the item before a given |
| |
item |
|
dml_next |
to obtain the item following a |
| | given
item |
|
dml_record |
to obtain the record referenced by |
| | an
item |
|
dml_length |
to obtain the length of a list in |
| |
items |
|
dml_find_data |
to locate the item that references |
| | a data
record |
|
dml_find_test |
to locate the first item on a list |
| | that
references a data record |
| | that passes a user-defined test |
------------------------------------------------------------------------------
The
following macros are used for traversing lists:
______________________________________________________________________________
|
Macro |
Use |
|----------------------------------------------------------------------------|
|
DML_FOR_LOOP(I0,I) |
to walk a list from item I0 to the |
| | end of
the list, returning item I |
| | at
each step |
|
DML_WALK_LIST(L,I) |
to walk list L from the beginning |
| | to the
end, returning item I at |
| | each
step |
------------------------------------------------------------------------------
These
macros, which are aliases for 'for' statements, are defined in
dmldefs.h.
List
Iteration
--------------
The
following functions apply a function to each object on a list. This
process
is called iteration.
function
uses a data record supplied to this function in the course of its
operation
Alphabetized
Reference
======================
***>>
dml_append_data <<***
******
Summary ******
#include
<dmldefs.h>
DML_ITEM
dml_append_data(list,data);
******
Description ******
This
function appends a data record to the end of a list.
******
Input ******
------------------------------------------------------------------------------
|
DML_LIST | list | the list to which a data |
| |
| record is appended |
------------------------------------------------------------------------------
|
ANY | data | the data record to be |
| | | appended |
------------------------------------------------------------------------------
******
See also ******
dml_insert_after,
dml_insert_prior
******
Return Value ******
The
return value is the item on the list referencing the data.
******
Example ******
#include
<string.h>
#include
<dmldefs.h>
void
main()
{
DML_LIST list ;
char *data, input [80] ;
DML_ITEM item ;
list = dml_create_list () ;
printf ("Enter strings or 'quit' to
end.\n" ) ;
do
{
scanf ( "%s", input ) ;
if ( strcmp ( input,
"quit" ) )
{
data = ( char * ) malloc (
strlen ( input) + 1 ) ;
strcpy ( data, input ) ;
dml_append_data ( list, ( ANY
) data ) ;
}
}
while ( strcmp ( input, "quit" )
) ;
for ( item = dml_first ( list ) ; item !=
NULL ;
item = dml_next ( item ))
{
data = ( ANY ) dml_record ( item ) ;
printf ( "%s\n", data ) ;
free ( data ) ;
}
dml_free_list ( list ) ;
}
The
program builds a list of strings read from the keyboard. When the string
"quit"
is encountered, the programs exits the input loop, prints out the
strings,
and frees the data space and the list.
***>>
dml_append_list <<***
******
Summary ******
#include
<dmldefs.h>
DML_LIST
dml_append_list(list1,list2);
******
Description ******
This
function appends the second list to the first. When this function
returns,
all of the items on the second list have been transferred to the
first
list, and the second list is empty. The second list is not freed.
******
Input ******
------------------------------------------------------------------------------
|
DML_LIST |
list1,list2 | the lists to
combine |
------------------------------------------------------------------------------
******
See also ******
dml_append_data,
dml_merge_lists
******
Example ******
#include
<dmldefs.h>
DML_LIST
reverse_and_append
( list1, list2 )
DML_LIST
list1, list2;
{
dml_reverse_list ( list2 );
dml_append_list ( list1, list2 ) ;
dml_free_list ( list2 );
RETURN ( list1 );
}
This
subroutine, whose input is two lists, reverses the second list, appends
the
contents of the second list to the first list, frees the (now empty)
second
list.
***>>
dml_apply <<***
******
Summary ******
#include
<dmldefs.h>
void
dml_apply ( list, action );
******
Description ******
This
function applies an action to each record on a list.
******
Input ******
------------------------------------------------------------------------------
|
DML_LIST | list | a list |
------------------------------------------------------------------------------
|
PF_ACTION | action | an action function |
------------------------------------------------------------------------------
******
Example ******
#include
<qgldefs.h>
#include
<dmldefs.h>
void
main()
{
INT i;
REAL array[10];
DML_LIST list = dml_create_list();
void action ( ANY );
for ( i = 0; i < 10; i++ )
array[i] = i;
dml_copy_array_to_list ( array, 10,
sizeof(REAL), list );
dml_apply ( list, ( PF_VOID ) action );
}
void
action ( record )
ANY
record;
{
REAL *x = ( REAL * ) record;
printf ( "%lf ", *x );
}
This
program builds a list composed of the elements of an array of REALs. It
then
prints out the contents of the list by applying an "action" function to
each
element on the list.
***>>
dml_apply_data <<***
******
Summary ******
#include
<dmldefs.h>
void
dml_apply_data ( list, action, data );
******
Description ******
This
function applies an action to each object on a list. A data record is
provided
by the caller to pass information to the action function.
This
function is useful for applications such as displaying a list of
geometry. The data record can be used to specify
color, line pattern or
other
information. In other words, this
function can "walk" a list of
geometry,
displaying it with the color and pattern information found in a
data
record.
******
Input ******
------------------------------------------------------------------------------
|
DML_LIST | list | a list |
------------------------------------------------------------------------------
|
PF_ACTION_DATA | action | a caller-supplied action |
| | | function; this
function |
| | | should take
two arguments: |
| | | an object (which will
be |
| | | taken from the list),
and a
|
| | | data record that provides |
| | | parameters for applying
the |
| | | action |
------------------------------------------------------------------------------
|
ANY | data | a caller supplied data |
| | | record |
------------------------------------------------------------------------------
******
Example ******
#include
<c2defs.h>
#include
<dmldefs.h>
static void action ( PT2, INT* ) ;
void
modi_pts_list ( pts_list )
DML_LIST
pts_list ;
{
INT coord ;
printf ( "which coordinate do you
want to negate ?\n" ) ;
printf ( "x - enter 0 ; y - enter
1\n" ) ;
scanf ( "%d", &coord ) ;
if ( coord < 0 || coord > 1 )
printf ( "illegal
coordinate\n" ) ;
else
dml_apply_data ( pts_list, action,
&coord ) ;
}
static
void action ( p, coord )
PT2 p ;
INT
*coord ;
{
p[*coord] = - p[*coord] ;
}
This
routine mirrors a list of points about the x or y axis.
***>>
dml_clear_list <<***
******
Summary ******
#include
<dmldefs.h>
void
dml_clear_list(list);
******
Description ******
This
function removes all of the items from a list. The data records
referenced
by the items are not affected.
******
Input ******
------------------------------------------------------------------------------
|
DML_LIST | list | The list to clear |
------------------------------------------------------------------------------
******
See also ******
dml_create_list,
dml_free_list, dml_remove_item
******
Example ******
#include
<qgldefs.h>
#include
<dmldefs.h>
void
main()
{
INT i;
REAL array[10];
DML_LIST list = dml_create_list();
void action ( ANY );
for ( i = 0; i < 10; i++ )
array[i] = i;
dml_copy_array_to_list ( array, 10,
sizeof(REAL), list );
printf ( "The length of the list is
%d",
( INT ) DML_LENGTH(list) );
dml_clear_list ( list );
printf ( "The length of the list is
%d",
( INT ) DML_LENGTH(list) );
}
This
program builds a list composed of the elements of an array of REALs.
After
printing out the length of the list, it clears the list and prints the
length
again to show that the list is empty.
***>>
dml_copy_array_to_list <<***
******
Summary ******
#include
<dmldefs.h>
void
dml_copy_array_to_list ( x, n, size, list );
******
Description ******
This
function appends all the elements of an array to a list.
******
Input ******
------------------------------------------------------------------------------
|
ANY | x | an array |
------------------------------------------------------------------------------
|
INT | n | the number of elements
in |
| | | the array |
------------------------------------------------------------------------------
|
INT | size | the size of an element
in |
| | | the array |
------------------------------------------------------------------------------
|
DML_LIST | list | the list to append the |
| | | records to |
------------------------------------------------------------------------------
******
Example ******
#include
<qgldefs.h>
#include
<dmldefs.h>
void
main()
{
INT i;
REAL array[10];
DML_LIST list = dml_create_list();
for ( i = 0; i < 10; i++ )
array[i] = i;
dml_copy_array_to_list ( array, 10,
sizeof(REAL), list);
}
This
program builds a list composed of the elements of an array of REALs.
***>>
dml_copy_list_to_array <<***
******
Summary ******
#include
<dmldefs.h>
void
dml_copy_list_to_array ( list, x, size
);
******
Description ******
This
function copies all the records on a list into a preallocated array.
All the
records on the list must have the same size.
******
Input ******
------------------------------------------------------------------------------
|
DML_LIST | list | a list |
------------------------------------------------------------------------------
|
ANY | x | a preallocated array
large |
| | | enough to hold all the |
| | | records on the list |
------------------------------------------------------------------------------
|
INT | size | the size of the records on |
| | | the list |
------------------------------------------------------------------------------
******
Example ******
#include
<qgldefs.h>
#include
<dmldefs.h>
void
main()
{
DML_LIST list = dml_create_list();
REAL x = 4.0, y = 2.0, z = 7.0, array[3];
INT i;
dml_append_data ( list, ( ANY ) &x );
dml_append_data ( list, ( ANY ) &y );
dml_append_data ( list, ( ANY ) &z );
dml_copy_list_to_array ( list, array,
sizeof(REAL) );
for ( i = 0; i < 3; i++ )
printf ( "%lf ", array[i]
);
}
This
program copies the contents of a list into an array.
***>>
dml_create_array_to_list <<***
******
Summary ******
#include
<dmldefs.h>
DML_LIST
dml_create_array_to_list ( x, n, size
);
******
Description ******
This
function creates a list composed of the elements of an array.
******
Input ******
------------------------------------------------------------------------------
|
ANY | x | the array of data
records |
------------------------------------------------------------------------------
|
INT | n | the number of data records |
| | | in the array |
------------------------------------------------------------------------------
|
INT | size | the size of a data
record |
------------------------------------------------------------------------------
******
Return Value ******
The
return value is list which contains all of the data records in the
array.
If the list could not be created, NULL is returned.
******
Example ******
#include
<c2defs.h>
#include
<dmldefs.h>
void
main()
{
PT2 x[10];
DML_LIST list;
INT i;
for ( i = 0; i < 10; i++ )
{
PT2_X(x[i]) = i;
PT2_Y(x[i]) = 10.0 - i;
}
list = dml_create_array_to_list ( x, 10,
sizeof(PT2) );
dml_free_list ( list );
}
This
program builds an array of points, and then creates a list consisting
of
these points.
***>>
dml_create_copy <<***
******
Summary ******
#include
<dmldefs.h>
DML_LIST
dml_create_copy ( inlist );
******
Description ******
This
function creates a copy of list. The
objects on the input list are
also on
the output list, but are not affected in any other way.
******
Input ******
------------------------------------------------------------------------------
|
DML_LIST | inlist | a list to copy |
------------------------------------------------------------------------------
******
Return Value ******
The
return value is a copy of the input list.
******
Example ******
#include
<qgldefs.h>
#include
<dmldefs.h>
DML_LIST
reverse_list ( inlist )
DML_LIST
inlist ;
{
DML_LIST outlist = dml_create_copy (
inlist ) ;
dml_reverse_list ( outlist ) ;
RETURN ( outlist ) ;
}
This
routines creates a reversed copy of a list.
***>>
dml_create_list <<***
******
Summary ******
#include
<dmldefs.h>
DML_LIST
dml_create_list(void);
******
Description ******
This
function creates a new list.
******
Return Value ******
The
return value is the created list.
******
See also ******
dml_free_list,
dml_array_list
******
Example ******
#include
<qgldefs.h>
#include
<dmldefs.h>
void
main()
{
DML_LIST list = dml_create_list () ;
REAL x, y, z;
dml_append_data ( list, ( ANY ) &x );
dml_append_data ( list, ( ANY ) &y );
dml_append_data ( list, ( ANY ) &z );
}
This
program creates a list and appends three REALs to it.
***>>
dml_create_list_to_array <<***
******
Summary ******
#include
<dmldefs.h>
ANY
dml_create_list_to_array ( list, size
);
******
Description ******
This
function creates an array composed of copies of objects on a list. The
objects
on the list must all have the same size. The array should be freed
with
the free function when it is no longer
needed. The objects on the list
are not
affected.
******
Input ******
------------------------------------------------------------------------------
|
DML_LIST | list | a list |
------------------------------------------------------------------------------
|
INT | size | the size of the objects
on |
| | | the list |
------------------------------------------------------------------------------
******
Return Value ******
The
return value is a pointer to an array composed of copies of all the
records
on the input list.
******
Example ******
#include
<qgldefs.h>
#include
<dmldefs.h>
void
main()
{
DML_LIST list = dml_create_list () ;
REAL x, y, z, *array;
dml_append_data ( list, ( ANY ) &x );
dml_append_data ( list, ( ANY ) &y );
dml_append_data ( list, ( ANY ) &z );
array = dml_create_list_to_array ( list,
sizeof(REAL) );
free ( array );
}
This
program creates an array that contains copies of the elements on a
list.
The created array occupies allocated space and must be freed when it
is no
longer needed.
***>>
dml_destroy_list <<***
******
Summary ******
#include
<dmldefs.h>
void
dml_destroy_list ( list, free_function
);
******
Description ******
This
routine frees all of the records on a list using free_function, and
then
frees the list itself.
******
Input ******
------------------------------------------------------------------------------
|
DML_LIST | list | list of data records to
be |
| | | freed; it is a good
practice |
| | | to
set this parameter to |
| | | NULL after calling
this |
| | | function |
------------------------------------------------------------------------------
|
PF_ACTION |
free_function | pointer to a
function that |
| | | frees the data records
on |
| | | the list; this function |
| | | must return void |
------------------------------------------------------------------------------
******
Example ******
#include
<qgldefs.h>
#include
<dmldefs.h>
void
main()
{
DML_LIST list = dml_create_list();
void free_function ( ANY );
REAL *x;
INT i;
for ( i = 0; i < 10; i++ ) {
x = ( REAL * ) malloc ( sizeof(REAL)
);
*x = i;
dml_append_data ( list, ( ANY ) x );
}
dml_destroy_list ( list, free_function );
}
void
free_function ( record )
ANY
record;
{
free ( record );
}
This
program builds a list of REALs, and then frees the REALs and the list.
***>>
dml_find_data <<***
******
Summary ******
#include
<dmldefs.h>
DML_ITEM
dml_find_data ( list, data );
******
Description ******
This
function locates the position of an object in a list.
******
Input ******
------------------------------------------------------------------------------
|
DML_LIST | list | a list |
------------------------------------------------------------------------------
|
ANY | data | a pointer to the data or |
| | | object to search for |
------------------------------------------------------------------------------
******
Return Value ******
The
return value is the item where the data is located on the list. If
the
data
could not be found, NULL is returned.
******
Example ******
#include
<qgldefs.h>
#include
<dmldefs.h>
void
find_in_list ()
{
INT a[10], i ;
DML_LIST list ;
DML_ITEM item ;
for ( i = 0; i < 10; i++ ) a[i] = 10 -
i;
list = dml_create_array_to_list ( a, 10, sizeof(INT)
);
printf ( "which array element do you
want to find?\n" );
scanf ( "%d", &i ) ;
item = dml_find_data ( list, &a[i] ) ;
if ( item == NULL )
printf ( "List does not contain
this record.\n" ) ;
else
printf ( "The value of the data
is %d\n",
dml_record(item) ) ;
dml_free_list ( list ) ;
}
This
routine creates a list referencing elements of an array of integers,
and
then locates a specified element on the list.
***>>
dml_find_test <<***
******
Summary ******
#include
<dmldefs.h>
DML_ITEM
dml_find_test ( list, test );
******
Description ******
This
function locates the position on a list of the first object that causes
a test
function to return TRUE.
******
Input ******
------------------------------------------------------------------------------
|
DML_LIST | list | a list |
------------------------------------------------------------------------------
|
PF_TEST | test | a pointer to the test
|
| | | function that takes a
data |
| | | record as an input argument |
| | | and returns a
BOOLEAN |
------------------------------------------------------------------------------
******
Return Value ******
The
return value is the first item where the qualifying data is located on
the
list. If no qualifying data could be found,
NULL is returned.
******
Example ******
#include
<c2defs.h>
#include
<dmldefs.h>
static
BOOLEAN pt_test ( PT2 ) ;
void
line_test ( pts_list )
DML_LIST
pts_list ;
{
DML_ITEM item ;
PT2 *p ;
item = dml_find_test ( pts_list, pt_test )
;
if ( item == NULL )
printf ( "There are no points
below the x axis.\n" );
else {
p = dml_record(item) ;
printf ( "the first point with
y < 0 is %lf %lf\n",
PT2_X(*p), PT2_Y(*p) ) ;
}
}
static
BOOLEAN pt_test ( p )
PT2 p ;
{
RETURN ( PT2_Y(p) < 0.0 ) ;
}
This
routine finds the first point on a list which has a negative y-
coordinate.
***>>
dml_first <<***
******
Summary ******
#include
<dmldefs.h>
DML_ITEM
dml_first(list);
******
Description ******
This
function returns a pointer to the first item of a list. If list is
NULL,
or the list is empty, NULL is returned.
******
Input ******
------------------------------------------------------------------------------
|
DML_LIST | list | a list |
------------------------------------------------------------------------------
******
Return Value ******
The
return value is the first item of the input list.
******
Example ******
#include
<string.h>
#include
<qgldefs.h>
#include
<dmldefs.h>
void
main ()
{
DML_LIST list = dml_create_list();
DML_ITEM item ;
INT i;
char names[3][16], *name;
strcpy ( names[0], "Line" );
strcpy ( names[1], "Arc" );
strcpy ( names[2], "Spline" );
for ( i = 0; i < 3; i++ )
dml_append_data ( list, ( ANY )
names[i] );
for ( item = dml_first ( list ); item !=
NULL;
item = dml_next ( item ) ) {
name = ( char * ) dml_record ( item
) ;
printf ( "%s\n", name ) ;
}
}
This
program builds a list of names, walks the list and prints the names.
***>>
dml_free_list <<***
******
Summary ******
#include
<dmldefs.h>
void
dml_free_list(list)
******
Description ******
This
function frees a list. This function does not affect data records
referenced
by the list.
******
Input ******
------------------------------------------------------------------------------
|
DML_LIST | list | the list to free; it is
a |
| | | good practice to set this |
| | | parameter to NULL after |
| | | calling this
function |
------------------------------------------------------------------------------
******
See also ******
dml_create_list,
dml_clear_list
******
Example ******
#include
<qgldefs.h>
#include
<dmldefs.h>
void
main()
{
DML_LIST list = dml_create_list () ;
REAL x = 4.0, y = 8.0;
dml_append_data ( list, ( ANY ) &x );
dml_append_data ( list, ( ANY ) &y );
dml_free_list ( list ) ;
}
This
program builds a list of two elements, and then frees the list. The
elements
x and y are unaffected.
***>>
DML_FOR_LOOP <<***
******
Summary ******
#include
<dmldefs.h>
DML_FOR_LOOP
( item0, item );
******
Description ******
This
macro is shorthand for the following 'for' loop:
for ( item = item0; item != NULL;
item = dml_next ( item ) )
******
Input ******
------------------------------------------------------------------------------
|
DML_ITEM | item0 | starting item |
------------------------------------------------------------------------------
|
DML_ITEM | item | current item |
------------------------------------------------------------------------------
******
Example ******
#include
<qgldefs.h>
#include
<dmldefs.h>
void
main()
{
REAL a = 4.0, b = 7.0, c = 5.0;
DML_LIST list = dml_create_list();
DML_ITEM item;
dml_append_data ( list, ( ANY ) &a );
dml_append_data ( list, ( ANY ) &b );
dml_append_data ( list, ( ANY ) &c );
DML_FOR_LOOP ( dml_first ( list ), item );
printf ( "%lf\n",
*((REAL*)dml_record(item)) );
}
This
program prints out a list of REALs.
***>>
dml_insert_after <<***
******
Summary ******
#include
<dmldefs.h>
DML_ITEM
dml_insert_after(list,prev_item,data);
******
Description ******
This
function inserts data onto a list. The data is placed after the item
indicated
by prev_item. The data is inserted at the head
of the list if
prev_item
is NULL. No check is made to determine
if prev_item is an actual
item on
the list provided.
******
Input ******
------------------------------------------------------------------------------
|
DML_LIST | list | the list onto which data
is |
| | | inserted |
------------------------------------------------------------------------------
|
DML_ITEM | prev_item | the item after which data is |
| | | inserted after |
------------------------------------------------------------------------------
|
ANY | data | the data record to be |
| | | inserted |
------------------------------------------------------------------------------
******
See also ******
dml_insert_prior,
dml_append_data
******
Return Value ******
The
return value is the item added to the list.
******
Example ******
#include
<qgldefs.h>
#include
<dmldefs.h>
void
main ()
{
DML_LIST list = dml_create_list ()
;
REAL x = 4.0, y = 8.0, z = 1.0;
DML_ITEM item ;
dml_append_data ( list, ( ANY ) &x );
dml_append_data ( list, ( ANY ) &z );
item = dml_first ( list );
dml_insert_after ( list, item, ( ANY )
&y ) ;
}
This
program inserts an element into a list at the position following the
first
element on the list.
***>>
dml_insert_prior <<***
******
Summary ******
#include
<dmldefs.h>
DML_ITEM
dml_insert_prior(list,next_item,data);
******
Description ******
This
function inserts data onto a list. The data is placed prior to the item
indicated
by next_item. The data is inserted at the
tail of the list if
next_item
is NULL. No check is made to determine
if next_item is an actual
item on
the list provided.
******
Input ******
------------------------------------------------------------------------------
|
DML_LIST | list | the list onto which data
is |
| | | inserted |
------------------------------------------------------------------------------
|
DML_ITEM | next_item | the item before which data |
| | | is inserted |
------------------------------------------------------------------------------
|
ANY | data | the data record to be |
| | | inserted |
------------------------------------------------------------------------------
******
See also ******
dml_insert_after,
dml_append_data
******
Return Value ******
The
return value is the item added to the list.
******
Example ******
#include
<qgldefs.h>
#include
<dmldefs.h>
void
main ()
{
DML_LIST list = dml_create_list () ;
REAL x = 4.0, y = 8.0, z = 1.0;
DML_ITEM item ;
dml_append_data ( list, ( ANY ) &x );
dml_append_data ( list, ( ANY ) &z );
item = dml_last ( list );
dml_insert_prior ( list, item, ( ANY )
&y ) ;
}
This
program inserts an element into a list at the position preceding the
last
element on the list.
***>>
dml_kill_data <<***
******
Summary ******
#include
<dmldefs.h>
BOOLEAN
dml_kill_data ( list, data, data_destructor
);
******
Description ******
This
function locates a data record on a list, removes it from the list, and
frees
the data record.
******
Input ******
------------------------------------------------------------------------------
|
DML_LIST | list | a list |
------------------------------------------------------------------------------
|
ANY | data | the data record to
search |
| | | for |
------------------------------------------------------------------------------
|
PF_ACTION |
data_destructor | the function that
frees the |
| | |
data record |
------------------------------------------------------------------------------
******
Return Value ******
The
return value is TRUE if the data record was located and freed. Otherwise
it is
FALSE.
******
Example ******
#include
<c2ddefs.h>
#include
<dmldefs.h>
void
kill_curve ( curves, curve )
DML_LIST
curves ;
C2_CURVE
curve ;
{
if ( !dml_kill_data ( curves, curve,
c2d_free_curve ) )
printf ( "the curve is not on
the list\n" ) ;
}
This
routine removes a specified curve from a list of curves, and frees the
curve.
***>>
dml_last <<***
******
Summary ******
#include
<dmldefs.h>
DML_ITEM
dml_last(list);
******
Description ******
This
function returns pointer to the last item of a list. If list is NULL,
or the
list is empty, NULL is returned.
******
Input ******
------------------------------------------------------------------------------
|
DML_LIST | list | a list |
------------------------------------------------------------------------------
******
Return Value ******
The
return value is the last item of the list.
******
Example ******
#include
<string.h>
#include
<qgldefs.h>
#include
<dmldefs.h>
void
main ()
{
DML_LIST list = dml_create_list();
DML_ITEM item ;
INT i;
char names[3][16], *name;
strcpy ( names[0], "Line" );
strcpy ( names[1], "Arc" );
strcpy ( names[2], "Spline" );
for ( i = 0; i < 3; i++ )
dml_append_data ( list, ( ANY )
names[i] );
for ( item = dml_last ( list ); item !=
NULL;
item = dml_prev ( item ) ) {
name = ( char * ) dml_record ( item
) ;
printf ( "%s\n", name ) ;
}
}
This
program builds a list of names, and then prints the list out in reverse
order.
***>>
dml_length <<***
******
Summary ******
#include
<dmldefs.h>
INT
dml_length(list);
******
Description ******
This
function returns the number of items on a list. If list is NULL, or the
list is
empty, 0 is returned.
******
Input ******
------------------------------------------------------------------------------
|
DML_LIST | list | a list |
------------------------------------------------------------------------------
******
Return Value ******
The
return value is the number of items on the input list.
******
Example ******
#include
<qgldefs.h>
#include
<dmldefs.h>
void
main ()
{
DML_LIST list = dml_create_list () ;
INT i = 9, j = 6, k = 2 ;
dml_append_data ( list, ( ANY ) &i );
dml_append_data ( list, ( ANY ) &j );
dml_append_data ( list, ( ANY ) &k );
printf ( "%d", dml_length ( list
) );
}
This
program builds a list of integers and prints the list length.
***>>
dml_merge_lists <<***
******
Summary ******
#include
<dmldefs.h>
DML_LIST
dml_merge_lists(list1,list2,sort_key);
******
Description ******
This
function merges two sorted lists by inserting objects on the second
list
into the first list to form a sorted list.
The insertion positions are
determined
by the sort_key function, which
determines the relative order of
objects.
Note:
Before this function is called, the two lists must have been sorted.
The
second list is returned empty, but not freed.
******
Input ******
------------------------------------------------------------------------------
|
DML_LIST | list1,
list2 | sorted lists to be
merged; |
| | | both lists are modified
by |
| | | this routine |
------------------------------------------------------------------------------
|
PF_SORT | sort_key | pointer to a BOOLEAN sort |
| | | key function |
------------------------------------------------------------------------------
The
sort_key function is a user-supplied function that compares two data
records
to determine their relative order on the list. If the first record
should
precede the second record, the sort_key
function should return TRUE;
otherwise
the sort_key function should return
FALSE.
******
See also ******
dml_append_data,
dml_sort_list
******
Example ******
#include
<string.h>
#include
<qgldefs.h>
#include
<dmldefs.h>
BOOLEAN
alphabetize_key ( char *, char * ) ;
void
main ()
{
DML_LIST list1 = dml_create_list(),
list2 = dml_create_list() ;
char a[16], b[16], c[16], d[16];
strcpy ( a, "Intersect" );
dml_append_data ( list1, ( ANY ) a );
strcpy ( b, "Rotate" );
dml_append_data ( list1, ( ANY ) b );
strcpy ( c, "Mirror" );
dml_append_data ( list2, ( ANY ) c );
strcpy ( d, "Offset" );
dml_append_data ( list2, ( ANY ) d );
dml_merge_lists ( list1, list2,
( PF_BOOLEAN ) alphabetize_key ) ;
dml_free_list ( list2 ) ;
}
BOOLEAN
alphabetize_key ( data1, data2 )
char
*data1, *data2 ;
{
return ( strcmp ( data1, data2 ) < 0 )
;
/* TRUE if data1 precedes data2
alphabetically */
}
After
building two lists of names, this program merges the lists to produce
one
list which is organized in alphabetical order.
***>>
dml_next <<***
******
Summary ******
#include
<dmldefs.h>
DML_ITEM
dml_next(item);
******
Description ******
This
function returns the item following the input item. If the input item
is the
last item on the list, or is NULL, the returned value is NULL.
******
Input ******
------------------------------------------------------------------------------
|
DML_ITEM | item | an item |
------------------------------------------------------------------------------
******
Return Value ******
The
return value is the item following item.
If item is the last item on a
list,
or is NULL, NULL is returned.
******
See also ******
dml_prev
******
Example ******
#include
<string.h>
#include
<qgldefs.h>
#include
<dmldefs.h>
void
main () {
DML_LIST list = dml_create_list();
DML_ITEM item ;
INT i;
char names[3][16];
strcpy ( names[0], "Line" );
strcpy ( names[1], "Arc" );
strcpy ( names[2], "Spline" );
for ( i = 0; i < 3; i++ )
dml_append_data ( list, ( ANY )
names[i] );
for ( item = dml_first ( list ); item !=
NULL;
item = dml_next ( item ) )
printf ( "%s\n", ( char *
) dml_record ( item ) ) ;
}
After
building a list of names, this program walks the list from start to
end and
prints out the names.
***>>
dml_prev <<***
******
Summary ******
#include
<dmldefs.h>
DML_ITEM
dml_prev(item);
******
Description ******
This
function returns the item preceding the input item. If the input item
is the
first item of a list or item is NULL, the returned value is NULL.
******
Input ******
------------------------------------------------------------------------------
|
DML_ITEM | item | an item |
------------------------------------------------------------------------------
******
Return Value ******
The
return value is the item that precedes item. If item is the first item
on a
list, or is NULL, the return value is NULL.
******
See also ******
dml_next
******
Example ******
#include
<string.h>
#include
<qgldefs.h>
#include
<dmldefs.h>
void
main ()
{
DML_LIST list = dml_create_list();
DML_ITEM item ;
INT i;
char names[3][16];
strcpy ( names[0], "Line" );
strcpy ( names[1], "Arc" );
strcpy ( names[2], "Spline" );
for ( i = 0; i < 3; i++ )
dml_append_data ( list, ( ANY )
names[i] );
for ( item = dml_last ( list ); item !=
NULL;
item = dml_prev ( item ) )
printf ( "%s\n", ( char *
) dml_record ( item ) ) ;
}
After
building a list of names, this program walks the list backwards and
prints
out the names.
***>>
dml_record <<***
******
Summary ******
#include
<dmldefs.h>
ANY
dml_record(item);
******
Description ******
This
function returns a pointer to the data record referenced by an item.
******
Input ******
------------------------------------------------------------------------------
|
DML_ITEM | item | an item on a list |
------------------------------------------------------------------------------
Return
Value
The
return value is a pointer to the data record referenced by the item. If
item is
NULL, the value returned is also NULL.
******
Example ******
#include
<string.h>
#include
<qgldefs.h>
#include
<dmldefs.h>
void
main ()
{
DML_LIST list = dml_create_list();
DML_ITEM item ;
INT i;
char names[3][16], *name;
strcpy ( names[0], "Line" );
strcpy ( names[1], "Arc" );
strcpy ( names[2], "Spline" );
for ( i = 0; i < 3; i++ )
dml_append_data ( list, ( ANY )
names[i] );
for ( item = dml_first ( list ); item !=
NULL;
item = dml_next ( item ) )
{
name = ( char * ) dml_record ( item
) ;
printf ( "%s\n", name ) ;
}
}
After
building a list of names, this program walks the list from start to
end and
prints out the names.
***>>
dml_remove_data <<***
******
Summary ******
#include
<dmldefs.h>
BOOLEAN
dml_remove_data ( list, data );
******
Description ******
This
function locates the item in a list which references a given data
record,
and removes it from the list. It does
not modify or free the data
record.
******
Input ******
------------------------------------------------------------------------------
|
DML_LIST | list | a list |
------------------------------------------------------------------------------
|
ANY | data | the data record to
search |
| | | for |
------------------------------------------------------------------------------
******
Return Value ******
This
function returns TRUE if it successfully found the given data record
and
removed its reference from the list.
Otherwise, it returns FALSE.
******
Example ******
#include
<string.h>
#include
<qgldefs.h>
#include
<dmldefs.h>
void
main ()
{
DML_LIST list = dml_create_list();
INT i;
char names[3][16];
strcpy ( names[0], "Line" );
strcpy ( names[1], "Arc" );
strcpy ( names[2], "Spline" );
for ( i = 0; i < 3; i++ )
dml_append_data ( list, ( ANY )
names[i] );
dml_remove_data ( list, names[1] );
}
This
program builds a list of names, and then searches the list for a
reference
to the name "Arc", and removes it.
***>>
dml_remove_first <<***
******
Summary ******
#include
<dmldefs.h>
void
dml_remove_first(list);
******
Description ******
This
function removes the first item from the specified list. The data
record
referenced by the first item is not affected.
******
Input ******
------------------------------------------------------------------------------
|
DML_LIST | list | the list from which to |
| | | remove the first
item |
------------------------------------------------------------------------------
******
See also ******
dml_remove_item,
dml_remove_last
******
Example ******
#include
<string.h>
#include
<qgldefs.h>
#include
<dmldefs.h>
void
main ()
{
DML_LIST list = dml_create_list();
INT i;
char names[3][16];
strcpy ( names[0], "Line" );
strcpy ( names[1], "Arc" );
strcpy ( names[2], "Spline" );
for ( i = 0; i < 3; i++ )
dml_append_data ( list, ( ANY )
names[i] );
printf ( "list length: %d\n", (
INT ) DML_LENGTH(list) );
dml_remove_first ( list );
printf ( "list length: %d\n", (
INT ) DML_LENGTH(list) );
}
This
program builds a list, and then removes the first item from the list.
***>>
dml_remove_item <<***
******
Summary ******
#include
<dmldefs.h>
void
dml_remove_item(list,item);
******
Description ******
This
function removes the specified item from the specified list. It does
not
check if the item is on the list.
The
data record referenced by the item is not affected.
******
Input ******
------------------------------------------------------------------------------
|
DML_LIST | list | the list from which to |
| | | remove the item |
------------------------------------------------------------------------------
|
DML_ITEM | item | the item to remove |
------------------------------------------------------------------------------
******
Example ******
#include
<string.h>
#include
<qgldefs.h>
#include
<dmldefs.h>
void
main ()
{
DML_LIST list = dml_create_list();
DML_ITEM item ;
char names[3][16];
INT i;
strcpy ( names[0], "Line" );
strcpy ( names[1], "Arc" );
strcpy ( names[2], "Spline" );
for ( i = 0; i < 3; i++ )
dml_append_data ( list, ( ANY )
names[i] );
printf ( "list length: %d\n", (
INT ) dml_length(list));
item = dml_next ( dml_first ( list ) );
dml_remove_item ( list, item );
}
This
program removes the second item from a list.
***>>
dml_remove_last <<***
******
Summary ******
#include
<dmldefs.h>
void
dml_remove_last(list);
******
Description ******
This
function removes the last item from the specified list. The data record
referenced
by the last item is not affected.
******
Input ******
------------------------------------------------------------------------------
|
DML_LIST | list | the list from which to |
| | | remove the last
item |
------------------------------------------------------------------------------
******
See also ******
dml_remove_item,
dml_remove_first
******
Example ******
#include
<string.h>
#include
<qgldefs.h>
#include
<dmldefs.h>
void
main ()
{
DML_LIST list = dml_create_list();
INT i;
char names[3][16];
strcpy ( names[0], "Line" );
strcpy ( names[1], "Arc" );
strcpy ( names[2], "Spline" );
for ( i = 0; i < 3; i++ )
dml_append_data ( list, ( ANY )
names[i] );
dml_remove_last ( list );
}
This
program removes the last item from a list.
***>>
dml_reverse_list <<***
******
Summary ******
#include
<dmldefs.h>
DML_LIST
dml_reverse_list(list);
******
Description ******
This
function reverses the specified list.
******
Input ******
------------------------------------------------------------------------------
|
DML_LIST | list | the list to reverse |
------------------------------------------------------------------------------
******
Return Value ******
The
return value is the input list.
******
Example ******
#include
<string.h>
#include
<qgldefs.h>
#include
<dmldefs.h>
void
main ()
{
DML_LIST list = dml_create_list();
DML_ITEM item ;
INT i;
char names[3][16];
strcpy ( names[0], "Line" );
strcpy ( names[1], "Arc" );
strcpy ( names[2], "Spline" );
for ( i = 0; i < 3; i++ )
dml_append_data ( list, ( ANY )
names[i] );
DML_WALK_LIST ( list, item )
printf ( "%s\n", ( char *
) dml_record ( item ) );
dml_reverse_list ( list );
DML_WALK_LIST ( list, item )
printf ( "%s\n", ( char *
) dml_record ( item ) );
}
After
building a list of names, this program reverses the list.
***>>
dml_sort_list <<***
******
Summary ******
#include
<dmldefs.h>
DML_LIST
dml_sort_list(list,sort_key);
******
Description ******
This
function sorts a list according to the provided comparison key,
sort_key.
******
Input ******
------------------------------------------------------------------------------
|
DML_LIST | list | list to be sorted |
------------------------------------------------------------------------------
|
PF_SORT | sort_key | pointer to a BOOLEAN sort |
| | | key function |
------------------------------------------------------------------------------
The
sort_key function is a user-supplied function that compares two data
records
and and determines their relative order.
If the first record should
precede
the second record, the sort_key
function should return TRUE;
otherwise
the sort_key function should return
FALSE.
******
Return Value ******
The
return value is the input list.
******
Example ******
#include
<string.h>
#include
<qgldefs.h>
#include
<dmldefs.h>
BOOLEAN
alphabetize_key ( char *, char * ) ;
void
main ()
{
DML_LIST list = dml_create_list();
DML_ITEM item ;
INT i;
char names[3][16];
strcpy ( names[0], "Line" );
strcpy ( names[1], "Arc" );
strcpy ( names[2], "Spline" );
for ( i = 0; i < 3; i++ )
dml_append_data ( list, ( ANY )
names[i] );
DML_WALK_LIST ( list, item )
printf ( "%s\n", ( char *
) dml_record ( item ) );
dml_sort_list ( list, ( PF_BOOLEAN )
alphabetize_key );
DML_WALK_LIST ( list, item )
printf ( "%s\n", ( char *
) dml_record ( item ) );
}
BOOLEAN
alphabetize_key ( data1, data2 )
char
*data1, *data2 ;
{
return ( strcmp ( data1, data2 ) < 0 )
;
/* TRUE if data1 precedes data2
alphabetically */
}
After
building a list of names, this program alphabetizes the list.
***>>
dml_sort_list_data <<***
******
Summary ******
#include
<dmldefs.h>
DML_LIST
dml_sort_list_data ( list, sort_key, sort_data
);
******
Description ******
This
function sorts a list according to the provided comparison key,
sort_key,
and a data record. The data record can
contain some information
needed
for determining relative order of data records
on the list.
******
Input ******
------------------------------------------------------------------------------
|
DML_LIST | list | list to be sorted |
------------------------------------------------------------------------------
|
PF_SORT_DATA | sort_key | pointer to a BOOLEAN sort |
| | | key function |
------------------------------------------------------------------------------
The
sort_key function is a user-supplied function that compares two data
records
and determines their relative order. If
the first record should
precede
the second record, the sort_key
function should return TRUE;
otherwise
the sort_key function should return
FALSE.
------------------------------------------------------------------------------
|
ANY | sort_data | a data record used by the |
| | | sort_key to
determine |
| | | relative order of objects
|
| | | on the list |
------------------------------------------------------------------------------
******
Return Value ******
The
return value is the input list.
******
Example ******
#include
<c2defs.h>
#include
<dmldefs.h>
static BOOLEAN sort_key ( PT2, PT2, INT* ) ;
void
sort_pts_list ( pts_list )
DML_LIST
pts_list ;
{
INT sort_coord ;
printf ( "sort by which
coordinate?\n" ) ;
printf ( "x - enter 0 ; y - enter
1\n" ) ;
scanf ( "%d", &sort_coord ) ;
if ( sort_coord < 0 || sort_coord >
1 )
printf ( "illegal
coordinate\n" ) ;
else
dml_sort_list_data ( pts_list,
sort_key, &sort_coord ) ;
}
static
BOOLEAN sort_key ( p1, p2, coord )
PT2 p1,
p2 ;
INT
*coord ;
{
RETURN ( p1[*coord] < p2[*coord] ) ;
}
This
routine sorts a list points according to the specified coordinate.
***>>
DML_WALK_LIST <<***
******
Summary ******
#include
<dmldefs.h>
DML_WALK_LIST
( list, item );
******
Description ******
This
macro is shorthand for the following 'for' loop:
for ( item = dml_first ( list );
item != NULL; item = dml_next ( item
) )
******
Input ******
------------------------------------------------------------------------------
|
DML_LIST | list | a list |
------------------------------------------------------------------------------
|
DML_ITEM | item | current item |
------------------------------------------------------------------------------
******
Example ******
#include
<qgldefs.h>
#include
<dmldefs.h>
void
main()
{
REAL a = 4.0, b = 7.0, c = 5.0;
DML_LIST list = dml_create_list();
DML_ITEM item;
dml_append_data ( list, ( ANY ) &a );
dml_append_data ( list, ( ANY ) &b );
dml_append_data ( list, ( ANY ) &c );
DML_WALK_LIST ( list, item );
printf ( "%lf\n",
*((REAL*)dml_record(item)) );
}
This
program prints out a list of REALs.