Struct Class

Article
04/11/2014

A struct holds several values of any X++ type, to group the information about a specific entity.

Syntax

class Struct extends Object

Run On

Called

Methods

	Method	Description
	add	Adds a new item to the struct and assigns the specified value to it.
	cancelTimeOut	Cancels a previous method call to the setTimeOut method. (Inherited from Object.)
	definitionString	Returns a description of the names and types of the elements in the struct.
	equal	Determines whether the specified object is equal to the current one. (Inherited from Object.)
	exists	Determines whether a particular item exists in a struct.
	fieldName	Returns the name of the item in the struct at the specified position.
	fields	Returns the number of items in the struct.
	fieldType	Returns the data type of the item in the struct at the specified position.
	getTimeOutTimerHandle	Returns the timer handle for the object. (Inherited from Object.)
	handle	Retrieves the handle of the class of the object. (Inherited from Object.)
	index	Calculates the position of an item in the struct based on its name.
	new	Creates a struct. (Overrides the new Method.)
	notify	Releases the hold on an object that has called the wait method on this object. (Inherited from Object.)
	notifyAll	Releases a lock on the object that was issued by the wait method on this object. (Inherited from Object.)
	objectOnServer	Determines whether the object is on a server. (Inherited from Object.)
	owner	Returns the instance that owns the object. (Inherited from Object.)
	pack	Serializes the current instance of the Struct class.
	remove	Removes an item from a struct.
	setTimeOut	Sets up the scheduled execution of a specified method. (Inherited from Object.)
	toString	Returns a string that describes the contents of the struct. (Overrides the toString Method.)
	usageCount	Returns the current number of references, that is, the value of the reference counter, that the object has. (Inherited from Object.)
	value	Gets or sets the value for a specified item in a struct.
	valueImage	Returns a string that describes the value of the item at a particular position in the struct.
	valueIndex	Gets or sets the value of the item at a specified position in a struct.
	wait	Pauses a process. (Inherited from Object.)
	xml	Returns an XML string that represents the current object. (Overrides the xml Method.)
	::create	Creates a struct from a container that is obtained from a prior call to Struct.pack.
	::createFromXML
	::equal	Determines whether two structs are equal.
	::merge	Combines two structs to create a new struct.

Top

Remarks

A struct (short for structure) is an entity that can hold several values of any X++ type. Structs are used to group information about a specific entity. For example, you might want to store information about a customer's name, age and address and then treat this compound information as one item.

The items in a struct are specified by a data type and a name. Items are added when the struct is created by using the new method, or they are created after the struct has been created by using the add method. If you add an item by using the add method, you specify the value for the item at the same time, and the data type is inferred from this value. If you add an item during the instantiation of the struct, you need to use the value or the valueIndex method to assign a value to it.

The items in a struct can be of any of the data types found in the Types system enum, including: string, integer, real, date, container, record, and class.

The items in a struct are arranged in alphabetical order of the item names.

The fields in a struct can be traversed by using the fields, fieldName, and fieldType methods. Structs can be packed into containers and later restored by using the Struct::create method.

Structs have some similarities to X++ containers. However, a container is a value type and is built into the X++ language. You can create nested containers, but you cannot create nested structs.

X++ classes can store information in much the same way as structs. But although classes can supply methods to manipulate the data, no such facility is provided for structs, and there is no concept of overriding or extension. Classes can only be created in the AOT, but structs exist solely in the context of the code in which they are created. Class member variables are private to the class, so accessor functions must be coded for them for the values to be used from outside the class. The items within a struct are publicly accessible.

Examples

The following example creates a struct with two items and then assigns values to those items. A new item is then added by using the Struct.add method; the data type of the item is inferred from the value assigned to it. The struct is then packed into a container and used to create a new struct, a copy of the original struct.

{ 
    Struct s = new struct ("int age; str name"); 
    Struct copy; 
    container c; 
    int i; 
     
    // Add values to the items 
    s.value("age", 25); 
    s.value("name", "Jane Dow"); 
  
  // Add a new item; data type is inferred from value 
    s.add("Shoesize", 45); 
  
    // Print the definition of the struct 
    print s.definitionString(); 
  
    // Prints the type and name of all items in the struct 
    for (i =  1;   i <= s.fields();i++) 
    { 
         print s.fieldType(i), " ", s.fieldName(i); 
    }  
  
    // Pack the struct into a container and restore it into copy 
    c = s.pack(); 
    copy = Struct::create(c); 
    print copy.definitionString(); 
    pause; 
}

Inheritance Hierarchy

Object Class
Struct Class

Share via