Extensions

View source
ceramic.Extensions (Class)

A collection of static extension methods for common data types.

Extensions provides utility methods that enhance standard Haxe types with performance optimizations, convenience methods, and cross-platform compatibility helpers. These methods are designed to be used with Haxe's "using" syntax for cleaner code.

Categories

  • Array Extensions: Performance-optimized array operations
  • String Extensions: String manipulation utilities
  • Map Extensions: Enhanced map operations
  • Type Extensions: Type checking and conversion

Usage Example 

using ceramic.Extensions;

// Array extensions
var arr = [1, 2, 3, 4, 5];
arr.shuffle();
var random = arr.randomElement();
var value = arr.unsafeGet(0); // Fast access

// String extensions
var str = "  hello world  ";
var trimmed = str.trim();
var title = str.toTitleCase();

Performance Notes

  • unsafeGet/Set methods bypass bounds checking for speed
  • Native array operations are used on C++ when available
  • Debug builds can enable bounds checking with ceramic_debug_unsafe
See: Type-specific extension methods throughout the class

Static Members

unsafeGet(array: Array<unsafeGet.T>, index: Int): unsafeGet.T

Gets an array element without bounds checking for maximum performance.

This method provides the fastest possible array access by bypassing runtime bounds checking. Use only when you're certain the index is valid.

Name Type Description
array Array<unsafeGet.T> The array to access
index Int The index to retrieve (must be 0 <= index < array.length)
Returns Description
unsafeGet.T The element at the specified index
unsafeSet(array: Array<unsafeSet.T>, index: Int, value: unsafeSet.T): Void

Sets an array element without bounds checking for maximum performance.

This method provides the fastest possible array mutation by bypassing runtime bounds checking. Use only when you're certain the index is valid.

Name Type Description
array Array<unsafeSet.T> The array to modify
index Int The index to set (must be 0 <= index < array.length)
value unsafeSet.T The value to set at the index
setArrayLength(array: Array<setArrayLength.T>, length: Int): Void

Efficiently resizes an array to the specified length.

Platform-optimized array resizing that either truncates or extends the array. When extending, new positions contain null/undefined values.

Name Type Description
array Array<setArrayLength.T> The array to resize
length Int The new length (can be larger or smaller) * haxe var arr = [1, 2, 3, 4, 5]; arr.setArrayLength(3); // [1, 2, 3] arr.setArrayLength(5); // [1, 2, 3, null, null]
randomElement(array: Array<randomElement.T>): randomElement.T

Returns a random element from the array.

Uses Math.random() to select an element with uniform distribution. For empty arrays, this will return undefined/null.

Name Type Description
array Array<randomElement.T> The array to select from
Returns Description
randomElement.T A random element from the array * haxe var colors = ["red", "green", "blue"]; var randomColor = colors.randomElement(); // e.g., "green"
randomElementExcept(array: Array<randomElementExcept.T>, except: randomElementExcept.T, ?unsafe: Bool = false): randomElementExcept.T

Return a random element contained in the given array that is not equal to the except arg.

Name Type Default Description
array Array<randomElementExcept.T> The array in which we extract the element from
except randomElementExcept.T The element we don't want
unsafe Bool false If set to true, will prevent allocating a new array (and may be faster) but will loop forever if there is no element except the one we don't want
Returns Description
randomElementExcept.T The random element or null if nothing was found
randomElementMatchingValidator(array: Array<randomElementMatchingValidator.T>, validator: Function): randomElementMatchingValidator.T

Return a random element contained in the given array that is validated by the provided validator. If no item is valid, returns null.

Name Type Description
array Array<randomElementMatchingValidator.T> The array in which we extract the element from
validator Function A function that returns true if the item is valid, false if not
Returns Description
randomElementMatchingValidator.T The random element or null if nothing was found
shuffle(arr: Array<shuffle.T>): Void

Shuffles an array in place using the Fisher-Yates algorithm.

This operation modifies the original array, randomizing the order of all elements with uniform distribution. Each permutation has equal probability.

See: https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle
Name Type Description
arr Array<shuffle.T> The array to shuffle (modified in place) * haxe var deck = [1, 2, 3, 4, 5]; deck.shuffle(); trace(deck); // e.g., [3, 1, 5, 2, 4] *
swapElements(arr: Array<swapElements.T>, index0: Int, index1: Int): Void
Name Type
arr Array<swapElements.T>
index0 Int
index1 Int
removeNullElements(arr: Array<removeNullElements.T>): Void
Name Type
arr Array<removeNullElements.T>