Namespace atropa.objects

Version 20130121.
Utilities for handling objects.
Defined in: <node_modules/atropa-objects/src/atropa-objects.js>.

Namespace Summary
Constructor Attributes	Constructor Name and Description
	atropa.objects Utilities for handling objects.

Method Summary
Method Attributes	Method Name and Description
<static>	atropa.objects.convertObjectToArray(obj) Converts an object into an array of arrays to make it possible to sort and enumerate properties reliably.
<static>	atropa.objects.sort(obj, sortFn) Converts an object into an array of arrays and allows for reliable sorting and enumeration.
<static>	atropa.objects.sortProperties(obj, sortFn) Sorts an object by its properties using a user defined algorithm.
<static>	atropa.objects.sortPropertiesAlphabetically(obj) Throws an error, `String.prototype.localeCompare` is not standardized.
<static>	atropa.objects.sortPropertiesNumerically(obj) Sorts an object by its properties numerically.
<static>	atropa.objects.sortValues(obj, sortFn) Sorts an object by its values using a user defined algorithm.
<static>	atropa.objects.sortValuesAlphabetically() Throws an error, `String.prototype.localeCompare` is not standardized.
<static>	atropa.objects.sortValuesNumerically(obj) Sorts an object by its values numerically.

Namespace Detail

atropa.objects

Utilities for handling objects.
Author: Matthew Christopher Kastor-Inare III
☭ Hial Atropa!! ☭.

Method Detail

<static> {Array} atropa.objects.convertObjectToArray(obj)

Converts an object into an array of arrays to make it possible to sort and enumerate properties reliably.
Author: Matthew Christopher Kastor-Inare III
☭ Hial Atropa!! ☭.

 var x = {
     "stuffing" : "cotton",
     "nose" : "button",
     "name" : "bear"
 };
 console.log( atropa.objects.convertObjectToArray(x) );
 // logs [["stuffing", "cotton"], ["nose", "button"], ["name", "bear"]]

Parameters:
{Object} obj: An object.

Returns:: {Array} Returns an array of arrays where each nested array will have the object's key stored in element 0 and the value stored in element 1. The reason an array of arrays is returned is because JavaScript does not guarantee the order of properties on an object so there is no relizble way to sort an objects keys or values.

See:: "The mechanics and order of enumerating the properties [of an object] is not specified." http://www.ecma-international.org/ecma-262/5.1/#sec-12.6.4

<static> {Array} atropa.objects.sort(obj, sortFn)

Converts an object into an array of arrays and allows for reliable sorting and enumeration.
Author: Matthew Christopher Kastor-Inare III
☭ Hial Atropa!! ☭.

 var wordsCounted, sortedByValues, sortedByProperties;
 wordsCounted = {
     "document3" : 150,
     "document1" : 300,
     "document2" : 25
 };
 // sorting by property value as numbers
 function valSort(a, b) {
     return a[1] - b[1];
 }
 // sorting by property names as strings
 function propSort(a, b) {
     return a[0].localeCompare(b[0]);
 }
 sortedByValues = atropa.objects.sort(wordsCounted, valSort);
 sortedByProperties = atropa.objects.sort(wordsCounted, propSort);
 console.log('sorted by value: ', sortedByValues);
 console.log('sorted by properties: ', sortedByProperties);
 
 // logs:
 // sorted by value: [
 //     ["document2", 25],
 //     ["document3", 150],
 //     ["document1", 300]
 // ]
 // sorted by properties: [
 //     ["document1", 300],
 //     ["document2", 25],
 //     ["document3", 150]
 // ]

 Lexicographic sorting:
 This    [1, 2, 10, 'A', 'a','Z', 'z']
 becomes [1, 10, 2, "A", "Z", "a", "z"]

Parameters:
{Object} obj: An object.
{Function} sortFn: Optional. The sorting function. This function will be given two arguments. Compare the two arguments and return: 0 if they are equal, greater than zero if the first argument is greater than the second, or less than zero if the second argument is greater than the first. If the sorting function is not given, the array will be sorted lexographically by each elements toString value.

Returns:: {Array} Returns an array of arrays where each nested array will have the objects key stored in element 0 and the value stored in element 1. The reason an array of arrays is returned is because JavaScript does not guarantee the order of properties on an object so there is no relizble way to sort an objects keys or values.

See:: atropa.objects.convertObjectToArray; http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.4.11; https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/sort

<static> {Array} atropa.objects.sortProperties(obj, sortFn)

Sorts an object by its properties using a user defined algorithm.
Author: Matthew Christopher Kastor-Inare III
☭ Hial Atropa!! ☭.

 var wordsCounted;
 wordsCounted = {
     "document3" : 150,
     "document1" : 300,
     "document2" : 25
 };
 // sorting by property names as strings
 function sortFn(a, b) {
     return a.localeCompare(b);
 }
 console.log( atropa.objects.sortProperties(wordsCounted, sortFn) );
 // logs: [["document1", 300], ["document2", 25], ["document3", 150]]

Parameters:
{Object} obj: An object.
{Function} sortFn: The sorting function. This function will be given two arguments. Compare the two arguments and return: 0 if they are equal, greater than zero if the first argument is greater than the second, or less than zero if the second argument is greater than the first.

Returns:: {Array} Returns an array of arrays where each nested array will have the objects key stored in element 0 and the value stored in element 1.

See:: atropa.objects.sort

<static> atropa.objects.sortPropertiesAlphabetically(obj)

Throws an error, String.prototype.localeCompare is not standardized. Yes, localeCompare is in the standard but, at this time the actual comparison is implementation dependant. This means that "alphabetical order" can be different on different platforms. What I found was that in node the array of ['a','Z','A','z'] would be sorted to ['A','Z','a','z"], while on firefox it would be sorted to ['a','A','z','Z']. Who knows if another implementor would sort it ['A','a','Z','z']? In order to provide a reliable implementation I would have to create my own implementation of String.prototype.localeCompare and that's just too much work for me to do alone.

Parameters:
obj

Throws:
{Error}: "String.prototype.localeCompare is not standardized"

<static> {Array} atropa.objects.sortPropertiesNumerically(obj)

Sorts an object by its properties numerically.
Author: Matthew Christopher Kastor-Inare III
☭ Hial Atropa!! ☭.

 var wordsCounted;
 wordsCounted = {
     "3" : "Document A",
     "2" : "Document Z",
     "1" : "Document M"
 };
 console.log( atropa.objects.sortPropertiesNumerically(wordsCounted) );
 // logs: [["1", "Document M"], ["2", "Document Z"], ["3", "Document A"]]

Parameters:
{Object} obj: A simple object where the properties all have numeric-ish values.

Returns:: {Array} Returns an array of arrays where each nested array will have the objects key stored in element 0 and the value stored in element 1.

See:: atropa.objects.sort

<static> {Array} atropa.objects.sortValues(obj, sortFn)

Sorts an object by its values using a user defined algorithm.
Author: Matthew Christopher Kastor-Inare III
☭ Hial Atropa!! ☭.

 var wordsCounted;
 wordsCounted = {
     "document3" : 150,
     "document1" : 300,
     "document2" : 25
 };
 // sorting by values as numbers
 function sortFn(a, b) {
     return a - b;
 }
 console.log( atropa.objects.sortValues(wordsCounted, sortFn) );
 // logs: [["document2", 25], ["document3", 150], ["document1", 300]]

Parameters:
{Object} obj: An object.
{Function} sortFn: The sorting function. This function will be given two arguments. Compare the two arguments and return: 0 if they are equal, greater than zero if the first argument is greater than the second, or less than zero if the second argument is greater than the first.

Returns:: {Array} Returns an array of arrays where each nested array will have the objects key stored in element 0 and the value stored in element 1.

See:: atropa.objects.sort

<static> atropa.objects.sortValuesAlphabetically()

Throws:
{Error}: "String.prototype.localeCompare is not standardized"

<static> {Array} atropa.objects.sortValuesNumerically(obj)

Sorts an object by its values numerically.
Author: Matthew Christopher Kastor-Inare III
☭ Hial Atropa!! ☭.

 var wordsCounted;
 wordsCounted = {
     "document3" : 150,
     "document1" : 300,
     "document2" : 25
 };
 console.log( atropa.objects.sortValuesNumerically(wordsCounted) );
 // logs [["document2", 25], ["document3", 150], ["document1", 300]]

Parameters:
{Object} obj: A simple object where the properties all have numeric-ish values.

Returns:: {Array} Returns an array of arrays where each nested array will have the objects key stored in element 0 and the value stored in element 1.

See:: atropa.objects.sort

Classes

Namespace atropa.objects