v1.6.1
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.
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.
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.
jList has been tested in the latest versions of:
- Chrome
- Firefox
- Safari
- Opera
- Internet Explorer
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.
- 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] (http://dvolvr.davidwaterston.com)
- Forked by [Chris Tsongas] (http://www.bitmojo.com)
- Github repository: http://davidwaterston.github.com/jList and https://github.com/tsongas/jList
- Tested using Jasmine 1.2.0.
- Documentation written in Markdown using Byword and Atom with the Markdown-Preview package.
- Pushed to GitHub using Tower.
- Made in Scotland and the United States of America.
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
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
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/
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
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
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
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/
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
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
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
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
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
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/
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
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
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
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','~') | ' |
jList.listQualify('cat,dog','@','~') | '@cat,dog@' |
jList.listQualify('Cat-Dog--Mouse','$','-') | '$Cat$-$Dog$-$$-$Mouse$' |
jsFiddle
http://jsfiddle.net/davidwaterston/ArLh9
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/
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/
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('a |
'a |
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
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('a |
'a |
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
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/
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/
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
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
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
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('a |
'a |
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
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/
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
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
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 | 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. |