Skip to content

davidwaterston/jList

Repository files navigation

jList

v1.6.1

What does it do?

jList is a collection of functions that bring delimited-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/tsongas/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/tsongas/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 to be aware of - 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


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

Parameter Description
list A list or a variable that contains one.
value An element to be appended to list
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

Usage

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

Statement Output
jList.listAppend('elem1,elem2', 'rabbit' ) 'elem1,elem2,rabbit'
jList.listAppend('elem1,elem2','') 'elem1,elem2,'
jList.listAppend('','elem1,elem2') 'elem1,elem2'
jList.listAppend('cat-dog-mouse','hamster','-') 'cat-dog-mouse-hamster'

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

Parameter Description
list A list or a variable that contains one.
new_delimiter Delimiter string or a variable that contains one.
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

Usage

The following table shows examples of listChangeDelims processing:

Statement Output
jList.listChangeDelims('a,e,c,b,d', '=') 'a=e=c=b=d'
jList.listChangeDelims('a.e.c.b.d', ',', '.') 'a,e,c,b,d'
jList.listChangeDelims('a,e,c,b,d','-','!') 'a,e,c,b,d'
jList.listChangeDelims('a,e,c,b,d','-',',') 'a-e-c-b-d'

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

Parameter Description
list1 A list or a variable that contains one.
list2 A list or a variable that contains one.
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

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:

Statement Output
jList.listConcatenate('elem1,elem2', 'rabbit,dog' ) 'elem1,elem2,rabbit,dog'
jList.listConcatenate('elem1,elem2','') 'elem1,elem2'
jList.listConcatenate('','elem1,elem2') 'elem1,elem2'
jList.listConcatenate('cat-dog-mouse','hamster','-') 'cat-dog-mouse-hamster'

jsFiddle

http://jsfiddle.net/tsongas/2mWRJ/


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

Parameter Description
list A list or a variable that contains one.
substring A string or a variable that contains one. Item for which to search.
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

Usage

The following table shows examples of listContains processing:

Statement Output
jList.listContains('cat,dog,mouse,rabbit,dog', 'og') 2
jList.listContains('cat.dog.mouse.rabbit.dog', 'og', '.') 2
jList.listContains('cat,dog,mouse,rabbit,dog', 'OG') 0
jList.listContains('cat.dog.mouse.rabbit.dog', 'Rab', '.') 0
jList.listContains('cat,dog,mouse,rabbit,dog', 'tr') 0

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

Parameter Description
list A list or a variable that contains one.
substring A string or a variable that contains one. Item for which to search.
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

Usage

The following table shows examples of listContainsNoCase processing:

Statement Output
jList.listContainsNoCase('cat,dog,mouse,rabbit,dog', 'og') 2
jList.listContainsNoCase('cat.dog.mouse.rabbit.dog', 'og', '.') 2
jList.listContainsNoCase('cat,dog,mouse,rabbit,dog', 'OG') 2
jList.listContainsNoCase('cat.dog.mouse.rabbit.dog', 'Rab', '.') 4
jList.listContains('cat,dog,mouse,rabbit,dog', 'tr') 0

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

Parameter Description
list A list or a variable that contains one.
position A positive integer or a variable that contains one. Position at which to delete element. The first list position is 1.
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

Usage

The following table shows examples of listDeleteAt processing:

Statement Output
jList.listDeleteAt('elem1,elem2,elem3',2) 'elem1,elem3'
jList.listDeleteAt('elem1,elem2',4) 'elem1,elem2'
jList.listDeleteAt('cat-dog-mouse',3,'-') 'cat-dog'

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

Parameter Description
list1 A list or a variable that contains one.
list2 A list or a variable that contains one.
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

Usage

The following table shows examples of listDifference processing:

Statement Output
jList.listDifference('elem1,elem2', 'elem2,elem3' ) 'elem1,elem3'
jList.listDifference('','elem1,elem2') 'elem1,elem2'
jList.listDifference('elem1,elem2','') 'elem1,elem2'
jList.listDifference('cat-dog-mouse','cat-rabbit-dog-rabbit-hamster','-') 'mouse-rabbit-hamster'

jsFiddle

http://jsfiddle.net/tsongas/QaHLj/


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

Parameter Description
list A list or a variable that contains one.
value A string, a number, or a variable that contains one. Item for which to search.
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

Usage

The following table shows examples of listFind processing:

Statement Output
jList.listFind('elem1,elem2,elem3','elem3') 3
jList.listFind('elem1,elem2,elem3','Elem3') 0
jList.listFind('elem1,elem2','cat') 0
jList.listFind('cat-dog--mouse','dog','-') 2
jList.listFind('5-4-3-2-1',4,'-') 2

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

Parameter Description
list A list or a variable that contains one.
value A string, a number, or a variable that contains one. Item for which to search.
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

Usage

The following table shows examples of listFindNoCase processing:

Statement Output
jList.listFindNoCase('elem1,elem2,elem3','elem3') 3
jList.listFindNoCase('elem1,elem2,elem3','Elem3') 3
jList.listFindNoCase('cat,dog','CAT') 1
jList.listFindNoCase('Cat-Dog--Mouse','dog','-') 2
jList.listFindNoCase('5-4-3-2-1',4,'-') 2

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

Parameter Description
list A list or a variable that contains one.
value A string, a number, or a variable that contains one. Item for which to search.
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

Usage

The following table shows examples of listFirst processing:

Statement Output
jList.listFirst('elem1,elem2,elem3') 'elem1'
jList.listFirst('cat,dog','~') 'cat,dog'
jList.listFirst('Cat-Dog--Mouse','-') 'Cat'
jList.listFirst('5-4-3-2-1','-') '5'

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

Parameter Description
list A list or a variable that contains one.
position A positive integer or a variable that contains one. Position at which to get element. The first list position is 1.
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

Usage

The following table shows examples of listGetAt processing:

Statement Output
jList.listGetAt('elem1,elem2,elem3',1) 'elem1'
jList.listGetAt('cat,dog',1,'~') cat,dog
jList.listGetAt('Cat-Dog--Mouse',3,'-') ''
jList.listGetAt('5-4-3-2-1',5,'-') '1'

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

Parameter Description
list A list or a variable that contains one.
position A positive integer or a variable that contains one. Position at which to insert value. The first list position is 1.
value An element to be inserted
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

Usage

The following table shows examples of listInsertAt processing:

Statement Output
jList.listInsertAt('elem1,elem2,elem3',1,'hello') 'hello,elem1,elem2,elem3'
jList.listInsertAt('cat,dog',1,'monkey','~') 'monkey~cat,dog'
jList.listInsertAt('Cat-Dog--Mouse',3,'Elephant','-') 'Cat-Dog-Elephant-Mouse'
jList.listInsertAt('5-4-3-2-1',5,'999','-') '5-4-3-2-999-1'

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

Parameter Description
list1 A list or a variable that contains one.
list2 A list or a variable that contains one.
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

Usage

The following table shows examples of listIntersection processing:

Statement Output
jList.listIntersection('elem1,elem2', 'elem2,elem3' ) 'elem2'
jList.listIntersection('','elem1,elem2') ''
jList.listIntersection('elem1,elem2','') ''
jList.listIntersection('cat-dog-mouse','cat-rabbit-dog-rabbit-hamster','-') 'cat-dog'

jsFiddle

http://jsfiddle.net/tsongas/QBtZd/


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

Parameter Description
list A list or a variable that contains one.
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

Usage

The following table shows examples of listLast processing:

Statement Output
jList.listLast('elem1,elem2,elem3') 'elem3'
jList.listLast('cat,dog','~') 'cat,dog'
jList.listLast('Cat-Dog--Mouse','-') 'Mouse'

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

Parameter Description
list A list or a variable that contains one.
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

Usage

The following table shows examples of listLen processing:

Statement Output
jList.listLen('elem1,elem2,elem3') 3
jList.listLen('cat,dog','~') 1
jList.listLen('Cat-Dog--Mouse','-') 4

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

Parameter Description
list A list or a variable that contains one.
value An element to be inserted at the beginning of list.
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

Usage

The following table shows examples of listPrepend processing:

Statement Output
jList.listPrepend('elem1,elem2,elem3','elem99') 'elem99,elem1,elem2,elem3'
jList.listPrepend('cat,dog','mouse','~') 'mouse~cat,dog'
jList.listPrepend('Cat-Dog--Mouse','Rabbit','-') 'Rabbit-Cat-Dog--Mouse'
jList.listPrepend('','Rabbit','-') 'Rabbit'

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

Parameter Description
list A list or a variable that contains one.
qualifier A string or a variable that contains one. Character or string to insert before and after the list elements.
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

Usage

The following table shows examples of listQualify processing:

Statement Output
jList.listQualify('elem1,elem2,elem3','~') 'elem1,elem2,elem3'
jList.listQualify('cat,dog','@','~') '@cat,dog@'
jList.listQualify('Cat-Dog--Mouse','$','-') '$Cat$-$Dog$-$$-$Mouse$'

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

Parameter Description
list1 A list or a variable that contains one.
list2 A list or a variable that contains one.
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

Usage

The following table shows examples of listRemove processing:

Statement Output
jList.listRemove('elem1,elem2,elem3','elem2') 'elem1,elem3'
jList.listRemove('elem1,elem2','elem2,elem3') 'elem1'
jList.listRemove('cat-dog-mouse','mouse-dog-cat','-') ''
jList.listRemove('cat-dog-Mouse','mouse-dog-cat','-') 'Mouse'

jsFiddle

http://jsfiddle.net/tsongas/Y5Zgf/


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

Parameter Description
list1 A list or a variable that contains one.
list2 A list or a variable that contains one.
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

Usage

The following table shows examples of listRemoveNoCase processing:

Statement Output
jList.listRemoveNoCase('elem1,elem2,elem3','elem2') 'elem1,elem3'
jList.listRemoveNoCase('elem1,elem2','elem2,elem3') 'elem1'
jList.listRemoveNoCase('cat-dog-mouse','mouse-dog-cat','-') ''
jList.listRemoveNoCase('cat-dog-Mouse','mouse-dog-cat','-') ''

jsFiddle

http://jsfiddle.net/tsongas/bTerA/


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

Parameter Description
list A list or a variable that contains one.
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

Usage

The following table shows examples of listRemoveDuplicates processing:

Statement Output
jList.listRemoveDuplicates('a,e,c,e,a,b,d') 'a,e,c,b,d'
jList.listRemoveDuplicates('a,f,c,d,A,f,C,d') 'a,f,c,d,A,C'
jList.listRemoveDuplicates('a121ZCAAa12','~') 'a121ZC'
jList.listRemoveDuplicates('1.1.1.1.1.1','.') '1'
jList.listRemoveDuplicates('12,3,4,1,12,4,6') '12,3,4,1,6'

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

Parameter Description
list A list or a variable that contains one.
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

Usage

The following table shows examples of listRemoveDuplicatesNoCase processing:

Statement Output
jList.listRemoveDuplicatesNoCase('a,e,c,e,a,b,d') 'a,e,c,b,d'
jList.listRemoveDuplicatesNoCase('a,f,c,d,A,f,C,d') 'a,f,c,d'
jList.listRemoveDuplicatesNoCase('a121ZC','~') 'a121ZC'
jList.listRemoveDuplicatesNoCase('1.1.1.1.1.1','.') '1'
jList.listRemoveDuplicatesNoCase('12,3,4,1,12,4,6') '12,3,4,1,6'
jList.listRemoveDuplicatesNoCase('cat,dog,rabbit,DOG,Rabbit') 'cat,dog,rabbit'

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

Parameter Description
list A list or a variable that contains one.
value1 Element in list to be replaced.
value2 Element to replace value1.
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

Usage

The following table shows examples of listReplace processing:

Statement Output
jList.listReplace('elem1,elem2,elem3','elem2','elem4') 'elem1,elem4,elem3'
jList.listReplace('elem1','elem1','elem2') 'elem2'
jList.listReplace('cat-dog-mouse','mouse','flea','-') 'cat-dog-flea'
jList.listReplace('cat-dog-mouse','Mouse','flea','-') 'cat-dog-mouse'

jsFiddle

http://jsfiddle.net/tsongas/6ZCDY/


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

Parameter Description
list A list or a variable that contains one.
value1 Element in list to be replaced.
value2 Element to replace value1.
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

Usage

The following table shows examples of listReplaceNoCase processing:

Statement Output
jList.listReplaceNoCase('elem1,elem2,elem3','elem2','elem4') 'elem1,elem4,elem3'
jList.listReplaceNoCase('elem1','elem1','elem2') 'elem2'
jList.listReplaceNoCase('cat-dog-mouse','mouse','flea','-') 'cat-dog-flea'
jList.listReplaceNoCase('cat-dog-mouse','Mouse','flea','-') 'cat-dog-flea'

jsFiddle

http://jsfiddle.net/tsongas/5LFzJ/


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

Parameter Description
list A list or a variable that contains one.
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

Usage

The following table shows examples of listRest processing:

Statement Output
jList.listRest('elem1,elem2,elem3') 'elem2,elem3'
jList.listRest('cat,dog','~') ''
jList.listRest('Cat-Dog--Mouse','-') 'Dog--Mouse'

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

Parameter Description
list A list or a variable that contains one.
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

Usage

The following table shows examples of listReverse processing:

Statement Output
jList.listReverse('elem1,elem2,elem3') 'elem3,elem2,elem1'
jList.listReverse('cat,dog','~') 'cat,dog'
jList.listReverse('Cat-Dog--Mouse','-') 'Mouse--Dog-Cat'

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

Parameter Description
list A list or a variable that contains one.
position A positive integer or a variable that contains one. Position at which to set a value. The first list position is 1.
value An element to be injected into list.
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

Usage

The following table shows examples of listSetAt processing:

Statement Output
jList.listSetAt('elem1,elem2,elem3',1,'elem99') 'elem99,elem1,elem2,elem3'
jList.listSetAt('cat,dog',2,'hamster','~') 'cat,dog,hamster'
jList.listSetAt('Cat-Dog--Mouse',3,'Hamster','-') 'Cat-Dog-Hamster-Mouse'

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

Parameter Description
list A list or a variable that contains one.
sort_type numeric: sorts numbers
  alpha: sorts text alphabetically. Case sensistive.
sort_order asc - ascending sort order. This is the default.
  desc - descending sort order.
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

Usage

The following table shows examples of listSort processing:

Statement Output
jList.listSort('a,e,c,b,d') 'a,b,c,d,e'
jList.listSort('a,f,c,d,A,C') 'A,C,a,c,d,f'
jList.listSort('a121ZC','alpha','asc','~') 'aZC121'
jList.listSort('12,3,4,1,55,5,6','alpha','asc') '1,12,3,4,5,55,6'
jList.listSort('12,3,4,1,55,5,6','numeric','asc') '1,3,4,5,6,12,55'

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

Parameter Description
list1 A list or a variable that contains one.
list2 A list or a variable that contains one.
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

Usage

The following table shows examples of listUnion processing:

Statement Output
jList.listUnion('elem1,elem2', 'elem2,elem3' ) 'elem1,elem2,elem3'
jList.listUnion('','elem1,elem2') 'elem1,elem2'
jList.listUnion('elem1,elem2','') 'elem1,elem2'
jList.listUnion('cat-dog-mouse','cat-rabbit','-') 'cat-dog-mouse-rabbit'

jsFiddle

http://jsfiddle.net/tsongas/z7NEP/


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

Parameter Description
list A list or a variable that contains one.
value Item for which to search. Can be a string or number, or a variable that contains one. The search is case-sensitive.
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

Usage

The following table shows examples of listValueCount processing:

Statement Output
jList.listValueCount('a,e,a,c,a,b,a,d', 'a') 4
jList.listValueCount('a,e,a,c,a,b,a,d', 'A') 0
jList.listValueCount('a,e,A,c,a,b,A,d', 'A') 2
jList.listValueCount('a;e;A;c;a;b;A;d', 'A') 0
jList.listValueCount('a;e;A;c;a;b;A;d', 'A', ';') 2
jList.listValueCount('John,Mark,Steve,Alan,John,john', 'john') 1
jList.listValueCount('1,2,3,1,2,3', 3) 2
jList.listValueCount('1,2,3,1,2,3', '3') 2

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

Parameter Description
list A list or a variable that contains one.
value Item for which to search. Can be a string or number, or a variable that contains one. The search is not case-sensitive.
delimiter A string or a variable that contains one. The character that separates list elements. The default value is comma.

Usage

The following table shows examples of listValueCountNoCase processing:

Statement Output
jList.listValueCountNoCase('a,e,a,c,a,b,a,d', 'a') 4
jList.listValueCountNoCase('a,e,a,c,a,b,a,d', 'A') 4
jList.listValueCountNoCase('a,e,A,c,a,b,A,d', 'A') 4
jList.listValueCountNoCase('a;e;A;c;a;b;A;d', 'A') 0
jList.listValueCountNoCase('a;e;A;c;a;b;A;d', 'A', ';') 4
jList.listValueCountNoCase('John,Mark,Steve,Alan,John,john', 'john') 3
jList.listValueCountNoCase('1,2,3,1,2,3', 3) 2
jList.listValueCountNoCase('1,2,3,1,2,3', '3') 2

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

Version Release Date Details
1.6.1 19th August, 2017 Tidied up this ReadMe file to take account of Markdown rendering changes introduced in GitHub.com since the last release.
1.6.0 10th June, 2013 Added eight new functions - listConcatenate, listDifference, listIntersection, listRemove, listRemoveNoCase, listReplace, listReplaceNoCase and listUnion.
1.5.0 10th September, 2012 Added two new functions - listContains and listContainsNoCase.
1.4.1 8th September, 2012 Bug fix to listFind (and indirectly listFindNoCase to resolve a problem with older (pre-9) versions of Internet Explorer.
1.4.0 3rd September, 2012 Added extra parameter checking to each function, replaced 'typeof undefined' checks with '=== undefined' to ensure compatibility with jsLint Edition 2012-08-23. Added the Jasmine test suite with 250 tests.
1.3.0 16th June, 2012 Added three new functions - listChangeDelims, listValueCount and listValueCountNoCase.
1.2.0 21st May, 2012 Minor changes to listRemoveDuplicates and listRemoveDuplicatesNoCase to improve performance with larger lists (100,000+ elements).
1.1.0 18th May, 2012 Added two new functions - listRemoveDuplicates and listRemoveDuplicatesNoCase.
    Updated sample code and documentation.
    Added this version history.
1.0.0 15th May, 2012 Initial release.