Tekla Open API

Detailed and full API reference helps you master Tekla Open API

This is the most recent version of Tekla Open API.
For older versions, please visit Tekla Warehouse.

Distance Structure

The Distance datatype.

Namespace:  Tekla.Structures.Datatype
Assembly:  Tekla.Structures.Datatype (in Tekla.Structures.Datatype.dll) Version: 2019.0.0.0 (2019.0.0.0)
Syntax
[SerializableAttribute]
[TypeConverterAttribute(typeof(DistanceConverter))]
public struct Distance : IXmlSerializable, IEquatable<Distance>, 
	IComparable<Distance>, IDoubleDataType, IDataType, IFormattable

The Distance type exposes the following members.

Constructors
  Name Description
Public methodCode example Distance(Double)
Initializes a new instance of the structure.
Public methodCode example Distance(Double, DistanceUnitType)
Initializes a new instance of the structure.
Top
Properties
  Name Description
Public propertyStatic memberCode example CurrentUnitType
Gets or sets the current unit type.
Public propertyCode example Millimeters
Gets or sets the distance in millimeters.
Public propertyStatic memberCode example UseFractionalFormat
Gets or sets a boolean value indicating whether to use the fractional format for US imperial units.
Public propertyStatic memberCode example UseUnitsInDecimalString
Gets or sets a boolean value indicating whether to use units in the decimal string representation.
Public propertyCode example Value
Gets or sets the distance value in current units.
Top
Methods
  Name Description
Public method CompareTo
Compares the current object with another object of the same type.
Public methodCode example ConvertTo
Converts the distance to the specified units.
Public method Equals(Object)
Indicates whether the current instance and the specified object are equal.
(Overrides ValueTypeEquals(Object).)
Public method Equals(Distance)
Indicates whether the current object is equal to another object of the same type.
Public methodStatic memberCode example FromDecimalString(String)
Creates a distance from a decimal string representation.
Public methodStatic memberCode example FromDecimalString(String, IFormatProvider)
Creates a distance from a decimal string representation.
Public methodStatic memberCode example FromDecimalString(String, IFormatProvider, DistanceUnitType)
Creates a distance from a decimal string representation.
Public methodStatic memberCode example FromFractionalFeetAndInchesString(String)
Creates a distance from a string representation of fractional feet and inches.
Public methodStatic memberCode example FromFractionalFeetAndInchesString(String, IFormatProvider, DistanceUnitType)
Creates a distance from a string representation of fractional feet and inches.
Public method GetHashCode
Returns the hash code for the current instance.
(Overrides ValueTypeGetHashCode.)
Public methodStatic memberCode example Parse(String)
Parses a distance from a string representation using the current unit type and culture.
Public methodStatic memberCode example Parse(String, IFormatProvider)
Parses a distance from a string representation using the current unit type and the given culture.
Public methodStatic memberCode example Parse(String, IFormatProvider, DistanceUnitType)
Parses a distance from a string representation using the given unit type and culture.
Public methodCode example ToDecimalString
Converts the distance to a decimal string representation.
Public methodCode example ToDecimalString(IFormatProvider)
Converts the distance to a decimal string representation.
Public methodCode example ToDecimalString(String)
Converts the distance to a decimal string representation.
Public methodCode example ToDecimalString(String, IFormatProvider)
Converts the distance to a decimal string representation.
Public methodCode example ToDecimalString(String, IFormatProvider, DistanceUnitType)
Converts the distance to a decimal string representation.
Public methodCode example ToFractionalFeetAndInchesString
Creates a string representation of the distance in feet and inches.
Public methodCode example ToFractionalFeetAndInchesString(IFormatProvider)
Creates a string representation of the distance in feet and inches.
Public methodCode example ToFractionalInchesString
Creates a string representation of the distance in inches.
Public methodCode example ToFractionalInchesString(IFormatProvider)
Creates a string representation of the distance in inches.
Public methodCode example ToString
Creates a string representation of the distance.
(Overrides ValueTypeToString.)
Public methodCode example ToString(IFormatProvider)
Creates a string representation of the distance.
Public methodCode example ToString(String)
Creates a string representation of the distance.
Public methodCode example ToString(String, IFormatProvider)
Creates a string representation of the distance.
Public methodCode example ToString(String, IFormatProvider, DistanceUnitType)
Creates a string representation of the distance.
Public methodStatic memberCode example TryParse(String, Distance)
Attempts to parse a distance from a string representation using the current units.
Public methodStatic memberCode example TryParse(String, IFormatProvider, Distance)
Attempts to parse a distance from a string representation using the current units.
Public methodStatic memberCode example TryParse(String, IFormatProvider, DistanceUnitType, Distance)
Attempts to parse a distance from a string representation using the current units.
Top
Remarks
Distance stores, parses and formats distances in real world units.
Examples
using Tekla.Structures.Datatype;

public class Example
{
       public void Example1()
       {
           // Here we have an array of values in millimeters. These values may have come
           // from the Tekla Structures Open API (which assumes all distances to be in
           // millimeters) or from some other data source.
           double[] valuesInMillimeters = { 30.2, 40, 20 };

           // Here we have an array of values in inches. These may have come from the user
           // interface or some other data source.
           double[] valuesInInches = { 2, 4.5, 5 };


           // For this demonstration, we convert the values into millimeters and store
           // the sum of the distances into this array.
           Distance[] distances = new Distance[3];

           for(int i = 0; i < distances.Length; i++)
           {
               // The default unit type is millimeter.
               Distance value1 = new Distance(valuesInMillimeters[i]);

               // We need to explicitly define the unit type for inches.
               Distance value2 = new Distance(valuesInInches[i], Distance.UnitType.Inch);

               // To perform calculations, we need to use the same unit type for both
               // distances. In this case, we use millimeters.
               distances[i].Millimeters = value1.Millimeters + value2.Millimeters;
           }

           // While the Distance.ConvertTo method allows you to convert distances to other
           // distance units, it is usually better to keep all distances as instances of
           // Distance type and perform conversions only when absolutely necessary.
           // 
           // Distance provides extensive support for formatting and parsing distances, so
           // you usually need the conversion only when writing to some external data store.
           // 
           // To demonstrate conversion, we assume that the distance values need to be
           // converted to inches and stored in a database.

           double[] valuesInInchesToStoreInDatabase = new double[3];

           for(int i = 0; i < distances.Length; i++)
           {
               // We perform the conversion with the Distance.ConvertTo method just before
               // storing the values. All other distances should be kept as instances of
               // Distance type.
               valuesInInchesToStoreInDatabase[i] = distances[i].ConvertTo(Distance.UnitType.Inch);
           }

           // For the next demonstration, we assume that the program wants to use inches for
           // all distances. To do this, we set the current unit type. Current unit type
           // should be treated like locale; set it only once at the start of the program.
           Distance.CurrentUnitType = Distance.UnitType.Inch;

           // Create new Distance instance. The default unit is millimeters, even if the
           // current unit type is set to inches, so we still need to specify the unit type.
           Distance distance = new Distance(5, Distance.UnitType.Inch);

           // We have some distance in inches. This data may come from the user interface
           // or some other data source.
           double someDistanceInInches = 2;

           // To perform calculations in inches, we use the Distance.Value property to
           // get the distance in the current distance units. This way the program can
           // set the unit type once (usually at the start) and use the unit type for
           // all distances.
           double sumOfDistancesInInches = someDistanceInInches + distance.Value;

           // If the current unit type is changed during the run time, the above
           // calculation might use mismatching units and return incorrect result.
           // To prevent this, follow these simple rules:

           // 1) Use Distance type for all distances, specifying the unit when converting from plain values.
           Distance someDistance = new Distance(someDistanceInInches, Distance.UnitType.Inch);

           // 2) Perform calculations using the Distance.Millimeters property.
           Distance sumOfDistances = new Distance(someDistance.Millimeters + someDistance.Millimeters);
       }
}
See Also