String Lists


Functions

void TecUtilStringListClear (StringList_pa StringList)
  Remove all members of the string list.
void TecUtilStringListRemoveStrings (StringList_pa StringList, LgIndex_t StringNumber, LgIndex_t Count)
  Remove the specified number of strings beginning at the nth string.
void TecUtilStringListRemoveString (StringList_pa StringList, LgIndex_t StringNumber)
  Remove the nth string from the string list.
void TecUtilStringListDealloc (StringList_pa *StringList)
  Deallocate the string list members and handle, and set the handle to NULL.
StringList_pa TecUtilStringListAlloc (void)
  Create an empty string list.
Boolean_t TecUtilStringListAppendString (StringList_pa StringList, const char *String)
  Append a copy of the string to the string list.
LgIndex_t TecUtilStringListGetCount (StringList_pa StringList)
  Count the number of strings currently maintained by the string list.
const char * TecUtilStringListGetRawStringPtr (StringList_pa StringList, LgIndex_t StringNumber)
  Return a reference to the nth string in a string list.
char * TecUtilStringListGetString (StringList_pa StringList, LgIndex_t StringNumber)
  Return a copy of the nth string from a string list.
Boolean_t TecUtilStringListSetString (StringList_pa StringList, LgIndex_t StringNumber, const char *String)
  Place a copy of the specified string at the nth position in the string list.
Boolean_t TecUtilStringListInsertString (StringList_pa StringList, LgIndex_t StringNumber, const char *String)
  Insert a copy of the string into the nth position of the string list.
StringList_pa TecUtilStringListCopy (StringList_pa StringList)
  Return a handle to a duplicate of the specified string list and its contents.
Boolean_t TecUtilStringListAppend (StringList_pa Target, StringList_pa Source)
  Append a copy of the contents of the source string list to the target string list.
char * TecUtilStringListToNLString (StringList_pa StringList)
  Return a newline delimited string representation of the string list.
StringList_pa TecUtilStringListFromNLString (const char *String)
  Create a string list from a newline delimited string.
void TecUtilStringListSort (StringList_pa StringList, StringListStringComparator_pf Comparator, ArbParam_t ClientData)
  Sorts the string list by repeatedly calling the 'Comparator' function until the list is in order.

Function Documentation

StringList_pa TecUtilStringListAlloc ( void   ) 

Create an empty string list.

See the Chapter "Using String Lists," in the ADK User's Manual for a discussion of string lists. Use TecUtilStringListDealloc() to deallocate the string list when it is no longer needed. This function is Thread Safe.

Returns:
Handle to an empty string list. A handle of NULL is returned if sufficient memory is not available.
Fortran Syntax:
    SUBROUTINE TecUtilStringListAlloc(ResultPtr)
    POINTER (ResultPtr, Result)

Python Syntax:

    This function is not supported in Python.

Allocate and deallocate a string list.

   StringList_pa Names = NULL;

   Names = TecUtilStringListAlloc();
   if (Names != NULL)
     {
       // do something with the name list, append, clear, etc
         .
         .
         .

       // get rid of the name list
       TecUtilStringListDealloc(&Names);
     }

Boolean_t TecUtilStringListAppend ( StringList_pa  Target,
StringList_pa  Source 
)

Append a copy of the contents of the source string list to the target string list.

See the Chapter "Using String Lists," in the ADK User's Manual for a discussion of string lists. This function is Thread Safe.

Parameters:
Target String list to which the Source string list is appended. Use TecUtilStringListAlloc() to allocate a string list
Source String list to append to the Target. Use TecUtilStringListAlloc() to allocate a string list.
Returns:
A return value of TRUE indicates the operation was successful. A return value of FALSE indicates that sufficient memory was not available for the request.
Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilStringListAppend(
   &                   TargetPtr,
   &                   SourcePtr)
    POINTER         (TargetPtr, Target)
    POINTER         (SourcePtr, Source)

Python Syntax:

    This function is not supported in Python.

Append one string list to another.

   Boolean_t     IsOk = FALSE;
   StringList_pa Names = NULL;
   StringList_pa DefaultNames = NULL;

   // call some function to get a names list from the user
   Names = MyFuncForGettingNamesFromUser();

   // call some function to get some default name list
   DefaultNames = MyFuncForGettingDefaultNames();

   // combine the two name lists into one
   if (Names != NULL && DefaultNames != NULL)
     {
       IsOk = TecUtilStringListAppend(Names, DefaultNames);
       if (IsOk)
         {
           // do more processing
             .
             .
             .

           // get rid of the name lists
           TecUtilStringListDealloc(&Names);
           TecUtilStringListDealloc(&DefaultNames);
         }
     }

Boolean_t TecUtilStringListAppendString ( StringList_pa  StringList,
const char *  String 
)

Append a copy of the string to the string list.

The string list expands to accommodate the additional item. See the Chapter "Using String Lists," in the ADK User's Manual for a discussion of string lists. This function is Thread Safe.

Parameters:
StringList Handle to a valid string list. Use TecUtilStringListAlloc() to allocate a string list.
String A copy of String is appended to the string list. String may be NULL
Returns:
A return value of TRUE indicates the operation was successful. A return value of FALSE indicates that sufficient memory was not available for the additional item.
Precondition:
String Pointer must be a valid address or NULL.
Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilStringListAppendString(
   &                   StringListPtr,
   &                   String)
    POINTER         (StringListPtr, StringList)
    CHARACTER*(*)   String

Python Syntax:

    This function is not supported in Python.

Append two variable names to a string list

   Boolean_t     IsOk = FALSE;
   StringList_pa Names = NULL;

   Names = TecUtilStringListAlloc();
   if (Names != NULL)
     {
       IsOk = TecUtilStringListAppendString(Names, "X");
       IsOk = TecUtilStringListAppendString(Names, "Y");
       if (IsOk)
         {
           // do some processing with the name list
             .
             .
             .
         }

       // get rid of the name list
       TecUtilStringListDealloc(&Names);
     }

void TecUtilStringListClear ( StringList_pa  StringList  ) 

Remove all members of the string list.

See the Chapter "Using String Lists," in the ADK User's Manual for a discussion of string lists. This function is Thread Safe.

Parameters:
StringList Handle to a valid string list. Use TecUtilStringListAlloc() to allocate a string list
Fortran Syntax:
    SUBROUTINE TecUtilStringListClear(StringListPtr)
    POINTER (StringListPtr, StringList)

Python Syntax:

    This function is not supported in Python.

Clear a string list so that it no longer maintains any strings items.

   Boolean_t     ClearNames = FALSE;
   StringList_pa Names = NULL;

   // do some processing to get names
     .
     .
     .

   if (ClearNames)
     {
       TecUtilStringListClear(Names);
       TecUtilDialogMessageBox("All names cleared.",
                               MessageBoxType_Information);
     }

StringList_pa TecUtilStringListCopy ( StringList_pa  StringList  ) 

Return a handle to a duplicate of the specified string list and its contents.

See the Chapter "Using String Lists," in the ADK User's Manual for a discussion of string lists. This function is Thread Safe.

Note:
The caller is responsible for deallocating the string list when it is no longer needed.
Parameters:
StringList Handle to a valid string list. Use TecUtilStringListAlloc() to create a string list.
Returns:
A handle to a duplicate string list is returned if the operation was successful. A handle of NULL is returned if sufficient memory is not available.
Fortran Syntax:
    SUBROUTINE TecUtilStringListCopy(
   &           StringListPtr,
   &           ResultPtr)
    POINTER         (StringListPtr, StringList)
    POINTER         (ResultPtr, Result)

Python Syntax:

    This function is not supported in Python.

Make a copy of a string list.

   StringList_pa Names = NULL;
   StringList_pa CopyOfNames = NULL;

   // do some processing to get names
     .
     .
     .

   CopyOfNames = TecUtilStringListCopy(Names);
   if (CopyOfNames != NULL)
     {
       // do some processing on the name list copy
         .
         .
         .

       // get rid of the name list copy
       TecUtilStringListDealloc(&CopyOfNames);
     }

void TecUtilStringListDealloc ( StringList_pa *  StringList  ) 

Deallocate the string list members and handle, and set the handle to NULL.

See the Chapter "Using String Lists," in the ADK User's Manual for a discussion of string lists. This function is Thread Safe.

Parameters:
StringList Reference to a valid string list handle. Use TecUtilStringListAlloc() to create a string list
Precondition:
StringList Pointer must be a valid address and non-NULL.

StringList Pointer must be a valid address or NULL.

Fortran Syntax:
    SUBROUTINE TecUtilStringListDealloc(StringListPtr)
    POINTER (StringListPtr, StringList)

Python Syntax:

    This function is not supported in Python.

Create and then deallocate a string list:

   StringList_pa MyStrList = TecUtilStringListAlloc();
   .
   .
   .
   TecUtilStringListDealloc(&MyStrList);

StringList_pa TecUtilStringListFromNLString ( const char *  String  ) 

Create a string list from a newline delimited string.

A newline delimited string is a character string with newlines (\n) used to separate one substring from the next. See the Chapter "Using String Lists," in the ADK User's Manual for a discussion of string lists. This function is Thread Safe.

Note:
The caller is responsible for deallocating the string list when it is no longer needed.
Parameters:
String The newline delimited string
Returns:
Handle to the created string list. A handle of NULL is returned if sufficient memory is not available.
Precondition:
String Pointer must be a valid address and non-NULL.
Fortran Syntax:
    SUBROUTINE TecUtilStringListFromNLString(
   &           String,
   &           ResultPtr)
    CHARACTER*(*)   String
    POINTER         (ResultPtr, Result)

Python Syntax:

    This function is not supported in Python.

Given the string, Hello\n\nWorld, the function will return a string list containing 3 members: "Hello, "" (that is, an empty string), and "World."

   StringList_pa List = NULL;

   List = TecUtilStringListFromNLString("Hello\\n\\nWorld");
   if (List != NULL)
     {
       LgIndex_t I = 0;
       LgIndex_t Count = 0;

       // print each element of the string list
       for (I = 0, Count = TecUtilStringListGetCount(List);
             I < Count;
             I++)
         {
           String = TecUtilStringListGetString(List, I+1);
           if (String != NULL)
             {
               printf("Item #%d: %s\n", I+1, String);
               TecUtilStringDealloc(&String);
             }
         }

       // get rid of the list
       TecUtilStringListDealloc(&List);
     }

LgIndex_t TecUtilStringListGetCount ( StringList_pa  StringList  ) 

Count the number of strings currently maintained by the string list.

See the Chapter "Using String Lists," in the ADK User's Manual for a discussion of string lists. This function is Thread Safe.

Parameters:
StringList Handle to a valid string list. Use TecUtilStringListAlloc() to create a string list.
Returns:
The number of strings maintained by the string list.
Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilStringListGetCount(StringListPtr)
    POINTER (StringListPtr, StringList)

Python Syntax:

    This function is not supported in Python.

Get each instruction used to load the current frame's data set:

   StringList_pa LoaderInstructs;
   char *LoaderName = NULL;
   if (TecUtilImportGetLoaderInstr(&LoaderName,&LoaderInstructs))
     {
      LgIndex_t ii, Count =
        TecUtilStringListGetCount(LoaderInstructs);
      for (ii = 1; ii <= Count; ii++)
       {
        char *Instruct =
          TecUtilStringListGetString(LoaderInstructs, ii);
        // Do some processing
        .
        .
        .
        TecUtilStringDealloc(&Instruct);
       }
     }

const char* TecUtilStringListGetRawStringPtr ( StringList_pa  StringList,
LgIndex_t  StringNumber 
)

Return a reference to the nth string in a string list.

See the Chapter "Using String Lists", in the ADK User's Manual for a discussion of string lists. This function is Thread Safe.

Parameters:
StringList Handle to a valid string list. Use TecUtilStringListAlloc() to allocate a string list
StringNumber Position of string to be copied into the string list. StringNumber must be greater than or equal to one, and less than or equal to the number of items maintained by the string list. Use TecUtilStringListGetCount() to get the number of items.
Returns:
Returns a REFERENCE to the string. DO OT DEALLOCATE THIS REFERENCE.
Python Syntax:
    This function is not supported in Python.

Operate on the set of files retrieved using TecUtilDialogGetFileNames(). 

   StringList_pa FileNames = NULL;

   if (TecUtilDialogGetFileNames(SelectFileOption_ReadMultiFile,
                                 &FileNames,
                                 "any file",
                                 (StringList_pa)NULL,
                                 "*"))
     {
       LgIndex_t N,NumFiles;

       NumFiles = TecUtilStringListGetCount(FileNames);
       for (N = 1; N < Numfiles; N++)
         {
           const char *RawFNamePtr = TecUtilStringListGetRawStringPtr(FileNames,N);

           //
           // Do something with RawFNamePtr.  DO NOT DEALLOCATE RawFNamePtr.
           //
         }

       //
       // We do however dealloc the stringlist itself.
       //

       TecUtilStringListDealloc(&FileNames);
     }

char* TecUtilStringListGetString ( StringList_pa  StringList,
LgIndex_t  StringNumber 
)

Return a copy of the nth string from a string list.

See the Chapter "Using String Lists," in the ADK User's Manual for a discussion of string lists. This function is Thread Safe.

Note:
The caller is responsible for de-allocating the copy of the string when it is no longer needed.
Parameters:
StringList Handle to a valid string list. Use TecUtilStringListAlloc() to allocate a string list
StringNumber Position of string to be copied into the string list. StringNumber must be greater than or equal to one, and less than or equal to the number of items maintained by the string list. Use TecUtilStringListGetCount() to get the number of items
Returns:
Copy of the nth string.
Fortran Syntax:
    SUBROUTINE TecUtilStringListGetString(
   &           StringListPtr,
   &           StringNumber,
   &           Result,
   &           ResultLength)
    POINTER         (StringListPtr, StringList)
    INTEGER*4       StringNumber
    CHARACTER*(*)   Result
    INTEGER*4       ResultLength

Python Syntax:

    This function is not supported in Python.

Boolean_t TecUtilStringListInsertString ( StringList_pa  StringList,
LgIndex_t  StringNumber,
const char *  String 
)

Insert a copy of the string into the nth position of the string list.

The string list expands and the items are shifted to accommodate the additional item. See the Chapter "Using String Lists," in the ADK User's Manual for a discussion of string lists. This function is Thread Safe.

Parameters:
StringList Handle to a valid string list. Use TecUtilStringListAlloc() to allocate a string list
StringNumber Position where string is inserted in the string list. This value must be greater than or equal to one, and less than or equal to the number of items maintained by the string list. Use TecUtilStringListGetCount() to get the number of items
String A copy of String is inserted into the string list. String may be NULL
Returns:
A return value of TRUE indicates the operation was successful. FALSE indicates that the memory available was not sufficient for the additional item.
Precondition:
String Pointer must be a valid address or NULL.
Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilStringListInsertString(
   &                   StringListPtr,
   &                   StringNumber,
   &                   String)
    POINTER         (StringListPtr, StringList)
    INTEGER*4       StringNumber
    CHARACTER*(*)   String

Python Syntax:

    This function is not supported in Python.

Insert a string at the beginning and end of an existing list.

   Boolean_t     IsOk = FALSE;
   StringList_pa Names = NULL;
   LgIndex_t     Count = 0;

   // do some processing to get names
     .
     .
     .

   // insert a name at the beginning and end of the list
   IsOk = TecUtilStringListInsertString(Names, 1,
                                        "Very First Name");
   Count = TecUtilStringListGetCount(Names);
   IsOk = TecUtilStringListInsertString(Names, Count+1,
                                        "Very Last Name");

void TecUtilStringListRemoveString ( StringList_pa  StringList,
LgIndex_t  StringNumber 
)

Remove the nth string from the string list.

The members following the removed item are shifted to fill the vacated space. See the Chapter "Using String Lists," in the ADK User's Manual for a discussion of string lists. This function is Thread Safe.

Parameters:
StringList Handle to a valid string list. Use TecUtilStringListAlloc() to allocate a string list.
StringNumber Number of the string to remove. Must be greater than or equal to one, and less than or equal to the number of items maintained by the string list. Use TecUtilStringListGetCount() to get the number of items
Fortran Syntax:
    SUBROUTINE TecUtilStringListRemoveString(
   &           StringListPtr,
   &           StringNumber)
    POINTER         (StringListPtr, StringList)
    INTEGER*4       StringNumber

Python Syntax:

    This function is not supported in Python.

Remove the first name from a name list.

   StringList_pa Names = NULL;

   // do some processing to get names
     .
     .
     .

   TecUtilStringListRemoveString(Names, 1);

void TecUtilStringListRemoveStrings ( StringList_pa  StringList,
LgIndex_t  StringNumber,
LgIndex_t  Count 
)

Remove the specified number of strings beginning at the nth string.

The members following the items removed are shifted to fill the vacated space. See the Chapter "Using String Lists," in the ADK User's Manual for a discussion of string lists. This function is Thread Safe.

Parameters:
StringList Handle to a valid string list. Use TecUtilStringListAlloc() to allocate a string list
StringNumber Start position in the string list. Value must be greater than or equal to one, and less than or equal to the number of items maintained by the string list. Use TecUtilStringListGetCount() to get the number of strings in the string list
Count Number of items to remove from the string list. Value must be greater than or equal to one, and less than or equal to the number of items remaining, including the string at the start position. Use TecUtilStringListGetCount() to get the number of strings in the string list
Fortran Syntax:
    SUBROUTINE TecUtilStringListRemoveStrings(
   &           StringListPtr,
   &           StringNumber,
   &           Count)
    POINTER         (StringListPtr, StringList)
    INTEGER*4       StringNumber
    INTEGER*4       Count

Python Syntax:

    This function is not supported in Python.

Remove all but the first and last item from a name list.

   LgIndex_t     Count = 0;
   StringList_pa Names = NULL;

   // do some processing to get names
     .
     .
     .

   Count = TecUtilStringListGetCount(Names);
   TecUtilStringListRemoveStrings(Names, 2, Count-2);

Boolean_t TecUtilStringListSetString ( StringList_pa  StringList,
LgIndex_t  StringNumber,
const char *  String 
)

Place a copy of the specified string at the nth position in the string list.

If the position is beyond the end of the string list, the string list is resized, so that the string references between the last item of the string list in its original state and the last item of the string list in its new state are assigned NULL. If the position is within the boundaries of the original string list, the string at the specified position is replaced by the new value. See the Chapter "Using String Lists," in the ADK User's Manual for a discussion of string lists. This function is Thread Safe.

Parameters:
StringList Handle to a valid string list. Use TecUtilStringListAlloc() to allocate a string list
StringNumber Item position in the string list. Value must be greater than or equal to one
String A copy of String is appended to the string list. String may be NULL
Returns:
A return value of TRUE indicates the operation was successful. FALSE indicates that sufficient memory was not available for the additional item at the specified position.
Precondition:
String Pointer must be a valid address or NULL.
Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilStringListSetString(
   &                   StringListPtr,
   &                   StringNumber,
   &                   String)
    POINTER         (StringListPtr, StringList)
    INTEGER*4       StringNumber
    CHARACTER*(*)   String

Python Syntax:

    This function is not supported in Python.

Replace the first item of a name list with a new value and put a new item ten positions past the current last item.

   LgIndex_t     Count = 0;
   StringList_pa Names = NULL;

   // do some processing to get names
     .
     .
     .

   IsOk = TecUtilStringListSetString(Names, 1,
                                     "New First Name");
   Count = TecUtilStringListGetCount(Names);
   IsOk = TecUtilStringListSetString(Names, Count+10,
                                     "New Last Name");

void TecUtilStringListSort ( StringList_pa  StringList,
StringListStringComparator_pf  Comparator,
ArbParam_t  ClientData 
)

Sorts the string list by repeatedly calling the 'Comparator' function until the list is in order.

Since:
10.0-3-129
Parameters:
StringList String list to sort.
Comparator Function called to compare two string list strings or NULL for the default sort. The default sorting handles NULL elements and uses the system's strcmp utility for comparing valid strings elements.
ClientData Contextual information that is passed along to the comparator function. Client data isn't used by the default comparator and can be passed any value. For specialized comparator functions the client data is used to hold contextual information so that global variable do not have to be used.
Fortran Syntax:
    SUBROUTINE TecUtilStringListSort(
   &           StringListPtr,
   &           ComparatorPtr,
   &           ClientDataPtr)
    POINTER         (StringListPtr, StringList)
    POINTER         (ComparatorPtr, Comparator)
    POINTER         (ClientDataPtr, ClientData)

Python Syntax:

    This function is not supported in Python.

Sort the variable string list using Tecplot's default comparator: 

   TecUtilStringListSort(MyVarList, NULL, 0);

Sort the variable string list using own own comparator function. We pass some client data to our own comparator function simply to show how to use it. In this case all the client data is used for is to keep track of the number of times our comparator function was called... not very useful. 

   static int MyStrComparator(const char *String1,
                                      const char *String2,
                                      ArbParam_t  ClientData)
   {
     int Result = 0;
     LgIndex_t *NumTimesCalled;

     REQUIRE(VALID_REF(String1) || String1 == NULL);
     REQUIRE(VALID_REF(String2) || String2 == NULL);

     NumTimesCalled = (LgIndex_t *)ClientData;
     (*NumTimesCalled) += 1;

     if (String1 != NULL && String2 != NULL)
       Result = strcmp(String1, String2);
     else if (String1 == NULL && String2 == NULL)
       Result = 0;
     else if (String1 == NULL)
       Result = -1;
     else if (String2 == NULL)
       Result = 1;
     else
       CHECK(FALSE);

     return Result;
   }

 ...

   // After calling TecUtilStringListSort NumTimesCalled will contain the
   // number of times that our comparator was called.
   LgIndex_t NumTimesCalled = 0;
   TecUtilStringListSort(MyVarList, MyStrComparator, &NumTimesCalled);

char* TecUtilStringListToNLString ( StringList_pa  StringList  ) 

Return a newline delimited string representation of the string list.

A newline delimited string is a character string with newlines (\n) used to separate one substring from the next. See the chapter on "Using String Lists" in the ADK User's Manual for a discussion of string lists. This function is Thread Safe.

Note:
The caller is responsible for de-allocating the copy of the newline delimited string when it is no longer needed.
Parameters:
StringList Handle to a valid string list. Use TecUtilStringListAlloc() to allocate a string list.
Returns:
A newline, (\n), delimited string representation of the string list.
Fortran Syntax:
    SUBROUTINE TecUtilStringListToNLString(
   &           StringListPtr,
   &           Result,
   &           ResultLength)
    POINTER         (StringListPtr, StringList)
    CHARACTER*(*)   Result
    INTEGER*4       ResultLength

Python Syntax:

    This function is not supported in Python.

Given a string list containing 3 members: "Hello", "", and "World", the function will return the following string: "Hello\\n\\nWorld".

   StringList_pa List = NULL;

   List = TecUtilStringListAlloc();
   if (List != NULL)
     {
       // add items to the string list
       TecUtilStringListAppendString(List, "Hello");
       TecUtilStringListAppendString(List, "");
       TecUtilStringListAppendString(List, "World");

       //print the newline separated string representation
       String = TecUtilStringListToNLString(List);
       if (String != NULL)
         {
           printf("%s\n", String);
           TecUtilStringDealloc(&String);
         }

       // get rid of the list
       TecUtilStringListDealloc(&List);
     }

Generated on Tue Mar 12 02:24:43 2013 for Tecplot by  doxygen 1.5.5