AutoLISP Lists

The acutBuildList() function is called in conjunction with acedRetList(), which returns a list structure to AutoLISP.

The following sample code fragment passes a list of four points:

struct resbuf *res_list; 
ads_point ptarray[4]; 
// Initialize the point values here.  
. 
. 
. 
res_list = acutBuildList(
    RT3DPOINT, ptarray[0], 
    RT3DPOINT, ptarray[1], 
    RT3DPOINT, ptarray[2], 
    RT3DPOINT, ptarray[3], 0); 
if (res_list == NULL) { 
    acdbFail("Couldn't create list\n"); 
    return BAD; 
} 
acedRetList(res_list); 
acutRelRb(res_list); 

Dotted pairs and nested lists can be returned to AutoLISP by calling acutBuildList() to build a list created with the special list-construction type codes. These codes are needed only for complex lists. For ordinary (that is, one-dimensional) lists, acedRetList() can be passed a simple list of result buffers, as shown in the previous example.

Note: A list returned to AutoLISP by acedRetList() can include only the following result type codes: RTREAL, RTPOINT, RTSHORT, RTANG, RTSTR, RTENAME, RTPICKS, RTORINT, RT3DPOINT, RTLB, RTLE, RTDOTE, RTNIL, and RTT. (Although there is an RTNIL return code, if you are returning only a nil list, you can call acedRetNil()). It can contain result types of RTLONG if the list is being returned to another ObjectARX application.

Use of the list-construction type codes is simple. In the acutBuildList() call, a nested list is preceded by the result type code RTLB (for List Begin) and is followed by the result type code RTLE (for List End). A dotted pair can also be constructed. Dotted pairs also begin with RTLB and end with RTLE; the dot is indicated by the result type code RTDOTE, and appears between the two members of the pair.

Note: This is a change from earlier versions. Applications that receive a dotted pair from AutoLISP no longer have to modify the format of the dotted pair before returning it with acedRetList(). (The earlier order, with RTDOTE at the end, is still supported.)

Danger: The acutBuildList() function does not check for a well-formed AutoLISP list. For example, if the RTLB and RTLE codes are not balanced, this error is not detected. If the list is not well formed, AutoLISP can fail. Omitting the RTLE code is guaranteed to be a fatal error.

The following sample code fragment constructs a nested list to return to AutoLISP:

res_list = acutBuildList(
    RTLB, // Begin sublist.  
    RTSHORT, 1, 
    RTSHORT, 2, 
    RTSHORT, 3, 
    RTLE, // End sublist.  
    RTSHORT, 4, 
    RTSHORT, 5, 
    0); 
if (res_list == NULL) { 
    acdbFail("Couldn't create list\n"); 
    return BAD; 
} 
acedRetList(res_list); 
acutRelRb(res_list); 

The list that this example returns to AutoLISP has the following form:

((1 2 3) 4 5)

The following code fragment constructs a dotted pair to return to AutoLISP:

res_list = acutBuildList(
    RTLB, // Begin dotted pair.  
    RTSTR, "Sample", 
    RTDOTE,
    RTSTR, "Strings", 
    RTLE, // End dotted pair.  
    0); 
if (res_list == NULL) { 
    acdbFail("Couldn't create list\n"); 
    return BAD; 
} 
acedRetList(res_list); 
acutRelRb(res_list); 

The list that this example returns to AutoLISP has the following form:

((“Sample” . “Strings”))

Note: In AutoLISP, dotted pairs associate DXF group codes and values. In an ObjectARX application this is unnecessary, because a single result buffer contains both the group code (in its restype field) and the value (in its resval field). While ObjectARX provides the list-construction type codes as a convenience, most ObjectARX applications do not require them.