jList

v1.6.0

What does it do?

jList is a collection of functions that bring ColdFusion-style list handling to Javascript.
A list is simply a string. What makes this string different (from any other string) is that it contains "delimiters". Delimiters (sometimes referred to as "separators") are used to separate each item in the list.
For instance, the string "carrots,peas,lettuce,tomato" could be described as a "comma delimited" or "comma separated" list. Although commas are the most common delimiter for lists, any character can be used - "Monkey:Rabbit:Mouse:Elephant" is no less a list than the comma delimited list. Once you start to use jList you will quickly realise that there are many situations where treating a string as a list is a simpler and more intuitive way to manipulate data than the built-in alternatives offered by Javascript.

What's included?

There are 12 files included with this package. The first, and most important, four are:

• readme.md
  This file.

• jlist-examples.htm
  Examples of each of the functions in action.

• jlist.js
  The Javascript source code of the library.

• jlist-min.js
  The Javascript source code minified using UglifyJS.

The next seven files are part of a comprehensive Jasmine test suite that allows modifications to the library to be quickly and easily regression tested. They are:

• test.htm
  Open this file in a browser to run the Jasmine test suite against the regular version of the library, jlist.js. This file can also be run in a browser here https://rawgithub.com/davidwaterston/jList/master/test/test.htm.

• test minimised version.htm
  Open this file in a browser to run the Jasmine test suite against the minified version of the library, jlist-min.js. This file can also be run in a browser here https://rawgithub.com/davidwaterston/jList/master/test/test%20minimised%20version.htm.

• jlist-spec.js
  The test suite specifications - these are the actual tests that are run by opening either of the preceding two files.

• jasmine-html.js, jasmine.css, jasmine,js and MIT.LICENSE
  These are the files required by Jasmine. They were not written by me and are subject to a separate licence.

Finally, there is:

• codekit-config.json
  A configuration file for the project for users of CodeKit on the Mac. If you don't use CodeKit (and you're probably wasting a lot of development time if you don't) then you can safely ignore this file. Otherwise, when adding the project to CodeKit it will pick up these settings automatically.

For this release there are 30 functions included. They are, in alphabetical order:

• listAppend
  Concatenates an element to a list.
  
• listChangeDelims
  Changes a list delimiter.
• listConcatenate
  Adds one list to the end of another.
• listContains
  Determines the index of the first list element that contains a specified substring.
  The search is case-sensitive.
• listContainsNoCase
  Determines the index of the first list element that contains a specified substring. The search is not case-sensitive.
• listDeleteAt
  Deletes an element from a list.
  
• listDifference
  Gets the elements that are unique to each of two different lists.
  
• listFind
  Determines the index of the first list element in which a specified value occurs. The search is case-sensitive.
  
• listFindNoCase
  Determines the index of the first list element in which a specified value occurs. The search is case-insensitive.
• listFirst
  Gets the first element of a list.
• listGetAt
  Gets a list element at a specified position.
• listInsertAt
  Inserts an element into a list.
• listIntersection
  Gets the elements that are common to two different lists.
• listLast
  Gets the last element of a list.
• listLen
  Determines the number of elements in a list.
• listPrepend
  Inserts an element at the beginning of a list.
• listQualify
  Inserts a string at the beginning and end of list elements.
• listRemove
  Removes elements in one list from another list. Matching is case-sensitive.
• listRemoveNoCase
  Removes elements in one list from another list. Matching is not case-sensitive.
• listRemoveDuplicates
  Removes duplicate elements from a list. Matching is case-sensitive.
• listRemoveDuplicatesNoCase
  Removes duplicate elements from a list. Matching is not case-sensitive.
• listReplace
  Replaces instances of one element in a list with another element. Matching is case-sensitive.
• listReplaceNoCase
  Replaces instances of one element in a list with another element. Matching is not case-sensitive.
• listRest
  Gets a list, without its first element.
• listReverse
  Reverses the order of elements in a list.
• listSetAt
  Replaces the contents of a list element.
• listSort
  Sorts list elements according to a sort type and sort order.
• listUnion
  Combines the elements from two different lists.
• listValueCount
  Counts the instances of a specified value in a list. The search is case-sensitive.
  
• listValueCountNoCase
  Counts the instances of a specified value in a list. The search is not case-sensitive.
  

More detailed documentation for each of these functions can be found later in this document.

Quick start

jList requires only that you include the jlist.js or jlist-min.js file in your source:

<script src="jlist-min.js"></script>

Alternatively you may use a script loader such as LABjs or RequireJS or concatenate the file with one or more other Javascript files to improve loading times. It's recommended that you use the minified version (*jlist-min.js*) in production to reduce the loading time. The original, commented, pre-minification source is also included and you may find this more useful when debugging, making your own changes or just for learning.
Once the script is loaded then invoking the function you want is simply a matter of prefixing the function with "jList.". The following example, which uses the listAppend and listSort functions, shows how:

<script src="jlist-min.js"></script>
<script>
    var l, l2;
    l = "Susan,Janet,Steve,Bree,Michele,Jim,Mark,Elizabeth";
    l = jList.listAppend(l, "David");
    l2 = jList.listSort(l);
    alert(l2);
</script>

This will show an alert with the text "Bree,David,Elizabeth,Janet,Jim,Mark,Michele,Steve,Susan".

List processing is convenient for handling many strings that don't at first appear to be lists.
For example, the URL "http://www.mysite.net/main.htm?id=1234" can be considered to be a list or, more usefully, a series of lists. To extract the top-level domain (tld) part (in this case the "net") we could think of the URL as a "dot delimited" list, within a "forward-slash delimited" list.

1.  var url = "http://www.mysite.net/main.htm?id=1234";
2.  var url_part = jList.listGetAt(url,3,"/");  // returns 'www.mysite.net'
3.  var tld = jList.listLast(url_part,".");  // returns 'net' 

In line 2 we grab the 3rd item in the list, using a delimiter of "/". In this case this is "www.mysite.net" because the first item is "http:" and the second item is empty. This is an important difference between this library and ColdFusion list processing - empty elements are not ignored in these functions. Notice also that we start counting the items from 1, not from zero.
Once we have the third item stored in url_part (line 2) we can then treat this as a "dot delimited" list. Using the listLast function (line 3) to retrieve the rightmost item in the list but this time specifying "." as the delimiter will return "net" into the tld variable.

Browser compatibility

jList has been tested in the latest versions of:

• Chrome
• Firefox
• Safari
• Opera
• Internet Explorer

Licence

Copyright (c) 2012 David Waterston.

You may use this library under the terms of the MIT License, detailed below. More information can be found at http://www.opensource.org/licenses/mit-license.php.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

More

• jList is minified using UglifyJS.
• Version numbers follow the Semantic Versioning standard.
• The unminified version of the source validates clean in jsLint (Edition 2013-06-08).
• Written by David Waterston
• Forked by Chris Tsongas
• Github repository: http://davidwaterston.github.com/jList and https://github.com/tsongas/jList
• Planning and task management in Trello
• Developed using Sublime Text 2, CodeBox and CodeKit.
• Tested using Jasmine 1.2.0.
• Documentation written in Markdown using Byword.
• Pushed to GitHub using Tower.
• Made in Scotland and the United States of America.

Usage details

listAppend

Description
Concatenates an element to a list.

Availability
v1.0

Function syntax
listAppend(list, value [, delimiter ])

Returns
A copy of the list, with value appended.

Parameters

Usage

Inserts a delimiter character before value regardless of whether value is empty. The following table shows examples of listAppend processing:

jsFiddle

http://jsfiddle.net/davidwaterston/KDNUf

listChangeDelims

Description
Changes a list delimiter.

Availability
v1.3

Function syntax
listChangeDelims(list, new_delimiter [, delimiter ])

Returns
A copy of the list, with the delimiter character replaced by new_delimiter.

Parameters

Usage

The following table shows examples of listChangeDelims processing:

jsFiddle

http://jsfiddle.net/davidwaterston/uvvHF

listConcatenate

Description
Adds one list to the end of another.

Availability
v1.6

Function syntax
listConcatenate(list1, list2 [, delimiter ])

Returns
A new list, with list2 concatenated to list1.

Parameters

Usage

If both list1 and list2 are not empty, inserts a delimiter character between list1 and list2.
The following table shows examples of listConcatenate processing:

jsFiddle

http://jsfiddle.net/davidwaterston/K2y92/

listContains

Description
Determines the index of the first list element that contains a specified substring. The search is case-sensitive.

Availability
v1.5.0

Function syntax
listContains(list, substring [, delimiter ])

Returns
Index of the first list element that contains substring. If not found, returns zero.

Parameters

Usage

The following table shows examples of listContains processing:

jsFiddle

http://jsfiddle.net/davidwaterston/mjJ2n

listContainsNoCase

Description
Determines the index of the first list element that contains a specified substring. The search is not case-sensitive.

Availability
v1.5.0

Function syntax
listContainsNoCase(list, substring [, delimiter ])

Returns
Index of the first list element that contains substring. If not found, returns zero.

Parameters

Usage

The following table shows examples of listContainsNoCase processing:

jsFiddle

http://jsfiddle.net/davidwaterston/ku4rP

listDeleteAt

Description
Deletes an element from a list.

Availability
v1.0

Function syntax
listDeleteAt(list, position [, delimiter ])

Returns
A copy of the list, without the specified element.

Parameters

Usage

The following table shows examples of listDeleteAt processing:

jsFiddle

http://jsfiddle.net/davidwaterston/j6pEP

listDifference

Description
Gets the elements that are unique to each of two different lists.

Availability
v1.6

Function syntax
listDifference(list1, list2 [, delimiter ])

Returns
A new list containing elements that are either in list1 but not list2, or in list2 but not list1.

Parameters

Usage

The following table shows examples of listDifference processing:

jsFiddle

http://jsfiddle.net/davidwaterston/Zq6ay/

listFind

Description
Determines the index of the first list element in which a specified value occurs. The search is case-sensitive.

Availability
v1.0

Function syntax
listFind(list, value [, delimiter ])

Returns
The index of the first list element that contains value, with matching case. If not found, returns zero. The search is case-sensitive.

Parameters

Usage

The following table shows examples of listFind processing:

jsFiddle

http://jsfiddle.net/davidwaterston/LAfBn

listFindNoCase

Description
Determines the index of the first list element in which a specified value occurs. The search is case-insensitive.

Availability
v1.0

Function syntax
listFindNoCase(list, value [, delimiter ])

Returns
The index of the first list element that contains value, with matching case. If not found, returns zero. The search is case-insensitive.

Parameters

Usage

The following table shows examples of listFindNoCase processing:

jsFiddle

http://jsfiddle.net/davidwaterston/TXt2T

listFirst

Description
Gets the first element of a list.

Availability
v1.0

Function syntax
listFirst(list, [, delimiter ])

Returns
The first element of a list. If the list is empty, returns an empty string.

Parameters

Usage

The following table shows examples of listFirst processing:

jsFiddle

http://jsfiddle.net/davidwaterston/FEQWc

listGetAt

Description
Gets a list element at a specified position.

Availability
v1.0

Function syntax
listGetAt(list, position, [, delimiter ])

Returns
Value of the list element at position position.

Parameters

Usage

The following table shows examples of listGetAt processing:

jsFiddle

http://jsfiddle.net/davidwaterston/7khW6

listInsertAt

Description
Inserts an element into a list.

Availability
v1.0

Function syntax
listInsertAt(list, position, value, [, delimiter ])

Returns
A copy of the list, with value inserted at the specified position.

Parameters

Usage

The following table shows examples of listInsertAt processing:

jsFiddle

http://jsfiddle.net/davidwaterston/9D26p

listIntersection

Description
Gets the elements that are common to each of two different lists.

Availability
v1.6

Function syntax
listIntersection(list1, list2 [, delimiter ])

Returns
A new list only containing elements that are in both list1 and list2.

Parameters

Usage

The following table shows examples of listIntersection processing:

jsFiddle

http://jsfiddle.net/davidwaterston/zX8aU/

listLast

Description
Gets the last element of a list.

Availability
v1.0

Function syntax
listLast(list [, delimiter ])

Returns
The last element of the list.

Parameters

Usage

The following table shows examples of listLast processing:

jsFiddle

http://jsfiddle.net/davidwaterston/BbLD8

listLen

Description
Determines the number of elements in a list.

Availability
v1.0

Function syntax
listLen(list [, delimiter ])

Returns
The number of elements in a list as an integer.

Parameters

Usage

The following table shows examples of listLen processing:

jsFiddle

http://jsfiddle.net/davidwaterston/Uz4P2

listPrepend

Description
Inserts an element at the beginning of a list.

Availability
v1.0

Function syntax
listPrepend(list, value [, delimiter ])

Returns
A copy of the list, with value inserted at the first position.

Parameters

Usage

The following table shows examples of listPrepend processing:

jsFiddle

http://jsfiddle.net/davidwaterston/n8AXz

listQualify

Description
Inserts a string at the beginning and end of all list elements.

Availability
v1.0

Function syntax
listQualify(list, qualifier [, delimiter ])

Returns
A copy of the list, with qualifier before and after each element.

Parameters

Usage

The following table shows examples of listQualify processing:

jsFiddle

http://jsfiddle.net/davidwaterston/ArLh9

listRemove

Description Removes elements in one list from another list. Matching is case-sensitive.

Availability v1.6

Function syntax listRemove(list1, list2 [, delimiter ])

Returns A new list, with the elements in list2 removed from list1.

Parameters

Usage

The following table shows examples of listRemove processing:

jsFiddle

http://jsfiddle.net/davidwaterston/WeZtB/

listRemoveNoCase

Description Removes elements in one list from another list. Matching is not case-sensitive.

Availability v1.6

Function syntax listRemoveNoCase(list1, list2 [, delimiter ])

Returns A new list, with the elements in list2 removed from list1.

Parameters

Usage

The following table shows examples of listRemoveNoCase processing:

jsFiddle

http://jsfiddle.net/davidwaterston/BYXnk/

listRemoveDuplicates

Description
Removes all duplicate elements from a list. Where an element matches one which appears earlier in the list it is removed. Matching is case-sensitive.

Availability
v1.1

Function syntax
listRemoveDuplicates(list, [, delimiter ])

Returns
A copy of the list, with duplicate elements removed.

Parameters

Usage

The following table shows examples of listRemoveDuplicates processing:

jsFiddle

http://jsfiddle.net/davidwaterston/qHvHg

listRemoveDuplicatesNoCase

Description
Removes all duplicate elements from a list. Where an element matches one which appears earlier in the list it is removed. Matching is not case-sensitive.

Availability
v1.1

Function syntax
listRemoveDuplicatesNoCase(list, [, delimiter ])

Returns
A copy of the list, with duplicate elements removed.

Parameters

Usage

The following table shows examples of listRemoveDuplicatesNoCase processing:

jsFiddle

http://jsfiddle.net/davidwaterston/8NpEY

listReplace

Description Replaces any occurances of an element in a list with a different element. Matching is case-sensitive.

Availability v1.6

Function syntax listReplace(list, value1, value2 [, delimiter ])

Returns A new list, with any occurrances of value1 replaced by value2.

Parameters

Usage

The following table shows examples of listReplace processing:

jsFiddle

http://jsfiddle.net/davidwaterston/5TdcQ/

listReplaceNoCase

Description Replaces any occurances of an element in a list with a different element. Matching is not case-sensitive.

Availability v1.6

Function syntax listReplaceNoCase(list, value1, value2 [, delimiter ])

Returns A new list, with any occurrances of value1 replaced by value2.

Parameters

Usage

The following table shows examples of listReplaceNoCase processing:

jsFiddle

http://jsfiddle.net/davidwaterston/nbmmu/

listRest

Description
Gets a list, without its first element.

Availability
v1.0

Function syntax
listRest(list [, delimiter ])

Returns
A copy of list, without the first element. If list has one element, returns an empty list.

Parameters

Usage

The following table shows examples of listRest processing:

jsFiddle

http://jsfiddle.net/davidwaterston/Q6Hh4

listReverse

Description
Reverses the order of elements in a list.

Availability
v1.0

Function syntax
listReverse(list [, delimiter ])

Returns
A copy of list, with the order of the elements reversed.

Parameters

Usage

The following table shows examples of listReverse processing:

jsFiddle

http://jsfiddle.net/davidwaterston/vsmXu

listSetAt

Description
Replaces the contents of a list element.

Availability
v1.0

Function syntax
listSetAt(list, position, value [, delimiter ])

Returns
A copy of list, with a new value assigned to the element at a specified position.

Parameters

Usage

The following table shows examples of listSetAt processing:

jsFiddle

http://jsfiddle.net/davidwaterston/CTN2w

listSort

Description
Sorts list elements according to a sort type and sort order.

Availability
v1.0

Function syntax
ListSort(list, sort_type [, sort_order, delimiter ])

Returns
A copy of a list, sorted.

Parameters

Usage

The following table shows examples of listSort processing:

jsFiddle

http://jsfiddle.net/davidwaterston/ff2zy

listUnion

Description
Combines the elements from two different lists.

Availability
v1.6

Function syntax
listUnion(list1, list2 [, delimiter ])

Returns
A new list with duplicates removed containing all elements from both list1 and list2.

Parameters

Usage

The following table shows examples of listUnion processing:

jsFiddle

http://jsfiddle.net/davidwaterston/gUGGw/

listValueCount

Description
Counts instances of a specified value in a list. The search is case-sensitive.

Availability
v1.3

Function syntax
listValueCount(list, value [, delimiter ])

Returns
The number of instances of value in the list.

Parameters

Usage

The following table shows examples of listValueCount processing:

jsFiddle

http://jsfiddle.net/davidwaterston/WPyED

listValueCountNoCase

Description
Counts instances of a specified value in a list. The search is not case-sensitive.

Availability
v1.3

Function syntax
listValueCountNoCase(list, value [, delimiter ])

Returns
The number of instances of value in the list.

Parameters

Usage

The following table shows examples of listValueCountNoCase processing:

jsFiddle

http://jsfiddle.net/davidwaterston/4gVnX

jsFiddle

In addition to the examples included in the file jlist-test.htm, all functions are available in jsFiddle for ad-hoc testing:

List of fiddles by Chris Tsongas
List of fiddles by David Waterston

listAppend
listChangeDelims
listConcatenate
listContains
listContainsNoCase
listDeleteAt
listDifference
listFind
listFindNoCase
listFirst
listGetAt
listInsertAt
listIntersection
listLast
listLen
listPrepend
listQualify
listRemove
listRemoveNoCase
listRemoveDuplicates
listRemoveDuplicatesNoCase
listReplace
listReplaceNoCase
listRest
listReverse
listSetAt
listSort
listUnion
listValueCount
listValueCountNoCase

Version History

Future Plans

Current and planned work for jList is public and detailed in Trello.