Sugar.js

https://sugarjs.com/docs/
Admin
Sugar.js is a JavaScript library that extends native objects with enhanced methods for working with...
Tokens:21,083
Snippets:192
Trust Score:9.3
Update:8 months ago
Show doc for...
Tokens:
Raw
### fnFromIndex

Source: https://sugarjs.com/docs/index

Runs native array functions starting from a specified index. Supports looping and enhanced method features.

```APIDOC
## fnFromIndex

### Description
Runs native array functions beginning from `startIndex`. If `loop` is `true`, once the end of the array has been reached, iteration will continue from the start of the array up to `startIndex - 1`. If `loop` is false it can be omitted. Standard arguments are then passed which will be forwarded to the native methods. When available, methods are always `enhanced`. This includes deep properties for `map`, and enhanced matching for `some`, `every`, `filter`, `find`, and `findIndex`.

### Method
Instance method (called on an array instance)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
users.mapFromIndex(2, 'name');

users.mapFromIndex(2, true, 'name');

names.forEachFromIndex(10, log);

names.everyFromIndex(15, /^[A-F]/);
```

### Response
#### Success Response (200)
Mixed: The return type depends on the specific native function being called (e.g., Array for `filterFromIndex`, Boolean for `everyFromIndex`).

#### Response Example
(Depends on the specific method used and the array content)
```

--------------------------------

### from

Source: https://sugarjs.com/docs/index

Returns a new array containing elements from a specified starting index to the end of the original array.

```APIDOC
## from

### Description
Returns a slice of the array from `index`.

### Method
Instance method (called on an array instance)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
['a','b','c'].from(1)

['a','b','c'].from(2)
```

### Response
#### Success Response (200)
Array: A new array containing elements from the specified index to the end.

#### Response Example
(Depends on the array content and the starting index)
```

--------------------------------

### Format Dates with Short English Locales in Sugar.js

Source: https://sugarjs.com/docs/index

Provides examples of formatting dates using the `short` method with various English locale variants (`en`, `en-US`, `en-GB`, `en-AU`, `en-CA`). It highlights differences in date ordering (MM/DD/YYYY vs. DD/MM/YYYY) and formatting.

```javascript
new Date().short('en')
```

```javascript
new Date().short('en-US')
```

```javascript
new Date().short('en-GB')
```

```javascript
new Date().short('en-AU')
```

```javascript
new Date().short('en-CA')
```

--------------------------------

### Extend Specific Sugar.js Module Methods (e.g., Date)

Source: https://sugarjs.com/docs/index

This example shows how to extend only the methods belonging to a specific Sugar.js module, such as the Date module. This allows for more targeted application of Sugar.js features.

```javascript
Sugar.Date.extend();
```

--------------------------------

### Exclude Specific Namespaces from Sugar.js Extension

Source: https://sugarjs.com/docs/index

This example demonstrates how to exclude specific namespaces (e.g., Array, Number) from being extended by Sugar.js. This is useful when you want to selectively apply Sugar.js functionality.

```javascript
Sugar.extend({
  except: [Array, Number]
});
```

--------------------------------

### Get First Element(s) of Array - JavaScript

Source: https://sugarjs.com/docs/index

The `first` method retrieves the first element of an array. If a number is provided as an argument, it returns the first `num` elements.

```javascript
[1,2,3].first()
```

```javascript
[1,2,3].first(2)
```

--------------------------------

### Get Array Slice from Index - JavaScript

Source: https://sugarjs.com/docs/index

The `from` method returns a new array containing elements from a specified starting index to the end of the original array.

```javascript
['a','b','c'].from(1)
```

```javascript
['a','b','c'].from(2)
```

--------------------------------

### Object.add with Static Method

Source: https://sugarjs.com/docs/index

Example of using the `Object.add` method statically to merge properties from `obj2` into `obj1`. This method is part of Sugar.js's object utilities and is available as a static function by default.

```javascript
// Using static methods
Object.keys(Object.add(obj1, obj2))
```

--------------------------------

### Run Array Functions from Specific Index - JavaScript

Source: https://sugarjs.com/docs/index

The `fnFromIndex` family of methods (e.g., `mapFromIndex`, `forEachFromIndex`) allows executing native array functions starting from a specified index. An optional `loop` parameter enables circular iteration. These methods often provide enhanced functionality.

```javascript
users.mapFromIndex(2, 'name');
```

```javascript
users.mapFromIndex(2, true, 'name');
```

```javascript
names.forEachFromIndex(10, log);
```

```javascript
names.everyFromIndex(15, /^[A-F]/);
```

--------------------------------

### Get Internal Array Option (JavaScript)

Source: https://sugarjs.com/docs/index

The `getOption` method retrieves an internal option used by Sugar.js Array methods. This is primarily used for configuring sorting behaviors, such as natural sorting.

```javascript
Sugar.Array.getOption('sortNatural')
```

--------------------------------

### Get Element(s) at Index with Sugar.js

Source: https://sugarjs.com/docs/index

Retrieves the element(s) at a specified index. If 'loop' is true, accessing beyond the array bounds wraps around. Negative indices are supported. Providing an array of indices returns multiple elements.

```javascript
[1,2,3].at(0)
```

```javascript
[1,2,3].at(2)
```

```javascript
[1,2,3].at(4)
```

```javascript
[1,2,3].at(4, true)
```

```javascript
[1,2,3].at(-1)
```

```javascript
[1,2,3].at([0, 1])
```

--------------------------------

### Check if Array Contains Element (JavaScript)

Source: https://sugarjs.com/docs/index

The `includes` method checks if an array contains a specific element. It can optionally start the search from a given index. This method is provided as a polyfill for broader compatibility.

```javascript
[1,2,3].includes(2)
```

```javascript
[1,2,3].includes(4)
```

```javascript
[1,2,3].includes(2, 3)
```

--------------------------------

### Exclude Specific Methods within a Sugar.js Module (e.g., Array)

Source: https://sugarjs.com/docs/index

This example demonstrates how to exclude specific methods (e.g., 'unique', 'average') from being extended within a Sugar.js module like Array. This prevents unwanted methods from being added.

```javascript
Sugar.Array.extend({
  except: ['unique', 'average']
});
```

--------------------------------

### Define and Use Basic Month Format

Source: https://sugarjs.com/docs/index

Demonstrates how to add a simple LDML format for months and then create a date using that format. This is useful for custom date string parsing.

```javascript
Date.getLocale('en').addFormat('{month}');
Date.create('January');
```

--------------------------------

### Create and use a SugarJS Date chainable

Source: https://sugarjs.com/docs/index

Shows how to create a SugarJS Date chainable object and use methods like 'addDays' and 'relative'. The output is retrieved using the 'raw' property.

```javascript
var d = Sugar.Date('tomorrow');
d.addDays(5).relative().raw;
```

--------------------------------

### Create and use a SugarJS Number chainable

Source: https://sugarjs.com/docs/index

Demonstrates creating a SugarJS Number chainable object and applying several methods to it. The final result is accessed via the 'raw' property.

```javascript
var n = new Sugar.Number(5);
n.log().pow(2).round(2).raw;
```

--------------------------------

### Extend All Sugar.js Methods

Source: https://sugarjs.com/docs/index

This snippet demonstrates how to extend all available Sugar.js methods onto native JavaScript prototypes. This is the most comprehensive way to enable Sugar.js functionality.

```javascript
Sugar.extend();
```

--------------------------------

### Create and Convert String Range to Array

Source: https://sugarjs.com/docs/index

Shows how to create a string range and convert it into an array of characters. This is helpful for iterating over alphabetical sequences or generating character sets.

```javascript
String.range('a', 'c').toArray();
```

--------------------------------

### first

Source: https://sugarjs.com/docs/index

Retrieves the first element(s) of an array. An optional number can specify how many elements to return from the beginning.

```APIDOC
## first

### Description
Returns the first element(s) in the array. When `num` is passed, returns the first `num` elements in the array.

### Method
Instance method (called on an array instance)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
[1,2,3].first()

[1,2,3].first(2)
```

### Response
#### Success Response (200)
Mixed: If `num` is not provided, returns the first element. If `num` is provided, returns an array containing the first `num` elements.

#### Response Example
(Depends on the array content and the value of `num`)
```

--------------------------------

### Enable Object Prototype Extension

Source: https://sugarjs.com/docs/index

Shows how to enable Sugar.js to extend `Object.prototype` by setting the `objectPrototype` flag to `true` in `Sugar.extend`. This allows direct use of Sugar.js object methods on object instances, but comes with potential risks.

```javascript
Sugar.extend({
  objectPrototype: true
});
obj1.add(obj2).keys();
```

--------------------------------

### Define and Use Month and Year Format with Optional Year

Source: https://sugarjs.com/docs/index

Shows how to define a more complex LDML format that includes an optional year (either 4-digit or 2-digit) and then create a date using this format. This allows for flexible date input.

```javascript
Date.getLocale('en').addFormat("{months?} (?:{year}|'{yy})");
Date.create("February of '82");
```

--------------------------------

### Get Deep Property Value with Sugar.js

Source: https://sugarjs.com/docs/index

Retrieves a nested property value from an object using dot or bracket notation. Returns undefined if any part of the path does not exist. Supports traversing nested objects and arrays.

```javascript
Object.get(users[0], 'currencies.usd.balance')
```

```javascript
Object.get(users[0], 'profile.addresses[0].city')
```

--------------------------------

### Object.add with Chainable

Source: https://sugarjs.com/docs/index

Illustrates using the `Object.add` method via Sugar.js chainables. This approach creates a Sugar.Object instance and allows chaining of methods like `add` and `keys` without modifying native prototypes.

```javascript
// Using chainables
var obj = new Sugar.Object(obj1);
obj.add(obj2).keys().raw
```

--------------------------------

### Get Last Element(s) of Array (JavaScript)

Source: https://sugarjs.com/docs/index

The `last` method retrieves the last element of an array. If a number `num` is provided, it returns the last `num` elements as a new array. This is useful for accessing the tail of a sequence.

```javascript
[1,2,3].last()
```

```javascript
[1,2,3].last(2)
```

--------------------------------

### Sugar.Array.getOption

Source: https://sugarjs.com/docs/index

Retrieves an internal option used by SugarJS Array methods, primarily for sorting configurations.

```APIDOC
## Sugar.Array.getOption

### Description
Gets an option used internally by Array. Options listed below. Current options are for sorting strings with `sortBy`.

### Method
Accessor

### Endpoint
`Sugar.Array.getOption(name)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **name** (string) - Required - The name of the option to retrieve.

### Request Example
```javascript
Sugar.Array.getOption('sortNatural')
```

### Response
#### Success Response (200)
- **Mixed** - The value of the requested option.

#### Response Example
```json
{
  "example": "true"
}
```
```

--------------------------------

### forEach

Source: https://sugarjs.com/docs/index

Iterates over each element of the array, executing a provided callback function for each element. The context for `this` can also be specified.

```APIDOC
## forEach

### Description
Iterates over the array, calling `eachFn` on each loop. `context` becomes the `this` object. This method is provided as a polyfill.

### Method
Instance method (called on an array instance)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
['a','b','c'].forEach(function(a) {
  // Called 3 times: 'a','b','c'
});
```

### Response
#### Success Response (200)
Undefined: This method does not return a value; it executes the callback for each element.

#### Response Example
(No return value)
```

--------------------------------

### Find Last Index of Element in Array (JavaScript)

Source: https://sugarjs.com/docs/index

The `lastIndexOf` method searches an array from the end and returns the index of the first occurrence of a specified element, or -1 if not found. The search can start from a specified index. This method uses strict equality and is a polyfill.

```javascript
[1,2,1].lastIndexOf(1)
```

```javascript
[1,2,1].lastIndexOf(7)
```

--------------------------------

### Remove elements by index or range from an array (Sugar.js)

Source: https://sugarjs.com/docs/index

The 'removeAt' method removes elements from an array based on their index. If a single index is provided, it removes that element. If a start and end index are provided, it removes the range of elements between them. This method modifies the original array.

```javascript
['a','b','c'].removeAt(0)
```

```javascript
[1,2,3,4].removeAt(1, 2)
```

--------------------------------

### Define and Use Relative Date Format with Number, Unit, and Sign

Source: https://sugarjs.com/docs/index

Demonstrates adding a custom format for relative dates that includes a number, a unit (with a specific range), and a sign, and then creating dates using this format. This allows parsing of phrases like '2 months ago'.

```javascript
Date.getLocale('en').addFormat('{num} {unit:6-7} {sign}');
Date.create('2 months ago');
Date.create('5 years from now');
```

--------------------------------

### Node.js Sugar.js Extension Alias

Source: https://sugarjs.com/docs/index

In Node.js environments, the `require('sugar')()` call acts as an alias for `Sugar.extend()`, providing a concise way to extend native prototypes with Sugar.js functionality.

```javascript
// Node exports is an alias to .extend
require('sugar')();
```

--------------------------------

### Set Number Decimal Separator and Format Number

Source: https://sugarjs.com/docs/index

Explains how to use the `setOption` accessor to change the decimal separator for number formatting in Sugar.js. It then shows how to format a number using the custom decimal separator. This is useful for internationalization and custom number display.

```javascript
Sugar.Number.setOption('decimal', ',');
Sugar.Number.format(49.95);
```

--------------------------------

### Create and Check Number Range

Source: https://sugarjs.com/docs/index

Demonstrates how to create a number range using Sugar.js and check if a specific number is within that range. This is useful for validating input or performing operations on a sequence of numbers.

```javascript
Number.range(5, 10).contains(8);
```

--------------------------------

### Array.prototype.to

Source: https://sugarjs.com/docs/index

Returns a slice of the array up to the specified index.

```APIDOC
## GET /websites/sugarjs/to

### Description
Returns a slice of the array up to `index`.

### Method
GET

### Endpoint
`/websites/sugarjs/to`

### Parameters
#### Query Parameters
- **index** (integer) - Required - The index up to which the slice should be taken.

### Request Example
```
['a','b','c'].to(1)
['a','b','c'].to(2)
```

### Response
#### Success Response (200)
- **result** (Array) - A new array containing elements from the start up to the specified index.

#### Response Example
```json
{
  "result": ["a"]
}
```
```json
{
  "result": ["a", "b"]
}
```
```

--------------------------------

### Construct Array with Sugar.js

Source: https://sugarjs.com/docs/index

Constructs an array of a specified length using a mapping function. This is a shortcut for Array.from with new Array(n). The mapping function receives the current index as an argument.

```javascript
Array.construct(4, function(i) {
  return i * i;
});
```

--------------------------------

### Array.map with String Argument

Source: https://sugarjs.com/docs/index

Demonstrates using the `map` method on an array with a string argument, a Sugar.js enhancement that allows for deep property mapping. This is a shortcut for accessing a specific property of each object in the array.

```javascript
users.map('name');
```

--------------------------------

### Define and Use Relative Date Format with Explicit Mapping

Source: https://sugarjs.com/docs/index

Illustrates defining a custom format for relative dates, including number, unit, and sign, and then creating dates using this format. The second argument to `addFormat` explicitly maps capturing groups to date fields.

```javascript
var loc = Date.getLocale('en');
var arr = ['date', 'hours', 'minutes'];
loc.addFormat('(\d+)(?:th|st|rd)@(\d+):(\d+)', arr);
Date.create('15th@4:15');
```

--------------------------------

### Array.prototype.shuffle

Source: https://sugarjs.com/docs/index

Returns a shuffled copy of the array using the Fisher-Yates algorithm.

```APIDOC
## GET /websites/sugarjs/shuffle

### Description
Returns a copy of the array with the elements randomized. Uses Fisher-Yates algorithm.

### Method
GET

### Endpoint
`/websites/sugarjs/shuffle`

### Parameters
None

### Request Example
```
[1,2,3,4].shuffle()
```

### Response
#### Success Response (200)
- **result** (Array) - A new array with elements in a random order.

#### Response Example
```json
{
  "result": [3, 1, 4, 2]
}
```
```

--------------------------------

### Add Acronym and Camelize String

Source: https://sugarjs.com/docs/index

Shows how to add a custom acronym to Sugar.js's string extensions and then use the `camelize` method to convert a string with underscores into camel case. This is helpful for string manipulation and adhering to coding conventions.

```javascript
Sugar.String.addAcronym('SSL');
Sugar.String.camelize('ssl_error');
```

--------------------------------

### Parse Dates with Specific Locale in Sugar.js

Source: https://sugarjs.com/docs/index

Shows how to parse date strings in different languages by providing the locale code as a second argument to the `Date.create` method. This allows for flexible date interpretation from various linguistic inputs.

```javascript
Date.create('一時間前', 'ja');
```

```javascript
Date.create("d'ici 5 heures", 'fr');
```

--------------------------------

### Set Global Locale in Sugar.js

Source: https://sugarjs.com/docs/index

Demonstrates how to set the default locale for all subsequent date operations globally using the `setLocale` method. This is useful for applications that primarily operate in a single language.

```javascript
// Set "en" as the global locale
Date.setLocale('en');
```

--------------------------------

### Calculate Hours in Date Range

Source: https://sugarjs.com/docs/index

Illustrates how to create a date range and calculate the total number of hours within that range. This is useful for time-based calculations and scheduling.

```javascript
Date.range(today, tomorrow).hours();
```

--------------------------------

### Array.find with Regex Argument

Source: https://sugarjs.com/docs/index

Illustrates using the `find` method on an array with a regular expression argument, another Sugar.js enhancement. This allows for pattern matching within the array elements.

```javascript
names.find(/^H/);
```

--------------------------------

### Create Array from Array-like Object with Sugar.js

Source: https://sugarjs.com/docs/index

Creates an array from an array-like object, providing a polyfill for Array.from. It supports an optional mapping function and context. The mapping function receives the element, index, and the array itself.

```javascript
Array.from({0:'a',1:'b',length:2});
```

--------------------------------

### find

Source: https://sugarjs.com/docs/index

Returns the first element in the array that matches the search criteria. The search can be an element or a function.

```APIDOC
## find

### Description
Returns the first element in the array that matches `search`. `search` can be an array element or a function of type `searchFn`. Implements enhanced matching. This method is also provided as a polyfill in the ES6 module.

### Method
Instance method (called on an array instance)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
users.find(function(user) {
  return user.name === 'Harry';
});
```

### Response
#### Success Response (200)
Mixed: The first matching element in the array, or undefined if no match is found.

#### Response Example
(Depends on the array content and search criteria)
```

--------------------------------

### Array.prototype.sample

Source: https://sugarjs.com/docs/index

Returns a random element or multiple random elements from an array. Optionally removes the sampled elements.

```APIDOC
## GET /websites/sugarjs/sample

### Description
Returns a random element from the array. If `num` is passed, will return an array of `num` elements. If `remove` is true, sampled elements will also be removed from the array. `remove` can also be passed in place of `num`.

### Method
GET

### Endpoint
`/websites/sugarjs/sample`

### Parameters
#### Query Parameters
- **num** (integer) - Optional - The number of random elements to return.
- **remove** (boolean) - Optional - If true, removes the sampled elements from the original array.

### Request Example
```
[1,2,3,4,5].sample()
[1,2,3,4,5].sample(1)
[1,2,3,4,5].sample(3)
[1,2,3,4,5].sample(true)
```

### Response
#### Success Response (200)
- **result** (Mixed or Array) - A random element or an array of random elements.

#### Response Example
```json
{
  "result": 3
}
```
```json
{
  "result": [1, 5, 2]
}
```
```

--------------------------------

### Format Dates with Relative Time in Sugar.js

Source: https://sugarjs.com/docs/index

Illustrates how to format dates to display relative time differences using the `relative` method. This is often used for timestamps like 'a few minutes ago' or 'yesterday'.

```javascript
jan.relative('ru');
```

--------------------------------

### Create Shallow Clone of Array with Sugar.js

Source: https://sugarjs.com/docs/index

Creates a shallow clone of an array. This means that the new array will contain references to the same objects as the original array, but the array itself will be a new instance. Returns a new array.

```javascript
[1,2,3].clone()
```

--------------------------------

### Create Array from Object with Sugar.js

Source: https://sugarjs.com/docs/index

Creates an array from an object, similar to Array.from but optimized for arrays. It handles undefined, null, and numbers gracefully. An optional clone parameter can shallow clone the array.

```javascript
Array.create()
```

```javascript
Array.create(8)
```

```javascript
Array.create('abc')
```

```javascript
Array.create([1,2,3])
```

```javascript
Array.create(undefined)
```

--------------------------------

### Format Dates with Short Locale in Sugar.js

Source: https://sugarjs.com/docs/index

Demonstrates formatting a date object into a short string representation according to a specified locale. The output format varies significantly between locales, such as '10.2.2026' for Finnish.

```javascript
new Date().short('fi');
```

--------------------------------

### Group Array into Sub-arrays of Size N with Padding (JavaScript)

Source: https://sugarjs.com/docs/index

The `inGroupsOf` method divides an array into sub-arrays, each containing a specified number of elements. If the last sub-array is shorter, it can be padded with a given value to match the specified size. This is useful for batch processing.

```javascript
[1,2,3,4,5,6,7].inGroupsOf(4)
```

```javascript
[1,2,3,4,5,6,7].inGroupsOf(4, 0)
```

--------------------------------

### Extend Specific Namespaces with Sugar.js

Source: https://sugarjs.com/docs/index

This snippet illustrates how to explicitly define which namespaces (e.g., Date, String) should be extended by Sugar.js. This provides control over which native object types receive Sugar.js enhancements.

```javascript
Sugar.extend({
  namespaces: [Date, String]
});
```

--------------------------------

### Find First Element in Array - JavaScript

Source: https://sugarjs.com/docs/index

The `find` method returns the first element in an array that matches a given search criteria. The search can be a direct value or a callback function. This method is also available as an ES6 polyfill.

```javascript
users.find(function(user) {
  return user.name === 'Harry';
});
```

--------------------------------

### Calculate Hours from Specific Time Range

Source: https://sugarjs.com/docs/index

Demonstrates how to create a date range using a specific time string and calculate the hours within that period. This is useful for parsing and calculating durations from natural language time inputs.

```javascript
Date.range('Tuesday from 1pm to 6pm').hours();
```

--------------------------------

### Format Date with ISO8601 Alias

Source: https://sugarjs.com/docs/index

Formats a date object into a string using the predefined 'ISO8601' alias. This ensures the date is represented in the standard ISO 8601 format.

```javascript
today.format('ISO8601');
```

--------------------------------

### Array.prototype.sum

Source: https://sugarjs.com/docs/index

Calculates the sum of all elements in the array, optionally mapping values before summing.

```APIDOC
## GET /websites/sugarjs/sum

### Description
Sums all values in the array. `map` can be a function of type `mapFn` that maps the value to be summed or a string acting as a shortcut.

### Method
GET

### Endpoint
`/websites/sugarjs/sum`

### Parameters
#### Query Parameters
- **map** (string|function) - Optional - A string key or a function to map values before summing.

### Request Example
```
[1,2,2].sum()
users.sum(function(user) { return user.votes; })
users.sum('votes')
```

### Response
#### Success Response (200)
- **result** (Number) - The sum of the array elements.

#### Response Example
```json
{
  "result": 5
}
```
```json
{
  "result": 150
}
```
```

--------------------------------

### Sugar.Array.setOption

Source: https://sugarjs.com/docs/index

Sets an internal option used by SugarJS Array methods, affecting behaviors like sorting.

```APIDOC
## Sugar.Array.setOption

### Description
Sets an option used internally by Array. Options listed below. Current options are for sorting strings with `sortBy`. If `value` is `null`, the default value will be restored.

### Method
Accessor

### Endpoint
`Sugar.Array.setOption(name, value)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **name** (string) - Required - The name of the option to set.
- **value** (any) - Required - The value to set for the option. Use `null` to restore the default.

### Options
- `sortIgnore`: A regex to ignore when sorting. Default is `null`.
- `sortIgnoreCase`: A boolean that ignores case when sorting. Default is `true`.
- `sortNatural`: A boolean that turns on natural sorting. Default is `true`.
- `sortOrder`: A string of characters to use as the base sort order. Default is language-specific.
- `sortEquivalents`: A table of equivalent characters used when sorting. Default is language-specific.
- `sortCollate`: The collation function used when sorting strings. Default is language-specific.

### Request Example
```javascript
Sugar.Array.setOption('sortIgnore', /^\d+\./)
Sugar.Array.setOption('sortIgnoreCase', false)
```

### Response
#### Success Response (200)
- **undefined** - This method does not return a value.

#### Response Example
```json
{
  "example": ""
}
```
```

--------------------------------

### Extend Specific Methods within a Sugar.js Module (e.g., Array)

Source: https://sugarjs.com/docs/index

This snippet shows how to extend only a select list of methods (e.g., 'first', 'last') from a specific Sugar.js module like Array. This offers granular control over method extensions.

```javascript
Sugar.Array.extend({
  methods: ['first', 'last']
});
```

--------------------------------

### Format Date with Custom String

Source: https://sugarjs.com/docs/index

Formats a date object into a string using custom format tokens. This method allows for precise control over the output string's appearance.

```javascript
today.format('{yyyy}-{MM}-{dd}');
```

--------------------------------

### Array Matching with Sugar.js - Primitives

Source: https://sugarjs.com/docs/index

Enhances native array methods like 'every', 'some', and 'findIndex' by allowing direct use of primitive values (strings, numbers, booleans) for strict equality matching.

```javascript
['a','b','c'].every('b')
```

```javascript
['a','b','c'].some('b')
```

```javascript
['a','b','c'].findIndex('b')
```

--------------------------------

### Reduce an array from right to left (Sugar.js)

Source: https://sugarjs.com/docs/index

The 'reduceRight' method functions similarly to 'reduce', but it iterates over the array elements from right to left. An optional initial value can be provided.

```javascript
[1,2,3].reduceRight(function(a, b) {
  return a - b;
});
```

--------------------------------

### Sample Array Elements with Sugar.js

Source: https://sugarjs.com/docs/index

Returns a random element or a specified number of random elements from an array. The `remove` option can be used to remove sampled elements from the original array.

```javascript
[1,2,3,4,5].sample()
```

```javascript
[1,2,3,4,5].sample(1)
```

```javascript
[1,2,3,4,5].sample(3)
```

--------------------------------

### Iterate Over Array Elements - JavaScript

Source: https://sugarjs.com/docs/index

The `forEach` method iterates through each element of an array, executing a provided callback function for each element. This method is also available as a polyfill.

```javascript
['a','b','c'].forEach(function(a) {
  // Called 3 times: 'a','b','c'
});
```

--------------------------------

### Array Matching with Sugar.js - Complex Types

Source: https://sugarjs.com/docs/index

Extends array matching to handle complex types like arrays, regular expressions, dates, and objects. Supports deep matching for arrays, regex testing, date time comparison, and fuzzy object matching.

```javascript
[[1,2],[5,6],[4,3]].findIndex([4,3])
```

```javascript
names.find(/lly$/)
```

```javascript
names.filter(/^H/)
```

```javascript
users.find({ age: 32 })
```

--------------------------------

### Group Array into N Sub-arrays with Padding (JavaScript)

Source: https://sugarjs.com/docs/index

The `inGroups` method groups an array into a specified number of sub-arrays. An optional `padding` value can be provided to ensure the last sub-array has equal length to others. This method is useful for distributing array elements evenly.

```javascript
[1,2,3,4,5,6,7].inGroups(3)
```

```javascript
[1,2,3,4,5,6,7].inGroups(3, 0)
```

--------------------------------

### Format Dates with Medium Locale in Sugar.js

Source: https://sugarjs.com/docs/index

Shows how to format a date object into a medium string representation using a specific locale. This format provides more detail than 'short' but is less verbose than 'long'.

```javascript
new Date().medium('zh-CN');
```

--------------------------------

### Disable Specific Namespace Enhancements

Source: https://sugarjs.com/docs/index

Demonstrates how to disable enhancements for a specific namespace, such as `Array`, by setting the corresponding flag (e.g., `enhanceArray`) to `false` in `Sugar.extend`. This allows other namespaces to still be enhanced.

```javascript
Sugar.extend({
  enhanceArray: false // Disallow Array enhancements
});
```

--------------------------------

### Set Internal Array Option (JavaScript)

Source: https://sugarjs.com/docs/index

The `setOption` method configures internal options for Sugar.js Array methods, particularly for sorting. Options include ignoring case, natural sorting, and custom sort orders or character equivalences.

```javascript
Sugar.Array.setOption('sortIgnore', /^\d+\./)
```

```javascript
Sugar.Array.setOption('sortIgnoreCase', false)
```

--------------------------------

### findIndex

Source: https://sugarjs.com/docs/index

Returns the index of the first element that matches the search criteria, or -1 if no match is found. Supports element search and function search.

```APIDOC
## findIndex

### Description
Returns the index of the first element in the array that matches `search`, or `-1` if none. `search` can be an array element or a function of type `searchFn`. `context` is the `this` object. Implements enhanced matching. This method is also provided as a polyfill in the ES6 module.

### Method
Instance method (called on an array instance)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
[1,2,3,4].findIndex(function(n) {
  return n % 2 == 0;
});

['a','b','c'].findIndex('c');

['cuba','japan','canada'].find(/^c/)
```

### Response
#### Success Response (200)
Number: The index of the first matching element, or -1 if no match is found.

#### Response Example
(Depends on the array content and search criteria)
```

--------------------------------

### Check if Array is Empty (JavaScript)

Source: https://sugarjs.com/docs/index

The `isEmpty` method returns `true` if the array contains no elements (i.e., its length is zero), and `false` otherwise. This is a simple utility for checking array emptiness.

```javascript
[].isEmpty()
```

```javascript
['a'].isEmpty()
```

--------------------------------

### Array.prototype.some

Source: https://sugarjs.com/docs/index

Checks if any element in the array satisfies a condition. The condition can be a value, a regular expression, or a function.

```APIDOC
## GET /websites/sugarjs/some

### Description
Returns true if `search` is true for any element in the array. `search` can be an array element or a function of type `searchFn`. `context` is the `this` object. Implements enhanced matching. This method is also provided as a polyfill in the ES5 module.

### Method
GET

### Endpoint
`/websites/sugarjs/some`

### Parameters
#### Query Parameters
- **search** (any) - Required - The value, regular expression, or function to test against array elements.
- **context** (object) - Optional - The `this` object for the search function.

### Request Example
```
['a','b','c'].some(function(n) { return n == 'a'; })
['a','b','c'].some(function(n) { return n == 'd'; })
['a','b','c'].some('a')
[{a:2},{b:5}].some({a:2})
users.some({ name: /^H/ })
```

### Response
#### Success Response (200)
- **result** (Boolean) - True if at least one element matches the search criteria, false otherwise.

#### Response Example
```json
{
  "result": true
}
```
```json
{
  "result": false
}
```
```

--------------------------------

### Shuffle Array Elements with Sugar.js

Source: https://sugarjs.com/docs/index

Returns a new array with the elements randomized using the Fisher-Yates algorithm. The original array remains unchanged.

```javascript
[1,2,3,4].shuffle()
```

--------------------------------

### Find Minimum Value Element in Array (SugarJS)

Source: https://sugarjs.com/docs/index

The `min` method returns the element with the lowest value in an array. It can map values using a function or string shortcut and return multiple elements if `all` is true. Deep properties are supported.

```javascript
[1,2,3].min()
```

```javascript
['fee','fo','fum'].min('length')
```

```javascript
['fee','fo','fum'].min(true, 'length')
```

```javascript
users.min('age')
```

```javascript
['fee','fo','fum'].min(true, function(n) {
  return n.length;
});
```

--------------------------------

### Concatenate SugarJS String chainables

Source: https://sugarjs.com/docs/index

Illustrates concatenating two SugarJS String chainable objects. The result is a combined string.

```javascript
Sugar.String('foo') + Sugar.String('bar');
```

--------------------------------

### Find First Index of Element in Array (JavaScript)

Source: https://sugarjs.com/docs/index

The `indexOf` method returns the first index at which a given element can be found in the array, or -1 if it is not present. The search can begin from a specified index. This method uses strict equality and is a polyfill.

```javascript
[1,2,3].indexOf(3)
```

```javascript
[1,2,3].indexOf(7)
```

--------------------------------

### Merge Multiple Arrays Together (JavaScript)

Source: https://sugarjs.com/docs/index

The `zip` method merges multiple arrays into a single array. Elements at the same index from each input array are grouped together. If arrays have different lengths, missing elements are filled with `null`.

```javascript
[1,2,3].zip([4,5,6])
```

--------------------------------

### Count Matching Elements in Array with Sugar.js

Source: https://sugarjs.com/docs/index

Counts all elements in an array that match a given search criterion. The search can be an element, a regular expression, or a callback function. Returns a number.

```javascript
['a','b','a'].count('a')
```

```javascript
['a','b','c'].count(/b/)
```

```javascript
users.count(function(user) {
  return user.age > 30;
});
```

--------------------------------

### Check Array Elements with Sugar.js 'some'

Source: https://sugarjs.com/docs/index

Returns true if the `search` condition is met for any element in the array. The `search` can be an element, a function, or an object for enhanced matching. A `context` can also be provided.

```javascript
['a','b','c'].some(function(n) {
  return n == 'a';
});
```

```javascript
['a','b','c'].some(function(n) {
  return n == 'd';
});
```

```javascript
['a','b','c'].some('a')
```

```javascript
[{a:2},{b:5}].some({a:2})
```

```javascript
users.some({ name: /^H/ })
```

--------------------------------

### Format Date with strftime String

Source: https://sugarjs.com/docs/index

Formats a date object into a string using strftime-like format specifiers. This provides an alternative to Sugar.js's custom tokens for date formatting.

```javascript
today.format('%Y-%m-%d');
```

--------------------------------

### Sum Array Elements with Sugar.js

Source: https://sugarjs.com/docs/index

Calculates the sum of all values in the array. An optional `map` function or string shortcut can be provided to specify which values to sum.

```javascript
[1,2,2].sum()
```

```javascript
users.sum(function(user) {
  return user.votes;
});
```

```javascript
users.sum('votes')
```

--------------------------------

### Reduce an array to a single value (Sugar.js)

Source: https://sugarjs.com/docs/index

The 'reduce' method applies a function against an accumulator and each element in the array (from left to right) to reduce it to a single value. An optional initial value can be provided.

```javascript
[1,2,3].reduce(function(a, b) {
  return a - b;
});
```

--------------------------------

### Slice Array with Sugar.js 'to'

Source: https://sugarjs.com/docs/index

Returns a new array containing elements from the beginning of the array up to (but not including) the specified `index`.

```javascript
['a','b','c'].to(1)
```

```javascript
['a','b','c'].to(2)
```

--------------------------------

### Disable All Sugar.js Enhancements

Source: https://sugarjs.com/docs/index

Shows how to disable all enhanced methods in Sugar.js by setting the `enhance` flag to `false` during the `Sugar.extend` configuration. This prevents Sugar.js from overriding built-in methods.

```javascript
Sugar.extend({
  enhance: false // Disallow all enhancements
});
```

--------------------------------

### Map Array Elements to New Values (SugarJS)

Source: https://sugarjs.com/docs/index

The `map` method transforms an array into a new array by applying a function to each element. It accepts a string shortcut for property access or function invocation and supports deep properties. This method is also available as an ES5 polyfill.

```javascript
[1,2,3].map(function(n) {
  return n * 3;
});
```

--------------------------------

### Find Index of First Element in Array - JavaScript

Source: https://sugarjs.com/docs/index

The `findIndex` method returns the index of the first element in an array that matches the search criteria, or -1 if no match is found. The search can be a value, a function, or a regular expression. This method is also available as an ES6 polyfill.

```javascript
[1,2,3,4].findIndex(function(n) {
  return n % 2 == 0;
});
```

```javascript
['a','b','c'].findIndex('c');
```

```javascript
['cuba','japan','canada'].find(/^c/)
```

--------------------------------

### Array.prototype.union

Source: https://sugarjs.com/docs/index

Returns a new array containing unique elements from both the original array and the provided array.

```APIDOC
## GET /websites/sugarjs/union

### Description
Returns a new array containing elements in both arrays with duplicates removed. In addition to primitives, this method will also deep-check objects for equality.

### Method
GET

### Endpoint
`/websites/sugarjs/union`

### Parameters
#### Query Parameters
- **arr** (Array) - Required - The array to find the union with.

### Request Example
```
[1,3,5].union([5,7,9])
['a','b'].union(['b','c'])
```

### Response
#### Success Response (200)
- **result** (Array) - A new array containing the unique elements from both arrays.

#### Response Example
```json
{
  "result": [1, 3, 5, 7, 9]
}
```
```json
{
  "result": ["a", "b", "c"]
}
```
```

--------------------------------

### Group Array Elements by Key - JavaScript

Source: https://sugarjs.com/docs/index

The `groupBy` method organizes array elements into an object based on a specified key or mapping function. An optional `groupFn` can be applied to each resulting group.

```javascript
['a','aa','aaa'].groupBy('length')
```

```javascript
users.groupBy(function(n) {
  return n.age;
});
```

--------------------------------

### Format Date with 'long' Method

Source: https://sugarjs.com/docs/index

Formats a date object into a 'long' string representation using the dedicated 'long()' method. This is equivalent to using the '{long}' token.

```javascript
jul.long();
```
Tokens:
Raw