cfx_kmSuite: cfx_kmList Documentation

cfx_kmList contains alternative versions of the LIST functions provided natively in ColdFusion. These functions differ from the CF versions in the following ways:

Empty list entries are recognized and treated as legitimate items. In ColdFusion, empty list entries are ignored, which can cause difficulties in list numbering and processing logic.
List entries may be quoted using single or double quotes. Quoted items may contain list delimiters. Functions that return single list items return the value without the quotes. ColdFusion makes no allowance for quoted list items.
Line terminators (CR/LF, etc.) are automatically recognized and treated as delimiters. ColdFusion makes no special allowance for line terminators, although they can be partially handled by adding the characters to the DELIMITERS list.

Help ListAppend ListBestMatch ListDeleteAt ListFind ListFirst	ListGetAt ListInsertAt ListIntersection ListKillDups ListLast ListLen	ListPrepend ListSetAt ListSort ListUnion Version

Appendix D: The List DELIMITERS Attribute

F=ListAppend

Description

Alternative to the CF ListAppend function.

Returns

The list with the item appended.

Syntax

  <cfx_kmList  F=ListAppend  V=variable  SHOW
      LIST=list-string
      VALUE=value-string
      DELIMITERS=string >

Attribute	Description	Required?
LIST	A string list.	YES
VALUE	A value to be appended to the list.	YES
DELIMITERS	Optional set of list delimiters. Default is a comma. For more information about delimiters, refer to Appendix D: The List DELIMITERS Attribute.	no
TRIM	If the TRIM attribute is present, the output value is automatically trimmed.	YES

F=ListBestMatch

Description

Look for the best matching item in a list. The list is searched using a "similiarity" algorithm. The item most similar to the supplied value is returned. For more information, refer to the Similarity function in <cfx_kmMisc>

Returns

Returns the list item best matching the specified value.

The following variables are also set:

kmMatchIndex - Index of the matching value within the list.
kmMatchSimilarity - Similarity (0-100) of the value and the matching list item.
If the supplied value has nothing in common with any of the list items,
a match will not be found. In that case, the return value is empty and the variables kmMatchIndex and kmMatchSimilarity are set to zero.

In almost all cases, a match will be found. However, it is up to you to determine whether the match is "good enough". If the value of kmMatchSimilarity is too low, you may wish to reject the match.

Syntax

  <cfx_kmList  F=ListBestMatch  V=variable  SHOW
      LIST=list-string
      VALUE=string
      NOCASE
      DELIMITERS=string >

Attribute	Description	Required?
LIST	A string list.	YES
VALUE	Item to find in the list.	YES
NOCASE	If this attribute is present, the list search is case insensitive.	no
DELIMITERS	Optional set of list delimiters. Default is a comma. For more information about delimiters, refer to Appendix D: The List DELIMITERS Attribute.	no

F=ListDeleteAt

Description

Alternative to the CF ListDeleteAt function.

Returns

The list with the specified item deleted.

Syntax

  <cfx_kmList  F=ListDeleteAt  V=variable  SHOW
      LIST=list-string
      POSITION=pos-number
      DELIMITERS=string >

Attribute	Description	Required?
LIST	A string list.	YES
POSITION	Number of the item to delete. First item = 1.	YES
DELIMITERS	Optional set of list delimiters. Default is a comma. For more information about delimiters, refer to Appendix D: The List DELIMITERS Attribute.	no

F=ListFind

Description

Alternative to the CF ListFind function.

Returns

Returns the index of the first occurrence of the value within the list.
Returns 0 if no value is found.

Syntax

  <cfx_kmList  F=ListFind  V=variable  SHOW
      LIST=list-string
      VALUE=string
      NOCASE
      DELIMITERS=string >

Attribute	Description	Required?
LIST	A string list.	YES
VALUE	Item to find in the list.	YES
NOCASE	If this attribute is present, the list search is case insensitive.	no
DELIMITERS	Optional set of list delimiters. Default is a comma. For more information about delimiters, refer to Appendix D: The List DELIMITERS Attribute.	no

F=ListFirst

Description

Alternative to the CF ListFirst function.

Returns

The first item in the list.

Syntax

  <cfx_kmList  F=ListFirst  V=variable  SHOW
      LIST=list-string
      DELIMITERS=string
      TRIM >

Attribute	Description	Required?
LIST	A string list.	YES
DELIMITERS	Optional set of list delimiters. Default is a comma. For more information about delimiters, refer to Appendix D: The List DELIMITERS Attribute.	no
TRIM	If the TRIM attribute is present, the output value is automatically trimmed.	YES

F=ListGetAt

Description

Alternative to the CF ListGetAt function.

Returns

The specified list item.

Syntax

  <cfx_kmList  F=ListGetAt  V=variable  SHOW
      LIST=list-string
      POSITION=pos-number
      DELIMITERS=string
      TRIM >

Attribute	Description	Required?
LIST	A string list.	YES
POSITION	List item number. First item = 1.	YES
DELIMITERS	Optional set of list delimiters. Default is a comma. For more information about delimiters, refer to Appendix D: The List DELIMITERS Attribute.	no
TRIM	If the TRIM attribute is present, the output value is automatically trimmed.	YES

F=ListInsertAt

Description

Alternative to the CF ListInsertAt function.

Returns

The list with the specified item inserted.

Syntax

  <cfx_kmList  F=ListInsertAt  V=variable  SHOW
      LIST=list-string
      VALUE=list-item
      POSITION=pos-number
      DELIMITERS=string >

Attribute	Description	Required?
LIST	A string list.	YES
VALUE	The list item to insert.	YES
POSITION	Position to insert the new item. First position = 1.	YES
DELIMITERS	Optional set of list delimiters. Default is a comma. For more information about delimiters, refer to Appendix D: The List DELIMITERS Attribute.	no

F=ListIntersection

Description

Given two lists, return a third list containing items which were found in BOTH supplied lists.

Returns

A list representing the intersection of two supplied lists.

Syntax

  <cfx_kmList  F=ListIntersection  V=variable  SHOW
      LIST1=list-string
      LIST2=list-string
      NOCASE
      DELIMITERS=string >

Attribute	Description	Required?
LIST1	String list one.	YES
LIST2	String list two.	YES
NOCASE	Option to use case-insensitive list item comparisions.	no
DELIMITERS	Optional set of list delimiters. Default is a comma. For more information about delimiters, refer to Appendix D: The List DELIMITERS Attribute.	no

F=ListKillDups

Description

Remove duplicate items from a list.

Returns

The list with the duplicate items removed.

Syntax

  <cfx_kmList  F=ListKillDups  V=variable  SHOW
      LIST=list-string
      NOCASE
      DELIMITERS=string >

Attribute	Description	Required?
LIST	String list.	YES
NOCASE	Option to use case-insensitive list item comparisions.	no
DELIMITERS	Optional set of list delimiters. Default is a comma. For more information about delimiters, refer to Appendix D: The List DELIMITERS Attribute.	no

F=ListLast

Description

Alternative to the CF ListLast function.

Returns

The last item in the list.

Syntax

  <cfx_kmList  F=ListLast  V=variable  SHOW
      LIST=list-string
      DELIMITERS=string
      TRIM >

Attribute	Description	Required?
LIST	A string list.	YES
DELIMITERS	Optional set of list delimiters. Default is a comma. For more information about delimiters, refer to Appendix D: The List DELIMITERS Attribute.	no
TRIM	If the TRIM attribute is present, the output value is automatically trimmed.	YES

F=ListLen

Description

Alternative to the CF ListLen function.

Returns

The length of the list.

Syntax

  <cfx_kmList  F=ListLen  V=variable  SHOW
      LIST=list-string
      DELIMITERS=string

Attribute	Description	Required?
LIST	A string list.	YES
DELIMITERS	Optional set of list delimiters. Default is a comma. For more information about delimiters, refer to Appendix D: The List DELIMITERS Attribute.	no

F=ListPrepend

Description

Alternative to the CF ListPrepend function.

Returns

The list with the item prepended.

Syntax

  <cfx_kmList  F=ListAppend  V=variable  SHOW
      LIST=list-string
      VALUE=value-string
      DELIMITERS=string >

Attribute	Description	Required?
LIST	A string list.	YES
VALUE	A value to be prepended (added to the front of) to the list.	YES
DELIMITERS	Optional set of list delimiters. Default is a comma. For more information about delimiters, refer to Appendix D: The List DELIMITERS Attribute.	no
TRIM	If the TRIM attribute is present, the output value is automatically trimmed.	YES

F=ListSetAt

Description

Alternative to the CF ListSetAt function.

Returns

The list with the specified item replaced.

Syntax

  <cfx_kmList  F=ListSetAt  V=variable  SHOW
      LIST=list-string
      VALUE=list-item
      POSITION=pos-number
      DELIMITERS=string >

Attribute	Description	Required?
LIST	A string list.	YES
VALUE	The new list item to set in place of the current item.	YES
POSITION	Position to set the new item. First position = 1.	YES
DELIMITERS	Optional set of list delimiters. Default is a comma. For more information about delimiters, refer to Appendix D: The List DELIMITERS Attribute.	no

F=ListSort

Description

Alternative to the CF ListSort function.

Returns

A sorted list.

Syntax

  <cfx_kmList  F=ListSort  V=variable  SHOW
      LIST=list-string
      DELIMITERS=string

Attribute	Description	Required?
LIST	A string list.	YES
DELIMITERS	Optional set of list delimiters. Default is a comma. For more information about delimiters, refer to Appendix D: The List DELIMITERS Attribute.	no

F=ListUnion

Description

Combine two lists, eliminating duplicate items.

Returns

The combined list.

Syntax

  <cfx_kmList  F=ListUnion  V=variable  SHOW
      LIST1=list-string
      LIST2=list-string
      NOCASE
      DELIMITERS=string >

Attribute	Description	Required?
LIST1	String list one.	YES
LIST2	String list two.	YES
NOCASE	Option to use case-insensitive list item comparisions.	no
DELIMITERS	Optional set of list delimiters. Default is a comma. For more information about delimiters, refer to Appendix D: The List DELIMITERS Attribute.	no