Pev: /* GetNamedTagAsInt */ error correction

2011-05-03T10:49:08Z

GetNamedTagAsInt: error correction

← Older revision		Revision as of 10:49, 3 May 2011
Line 186:		Line 186:
	;Syntax		;Syntax
	int count = soup.GetNamedTagAsInt("count");		int count = soup.GetNamedTagAsInt("count");
	int count = soup.~~GetNamedTagAsBool~~("count", 25);		int count = soup.GetNamedTagAsInt("count", 25);

	;Notes		;Notes

Windwalkr at 16:22, 9 February 2010

2010-02-09T16:22:40Z

← Older revision		Revision as of 16:22, 9 February 2010
Line 1:		Line 1:
	*[[TrainzScript ~~Langage~~ Reference\|API Hierarchy]]		*[[TrainzScript Language Reference\|API Hierarchy]]
	**[[Class GSObject\|GSObject]]		**[[Class GSObject\|GSObject]]
	***Soup		***Soup

Windwalkr: 1 revision

2010-02-03T13:58:40Z

1 revision

← Older revision	Revision as of 13:58, 3 February 2010
(No difference)

Andi06: format fixes

2009-04-24T01:25:52Z

format fixes

New page

*[[TrainzScript Langage Reference|API Hierarchy]]
**[[Class GSObject|GSObject]]
***Soup
 

A Soup object is the script interface to data stored in the [[ACS Text Format]], such as [[config.txt file]]s. Soups are used in various places within Trainz as a way to load and save data, such as property settings.
*Soups can save items which can be represented as boolean values, floating point numbers, integers, strings, KUID references or nested SubSoups.
*All data items are saved in key-value pairs and saved information can be stored or retrieved by referring to the name (unique key) of the data item.
*Soups are used by calls to ''GetProperties()'' and ''SetProperties()'' as a mechanism for saving object data to the session and retrieving it on a subsequent load.
*It is possible in some cases to save data as one data type and retrieve it as another.
*Soups descend directly from GSObject enabling them to be passed as parameters to script libraries.
*A Soup object, with four simple tags and a nested SubSoup might be represented thus:
forename "Gordon"
surname "Bennett"
married 0
height 1.65
address {
0 "1 High Street"
1 "Southend"
2 "Essex"
}
*A new Soup can be created using Constructors.NewSoup() or as a result of method calls:
Soup soup = Constructors.NewSoup(); // this soup will be empty
Soup soup = GetAsset().GetConfigSoup(); // this will contain the contents of ''config.txt'' in ''Soup'' format.
 

==Clear==
{{MethodHeader|public native void Clear(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
soup.Clear();
;Notes
*Deletes all tags and values leaving an empty Soup.
 

==Copy==
{{MethodHeader|public native void Copy(Soup value)}}
;Parameters
*'''value''' = Soup to copy from.
;Returned Value
*None
;Syntax
Soup source;
Soup destination;
destination.Copy(source);
;Notes
*Clears ''destination'' and copies all tags from ''source'' creating a duplicate of the original Soup.
 

==CountTags==
{{MethodHeader|public native int CountTags(void)}}
;Parameters
*None
;Returned Value
*The total number of tags found at the highest level of the Soup being queried. Nested SubSoups are counted as one tag.
;Syntax
int items = soup.CountTags();
;Notes
*Note that since a call to ''[[#GetNamedSoup|GetNamedSoup()]]'' will always return a valid Soup object, the use of CountTags() is in some circumstances, necessary to establish whether or not a Soup object actually contains data.
GetAsset().GetConfigSoup().GetNamedSoup("extensions") // always returns true
GetAsset().GetConfigSoup().GetNamedSoup("extensions").CountTags() // returns true only if there is data present
 

==GetIndexedTagName==
{{MethodHeader|public native string GetIndexedTagName(int index)}}
;Parameters
*'''index''' = Integer denoting the tag to search for.
;Returned Value
*The tag name of the indexth tag in the database.
*Index must be in the range 0 .. soup.CountTags() - 1
;Syntax
string tagname = soup.GetIndexedTagName(1);
;Notes
*Tag ordering is arbitrary; the Soup is neither guaranteed to be order-preserving nor sorted.
*Remember that the value returned may be a SubSoup.
soup1: zero "1 High Street"
one "Southend"
two "Essex"

string result = soup1.GetNamedTag(soup1.GetIndexedTagName(1)); // returns "Southend"

soup1.GetIndexedTagName(1) would return "one" 

==GetIndexForNamedTag==
{{MethodHeader|public native int GetIndexForNamedTag(string name)}}
;Parameters
*'''name''' = Tag name to search for.
;Returned Value
*The zero based index of the position of the tag name at the highest level of the database.
*If the named tag is not present the method returns -1.
;Syntax
int index = soup.GetIndexForNamedTag("one");
;Notes
soup1: zero "1 High Street"
one "Southend"
two "Essex"

string result = soup1.GetIndexForNamedTag("one"); // returns 1
 

==GetNamedSoup==
{{MethodHeader|public native Soup GetNamedSoup(string name)}}
;Parameters
*'''name''' = name of SubSoup to retrieve
;Returned Value
*The named SubSoup, which will be created if it does not exist
*This method always returns a Soup object
;Syntax
Soup table = soup.GetNamedSoup("table");
;Notes
*[[#CountTags|CountTags()]] can be used to establish whether or not the returned Soup has any data.
Soup soup = GetAsset().GetConfigSoup().GetNamedSoup("Not Present"); // always returns true
if (soup and soup.CountTags() > 0) // returns false if soup is empty

soup1: forename "Gordon"
surname "Bennett"
married 0
height 1.65
address {
0 "1 High Street"
1 "Southend"
2 "Essex"
}

Soup address = soup.GetNamedSoup("address");

returns 0 "1 High Street"
1 "Southend"
2 "Essex"
 

==GetNamedTag==
{{MethodHeader|public native string GetNamedTag(string name)}}
;Parameters
*'''name''' = name of tag from which data is required.
;Returned Value
*String value associated with the name parameter.
*If the tag does not exist an empty string is returned.
;Syntax
string value = soup.GetNamedTag("tagName");
;Notes
soup1: forename "Gordon"
surname "Bennett"

string data = soup1.GetNamedTag("surname"); // returns "Bennett"
 

==GetNamedTagAsBool==
{{MethodHeader|public native bool GetNamedTagAsBool(string name) public native bool GetNamedTagAsBool(string name, bool default)}}
;Parameters
*'''name''' = name of tag from which data is required.
;Returned Value
*Boolean value associated with the ''name'' parameter.
;Syntax
bool found = soup.GetNamedTagAsBool("tagName");
bool found = soup.GetNamedTagAsBool("tagName", true);

;Notes
*For the first variant if the tag does not exist ''false'' is returned.
*For the second variant if the tag does not exist it will be created and assigned the value of ''default''.
*In this case ''default'' will be returned by the method.
 

==GetNamedTagAsFloat==
{{MethodHeader|public native float GetNamedTagAsFloat(string name) public native float GetNamedTagAsFloat(string name, float defaultValue)}}
;Parameters
*'''name''' = name of tag from which data is required.
*'''defaultValue''' = value to return if the tag is undefined.
;Returned Value
*Float value associated with the ''name'' parameter
*If the tag does not exist defaultValue will be returned, or 0.00 for the first variant.
;Syntax
float speed = soup.GetNamedTagAsFloat("speed")
;Notes
 

==GetNamedTagAsInt==
{{MethodHeader|public native int GetNamedTagAsInt(string name) public native int GetNamedTagAsInt(string name, int default)}}
;Parameters
*'''name''' = name of tag from which data is required.
;Returned Value
*Integer value associated with the ''name'' parameter.
;Syntax
int count = soup.GetNamedTagAsInt("count");
int count = soup.GetNamedTagAsBool("count", 25);

;Notes
*For the first variant if the tag does not exist 0 is returned.
*For the second variant if the tag does not exist it will be created and assigned the value of ''default''.
*In this case ''default'' will be returned by the method.
 

==GetNamedTagAsKUID==
{{MethodHeader|public native KUID GetNamedTagAsKUID(string name)}}
;Parameters
*'''name''' = name of tag from which data is required.
;Returned Value
*KUID reference associated with the name parameter.
*if the tag does not exist null is returned.
;Syntax
KUID kuid = soup.GetNamedTagAsKUID("kuidValue");
;Notes
*[[#SetNamedTag|SetNamedTag()]] can write a KUID in string format for retrieval by this method.
 

==IsLocked==
{{MethodHeader|public native bool IsLocked(void)}}
;Parameters
*None
;Returned Value
*Boolean value indicating whether data can be written to the Soup.
;Syntax
bool canWriteData = !soup.IsLocked();
;Notes
*Config.txt data returned by [[Asset#GetConfigSoup|GetConfigSoup()]] is always read-only
*Attempting to write data to a locked soup will cause an exception with the message "parent soup is locked"
*It is not possible to write directly to a nested soup.
To update a sub soup:

soup1: forename "Gordon"
surname "Bennett"
married 0
height 1.65
address {
0 "1 High Street"
1 "Southend"
2 "Essex"
}

Soup subSoup = soup.GetNamedSoup("address"); // copy the sub soup data to a temporary soup
subSoup.SetNamedTag(3,"SS2 3PX"); // add a new tag
soup.SetNamedSoup("address",subSoup); // write the amended sub soup back to its parent

result: data: forename "Gordon"
surname "Bennett"
married 0
height 1.65
address {
0 "1 High Street"
1 "Southend"
2 "Essex"
3 "SS2 3PX"
}
 

==RemoveNamedTag==
{{MethodHeader|public native void RemoveNamedTag(string name)}}
;Parameters
*'''name''' = name of tag to delete.
;Returned Value
*None
;Syntax
soup.RemoveNamedTag("address");
;Notes
*Deletes the named tag and its associated value.
*If the tag references a sub soup the entire soup will be removed.
 

==SetNamedSoup==
{{MethodHeader|public native void SetNamedSoup(string name, Soup value)}}
;Parameters
*'''name''' = name of subsoup tag to assign.
*'''value''' = Soup data to write to this tag
;Returned Value
*None
;Syntax
soup1.SetNamedSoup("address",soup2);
;Notes
*Creates a new database tag and writes ''value'' to it as a new sub soup.
*If the tag already exists it will be updated.
soup1: forename "Gordon"
surname "Bennett"
married 0
height 1.65

soup2: address {
0 "1 High Street"
1 "Southend"
2 "Essex"
}

soup1.SetNamedSoup("address",soup2); // write the sub soup data to the address tag

result: forename "Gordon"
surname "Bennett"
married 0
height 1.65
address {
0 "1 High Street"
1 "Southend"
2 "Essex"
}
 

==SetNamedTag==
{{MethodHeader|public void SetNamedTag(string name, bool value) public void SetNamedTag(string name, float value) public void SetNamedTag(string name, int value) public void SetNamedTag(string name, KUID value) public void SetNamedTag(string name, string value)
}}
;Parameters
*'''name''' = tag name to assign a value to.
*'''value''' = data to assign to tag, this can be of type bool, float, int KUID or string.
;Returned Value
*None
;Syntax
soup.SetNamedTag("index",1);
soup.SetNamedTag("open",true);
soup.SetNamedTag("myKUID","<KUID:1234:5678>");
;Notes
*The tag value is created if it does not already exist and overwritten otherwise
*KUIDs may be entered as strings or as KUID references.
 

==Code Examples==
{{MethodHeader|Soup to Array Conversion}}
*Soups cannot directly store Array types but conversion between Arrays and Soups is fairly straightforward.
*Similar code can be used for other array types as long as the Soup class supports the base type of the array.
*Lists of GameObjects can be saved by reference to their session name, using GameObject.GetName(), or if the list is needed during the current session only, by referencing their ID using GameObject.GetId().
Soup IntArrayToSoup(int[] numbers) {
int i;
Soup soup = Constructors.NewSoup();
for (i = 0; i < numbers.size(); i++) {
soup.SetNamedTag(i,numbers[i]);
}
return soup;
}

int[] SoupToIntArray(Soup soup) { // any non integer values will be saved as zero
int i;
int[] numbers = new int[0];
for (i = 0; i < soup.CountTags(); i++) {
string tag = soup.GetIndexedTagName(i);
numbers[numbers.size()] = soup.GetNamedTagAsInt(tag);
}
return numbers;
}
 

==Related Methods==

[[class Asset#GetConfigSoup|Asset.GetConfigSoup()]] 
[[Class Constructors#NewSoup|Constructors.NewSoup()]] 
[[class PropertyObject#GetProperties|PropertyObject.GetProperties()]] 
[[class PropertyObject#SetProperties|PropertyObject.SetProperties()]] 
 

==Categories==
[[Category:Script Class]]

Class Soup - Revision history

Pev: /* GetNamedTagAsInt */ error correction

Windwalkr at 16:22, 9 February 2010

Windwalkr: 1 revision

Andi06: format fixes