Package ortus.boxlang.runtime.types

Class Struct

java.lang.Object
ortus.boxlang.runtime.types.Struct
All Implemented Interfaces:
Serializable, Map<Key,Object>, IReferenceable, IStruct, IType, IListenable
Direct Known Subclasses:
BaseScope, ImmutableStruct
public class Struct extends Object implements IStruct, IListenable, Serializable
This type provides the core map class for Boxlang. Structs are highly versatile and are used for organizing and managing related data. Types of Structs in BoxLang: * Basic Structs: These are the basic structures where each key is associated with a single value. Keys are case-insensitive and can be strings or symbols. * Nested Structs: Structs can contain other structs as values, allowing for a hierarchical organization of data. * Case-Sensitive Structs: By default, BoxLang structs are case-insensitive. However, you can create case-sensitive structs if needed. * Ordered Structs: This implementation of a Struct maintains keys in the order they were added. * Sorted Structs: This implementation of a Struct maintains keys in specified sorted order.
See Also:

  • Field Details

    • KEY_LENGTH_LONGEST_FIRST_COMPARATOR

      public static final Comparator<Key> KEY_LENGTH_LONGEST_FIRST_COMPARATOR
      A pre-made comparator to use with a sorted struct to sort longest keys first, and shortest last

    • EMPTY

      public static final IStruct EMPTY
      An immutable singleton empty struct

    • $bx

      public BoxMeta $bx
      Metadata object

    • wrapped

      protected final Map<Key,Object> wrapped
      The wrapped map used in the implementation

    • INITIAL_CAPACITY

      protected static final int INITIAL_CAPACITY
      In general, a common approach is to choose an initial capacity that is a power of two. For example, 16, 32, 64, etc. This is because ConcurrentHashMap uses power-of-two-sized hash tables, and using a power-of-two capacity can lead to better distribution of elements in the table.
      See Also:

  • Constructor Details

    • Struct

      public Struct(IStruct.TYPES type)
      Constructor
      Parameters:
      type - The type of struct to create: DEFAULT, LINKED, SORTED
      Throws:
      BoxRuntimeException - If an invalid type is specified: DEFAULT, LINKED, SORTED

    • Struct

      public Struct()
      Create a default struct

    • Struct

      public Struct(Comparator<Key> comparator)
      Create a sorted struct with the passed object
      Parameters:
      comparator - The comparator to use

    • Struct

      public Struct(Map<Key,Object> map, IStruct.TYPES type)
      Construct a struct from a map. This wraps the original map. Use the Struct( Type type, Map<? extends Object, ? extends Object> map ) method and supply an explicit type to have this struct created with a copy of all the keys/values in your map.
      Parameters:
      map - The map to create the struct from
      type - The type of struct to create: DEFAULT, LINKED, SORTED

    • Struct

      public Struct(Map<? extends Object,? extends Object> map)
      Construct a struct from the keys/values in your map.
      Parameters:
      map - The map to create the struct from

    • Struct

      public Struct(IStruct.TYPES type, Map<? extends Object,? extends Object> map)
      Construct a struct of a specific type from an existing map
      Parameters:
      type - The type of struct to create: DEFAULT, LINKED, SORTED
      map - The map to create the struct from

  • Method Details

    • fromMap

      public static IStruct fromMap(Map<? extends Object,? extends Object> map)
      Static helper to create a struct from an existing map
      Parameters:
      map - The map to create the struct from
      Returns:
      The struct created from the map

    • fromMap

      public static IStruct fromMap(IStruct.TYPES type, Map<Object,Object> map)
      Static helper to construct a struct of a specific type and an existing map
      Parameters:
      type - The type of struct to create: DEFAULT, LINKED, SORTED
      map - The map to create the struct from
      Returns:
      The struct created from the map with the specified type

    • of

      public static IStruct of(Object... values)
      Create a struct from a list of values. The values must be in pairs, key, value, key, value, etc.
      Parameters:
      values - The values to create the struct from
      Returns:
      The struct

    • linkedOf

      public static IStruct linkedOf(Object... values)
      Create a linked struct from a list of values. The values must be in pairs, key, value, key, value, etc.
      Parameters:
      values - The values to create the struct from
      Returns:
      The linked struct

    • sortedOf

      public static IStruct sortedOf(Comparator<Key> comparator, Object... values)
      Create a sorted struct from a list of values and the passed comparator. The values must be in pairs, key, value, key, value, etc.
      Parameters:
      comparator - The comparator to use
      values - The values to create the struct from
      Returns:
      The sorted struct

    • sortedOf

      public static IStruct sortedOf(Comparator<Key> comparator, Map<Key,Object> map)
      Create a sorted struct from an existing map.
      Parameters:
      comparator - The comparator to use
      map - An existing map to create the sorted struct from
      Returns:
      The sorted struct

    • size

      public int size()
      Returns the number of key-value mappings in this map. If the map contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.
      Specified by:
      size in interface Map<Key,Object>
      Returns:
      the number of key-value mappings in this map

    • isEmpty

      public boolean isEmpty()
      Returns true if this map contains no key-value mappings.
      Specified by:
      isEmpty in interface Map<Key,Object>

    • containsKey

      public boolean containsKey(Key key)
      Returns true if this map contains a mapping for the specified Key
      Specified by:
      containsKey in interface IStruct
      Parameters:
      key - key whose presence in this map is to be tested
      Returns:
      true if this map contains a mapping for the specified

    • containsKey

      public boolean containsKey(Object key)
      Returns true if this map contains a mapping for the specified Key
      Specified by:
      containsKey in interface Map<Key,Object>
      Parameters:
      key - key whose presence in this map is to be tested
      Returns:
      true if this map contains a mapping for the specified

    • containsKey

      public boolean containsKey(String key)
      Returns true if this map maps one or more keys using a String key
      Specified by:
      containsKey in interface IStruct
      Parameters:
      key - The string key to look for. Automatically converted to Key object
      Returns:
      true if this map contains a mapping for the specified

    • containsValue

      public boolean containsValue(Object value)
      Returns true if this map maps has the specified value
      Specified by:
      containsValue in interface Map<Key,Object>
      Parameters:
      value - value whose presence in this map is to be tested
      Returns:
      true if this map contains a mapping for the specified value

    • get

      public Object get(Object key)
      Returns the value to which the specified Key is mapped
      Specified by:
      get in interface Map<Key,Object>
      Parameters:
      key - the key whose associated value is to be returned
      Returns:
      the value to which the specified key is mapped or null if not found

    • get

      public Object get(String key)
      Returns the value to which the specified Key is mapped
      Specified by:
      get in interface IStruct
      Parameters:
      key - the key whose associated value is to be returned
      Returns:
      the value to which the specified key is mapped or null if not found

    • getOrDefault

      public Object getOrDefault(Key key, Object defaultValue)
      Get key, with default value if not found
      Specified by:
      getOrDefault in interface IStruct
      Parameters:
      key - The key to look for
      defaultValue - The default value to return if the key is not found
      Returns:
      The value of the key

    • getOrDefault

      public Object getOrDefault(String key, Object defaultValue)
      Get key, with default value if not found
      Specified by:
      getOrDefault in interface IStruct
      Parameters:
      key - The key to look for
      defaultValue - The default value to return if the key is not found
      Returns:
      The value of the key

    • getRaw

      public Object getRaw(Key key)
      Returns the value of the key safely, nulls will be wrapped in a NullValue still.
      Specified by:
      getRaw in interface IStruct
      Parameters:
      key - The key to look for
      Returns:
      The value of the key or a NullValue object, null means the key didn't exist *

    • put

      public Object put(Key key, Object value)
      Set a value in the struct by a Key object
      Specified by:
      put in interface IStruct
      Specified by:
      put in interface Map<Key,Object>
      Parameters:
      key - The key to set
      value - The value to set
      Returns:
      The previous value of the key, or null if not found

    • put

      public Object put(String key, Object value)
      Set a value in the struct by a string key, which we auto-convert to a Key object
      Specified by:
      put in interface IStruct
      Parameters:
      key - The string key to set
      value - The value to set
      Returns:
      The previous value of the key, or null if not found

    • putIfAbsent

      public Object putIfAbsent(Key key, Object value)
      Put a value in the struct if the key doesn't exist
      Specified by:
      putIfAbsent in interface IStruct
      Specified by:
      putIfAbsent in interface Map<Key,Object>
      Parameters:
      key - The key to set
      value - The value to set
      Returns:
      The previous value of the key, or null if not found

    • putIfAbsent

      public Object putIfAbsent(String key, Object value)
      Put a value in the struct if the key doesn't exist
      Specified by:
      putIfAbsent in interface IStruct
      Parameters:
      key - The String key to set
      value - The value to set
      Returns:
      The previous value of the key, or null if not found

    • remove

      public Object remove(Object key)
      Remove a value from the struct by a Key object
      Specified by:
      remove in interface Map<Key,Object>
      Parameters:
      key - The key to remove

    • remove

      public Object remove(String key)
      Remove a value from the struct by a Key object
      Specified by:
      remove in interface IStruct
      Parameters:
      key - The String key to remove

    • remove

      public Object remove(Key key)
      Remove a value from the struct by a Key object
      Specified by:
      remove in interface IStruct
      Parameters:
      key - The String key to remove

    • putAll

      public void putAll(Map<? extends Key,? extends Object> map)
      Copies all of the mappings from the specified map to this map (optional operation). It expects the specific key and object generics.
      Specified by:
      putAll in interface Map<Key,Object>

    • addAll

      public void addAll(Map<? extends Object,? extends Object> map)
      Copies all of the mappings from the specified map to this map (optional operation). This method will automatically convert the keys to Key objects
      Specified by:
      addAll in interface IStruct
      Parameters:
      map -

    • clear

      public void clear()
      Removes all of the mappings from this map (optional operation).
      Specified by:
      clear in interface Map<Key,Object>

    • keySet

      public Set<Key> keySet()
      Returns a Set view of the keys contained in this map.
      Specified by:
      keySet in interface Map<Key,Object>

    • values

      public Collection<Object> values()
      Returns a Collection view of the values contained in this map.
      Specified by:
      values in interface Map<Key,Object>

    • entrySet

      public Set<Map.Entry<Key,Object>> entrySet()
      Returns a Set view of the mappings contained in this map.
      Specified by:
      entrySet in interface IStruct
      Specified by:
      entrySet in interface Map<Key,Object>

    • equals

      public boolean equals(Object obj)
      Verifies equality with the following rules: - Same object - Super class
      Specified by:
      equals in interface Map<Key,Object>
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Struct Hashcode
      Specified by:
      hashCode in interface Map<Key,Object>
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Convert the struct to a human-readable string, usually great for debugging Remember structs have no order except their internal hash code
      Overrides:
      toString in class Object
      Returns:
      The string representation of the struct using the format {key=value, key=value}

    • toStringWithCase

      public String toStringWithCase()
      Convert the struct to a human-readable string, usually great for debugging Remember structs have no order except their internal hash code
      Specified by:
      toStringWithCase in interface IStruct
      Returns:
      The string representation of the struct using the format {key=value, key=value}

    • asString

      public String asString()
      Represent as string, or throw exception if not possible
      Specified by:
      asString in interface IType
      Returns:
      The string representation

    • getBoxMeta

      public BoxMeta getBoxMeta()
      Get the BoxMetadata object for this struct
      Specified by:
      getBoxMeta in interface IType
      Returns:
      The object for this struct

    • getType

      public IStruct.TYPES getType()
      Get the type of struct
      Specified by:
      getType in interface IStruct
      Returns:
      The type of struct according to the enum

    • isCaseSensitive

      public Boolean isCaseSensitive()
      Returns a boolean as to whether the struct instance is case sensitive
      Specified by:
      isCaseSensitive in interface IStruct

    • isSoftReferenced

      public Boolean isSoftReferenced()
      Returns a boolean as to whether this is a soft-referenced struct
      Specified by:
      isSoftReferenced in interface IStruct

    • toImmutable

      public ImmutableStruct toImmutable()
      Helper to make the struct immutable

    • assign

      public Object assign(IBoxContext context, Key key, Object value)
      Assign a value to a key
      Specified by:
      assign in interface IReferenceable
      Parameters:
      context - The context we're executing inside of
      key - The key to assign
      value - The value to assign
      Returns:
      The value that was assigned

    • dereference

      public Object dereference(IBoxContext context, Key key, Boolean safe)
      Dereference this object by a key and return the value, or throw exception
      Specified by:
      dereference in interface IReferenceable
      Parameters:
      context - The context we're executing inside of
      key - The key to dereference
      safe - Whether to throw an exception if the key is not found
      Returns:
      The requested object

    • dereferenceAndInvoke

      public Object dereferenceAndInvoke(IBoxContext context, Key name, Object[] positionalArguments, Boolean safe)
      Dereference this object by a key and invoke the result as an invokable (UDF, java method) using positional arguments
      Specified by:
      dereferenceAndInvoke in interface IReferenceable
      Parameters:
      context - The context we're executing inside of
      name - The key to dereference
      positionalArguments - The positional arguments to pass to the invokable
      safe - Whether to throw an exception if the key is not found
      Returns:
      The requested object

    • dereferenceAndInvoke

      public Object dereferenceAndInvoke(IBoxContext context, Key name, Map<Key,Object> namedArguments, Boolean safe)
      Dereference this object by a key and invoke the result as an invokable (UDF, java method)
      Specified by:
      dereferenceAndInvoke in interface IReferenceable
      Parameters:
      context - The context we're executing inside of
      name - The name of the key to dereference, which becomes the method name
      namedArguments - The arguments to pass to the invokable
      safe - If true, return null if the method is not found, otherwise throw an exception
      Returns:
      The requested return value or null

    • getFunctionContextThisClassForInvoke

      public IClassRunnable getFunctionContextThisClassForInvoke()

    • getFunctionContextThisInterfaceForInvoke

      public BoxInterface getFunctionContextThisInterfaceForInvoke()

    • wrapNull

      public Object wrapNull(Object value)
      Wrap null values in an instance of the NullValue class
      Parameters:
      value - The value to wrap
      Returns:
      The wrapped value

    • wrapAssignment

      public Object wrapAssignment(Object value)
      Wraps the assignment value
      Parameters:
      value - The object to wrap ( or not )

    • getKeys

      public List<Key> getKeys()
      Get an array list of all the keys in the struct
      Specified by:
      getKeys in interface IStruct
      Returns:
      An array list of all the keys in the struct

    • getKeysAsStrings

      public List<String> getKeysAsStrings()
      Get an array list of all the keys in the struct
      Specified by:
      getKeysAsStrings in interface IStruct
      Returns:
      An array list of all the keys in the struct

    • unWrapNull

      public static Object unWrapNull(Object value)
      Unwrap null values from the NullValue class
      Parameters:
      value - The value to unwrap
      Returns:
      The unwrapped value which can be null

    • getWrapped

      public Map<Key,Object> getWrapped()
      Get the wrapped map used in the implementation
      Specified by:
      getWrapped in interface IStruct

    • registerChangeListener

      public void registerChangeListener(IChangeListener listener)
      -------------------------------------------------------------------------- IListenable Interface Methods --------------------------------------------------------------------------
      Specified by:
      registerChangeListener in interface IListenable

    • registerChangeListener

      public void registerChangeListener(Key key, IChangeListener listener)
      Specified by:
      registerChangeListener in interface IListenable

    • removeChangeListener

      public void removeChangeListener(Key key)
      Specified by:
      removeChangeListener in interface IListenable