Struct SwiftAmt

A financial amount with currency.

Implements

System.IComparable

Inherited Members

System.Object.Equals(System.Object, System.Object)

System.Object.GetType()

System.Object.ReferenceEquals(System.Object, System.Object)

Namespace: Subsembly.Swift

Assembly: Subsembly.Sepa.dll

Syntax

public struct SwiftAmt : IComparable

Remarks

This struct also includes some static convenience methods for parsing and formatting decimal numbers according to SWIFT, HBCI and FinTS.

Constructors

SwiftAmt(Decimal, String)

Constructs a SwiftAmt instance with the given properties.

Declaration

public SwiftAmt(decimal dcValue, string sCurrency)

Parameters

Type	Name	Description
System.Decimal	dcValue	Decimal value in the range from minus MaxValue through plus MaxValue.
System.String	sCurrency	The ISO currency code that denominates this amount.

Exceptions

Type	Condition
System.ArgumentNullException	The parameter sCurrency was `null`.
System.ArgumentOutOfRangeException	The parameter sCurrency was not a string consisting of three upper case letters, or the dcValue was not in the allowed range.

SwiftAmt(String, String)

Constructs a SwiftAmt instance from a decimal value given as a formatted string.

Declaration

public SwiftAmt(string sValue, string sCurrency)

Parameters

Type	Name	Description
System.String	sValue
System.String	sCurrency	The ISO currency code that denominates this amount.

Exceptions

Type	Condition
System.ArgumentNullException	The parameter sValue or sCurrency was `null`.
System.ArgumentOutOfRangeException	The parameter sCurrency was not a string consisting of three upper case letters, or the given sValue was an empty string, or was longer than 15 characters.
System.FormatException	The given sValue was not an acceptable representation according to the method Parse(String).

Fields

MaxValue

The maximum value allowed for a monetary amount stored in a SwiftAmt instance.

Declaration

public const decimal MaxValue = 99999999999999M

Field Value

Type	Description
System.Decimal

NullAmt

Represents a null amount.

Declaration

public static readonly SwiftAmt NullAmt

Field Value

Type	Description
SwiftAmt

Properties

Currency

The ISO currency code that denominates this amount.

Declaration

public string Currency { get; set; }

Property Value

Type	Description
System.String	An ISO currency code consists of three upper case letters. Any other value is not allowed.

Exceptions

Type	Condition
System.ArgumentNullException	An attempt to set a null reference will cause an ArgumentNullException to be thrown.
System.ArgumentOutOfRangeException	An attempt to set the currency code to a string that does not contain three upper case letters will cause an ArgumentOutOfRangeException to be thrown.

IsNegative

Indicates whether the Value is less than zero.

Declaration

public readonly bool IsNegative { get; }

Property Value

Type	Description
System.Boolean

IsNull

Indicates whether this SwiftAmt instance is logically null.

Declaration

public readonly bool IsNull { get; }

Property Value

Type	Description
System.Boolean

Value

The numerical value of this amount.

Declaration

public decimal Value { get; set; }

Property Value

Type	Description
System.Decimal	Decimal value in the range from minus MaxValue through plus MaxValue.

Exceptions

Type	Condition
System.ArgumentOutOfRangeException	An attempt to set a value smaller than minus MaxValue, or a value greater than plus MaxValue will cause an ArgumentOutOfRangeException to be thrown.

Methods

Add(Decimal)

Returns a new SwiftAmt with the sum of the Value and the given signed dcValue and the same Currency.

Declaration

public SwiftAmt Add(decimal dcValue)

Parameters

Type	Name	Description
System.Decimal	dcValue

Returns

Type	Description
SwiftAmt

Exceptions

Type	Condition
System.ArgumentOutOfRangeException	The sum of Value and `dcValue` is smaller than minus MaxValue, or greater than plus MaxValue.

CompareTo(Object)

Declaration

public int CompareTo(object obj)

Parameters

Type	Name	Description
System.Object	obj

Returns

Type	Description
System.Int32

Equals(Object)

Declaration

public override bool Equals(object obj)

Parameters

Type	Name	Description
System.Object	obj

Returns

Type	Description
System.Boolean

Overrides

System.ValueType.Equals(System.Object)

Format(Decimal)

Formats a decimal value into a string of characters using a comma as the decimal point symbol and generating no trailing zeroes.

Declaration

public static string Format(decimal dcValue)

Parameters

Type	Name	Description
System.Decimal	dcValue	Decimal value in the range from decimal zero through MaxValue that shall be formatted.

Returns

Type	Description
System.String	String that contains a formatted representation of the given decimal value. The returned string contains at most 15 chracters.

Remarks

This is an overloaded convenience method that internally just calls Format(Decimal, Char, Int32) passing a comma as the decimal point symbol and -1 as the desired number of decimal places.

Exceptions

Type	Condition
System.ArgumentOutOfRangeException	The dcValue was negative or greater than MaxValue.
System.FormatException	If the given decimal value has more than 13 significant decimal places , or if the resulting representation would have more than 15 characters, then a FormatException is thrown.

Format(Decimal, Char, Int32)

Formats a decimal value into a string of characters.

Declaration

public static string Format(decimal dcValue, char chDecimalPoint, int nDecimalPlaces)

Parameters

Type	Name	Description
System.Decimal	dcValue	Decimal value up to MaxValue that shall be formatted. If this is a negative value, then a minus sign will be prefixed.
System.Char	chDecimalPoint	Character to be used as the decimal point symbol. Currently this must be either '.' or ',', any other value is not allowed. For SWIFT, HBCI and FinTS decimal values, the decimal point must be a comma ','. For XML representations, including the FinTS XML representation, the decimal point must be a full stop '.'.
System.Int32	nDecimalPlaces	The desired number of decimal places following the decimal point. The formatted string will be filled up with trailing zeroes to that number of decimal places. Note that trailing zeroes are not allowed in HBCI and FinTS representations of decimal numbers. If this parameter is -1, then the formatted string will include whatever number of decimal places it takes to represent the given decimal value. In this case there will never be any trailing zeroes. The maximum allowed value for this parameter is 13. A value of 13 would imply, that there can be at most one digit in front of the decimal point.

Returns

Type	Description
System.String	String that contains a formatted representation of the given decimal value. The returned string contains at most 15 chracters.

Exceptions

Type	Condition
System.ArgumentOutOfRangeException	If any of the given parameters is outside the defined range, then an ArgumentOutOfRangeException is thrown.
System.FormatException	If the given decimal value has more significant decimal places than specified in nDecimalPlaces, or if the resulting representation would have more than 15 characters, then a FormatException is thrown.

GetHashCode()

Declaration

public override int GetHashCode()

Returns

Type	Description
System.Int32

Overrides

System.ValueType.GetHashCode()

Parse(String)

Parses a string representation of a decimal number with any number of decimal places into a decimal value.

Declaration

public static decimal Parse(string sValue)

Parameters

Type	Name	Description
System.String	sValue	String representation of a decimal number that shall be parsed. This string must not be longer than 15 characters and must not be `null`.

Returns

Type	Description
System.Decimal	Parsed quantity as a decimal value.

Remarks

Internally this method just calls the overloaded Parse(String, Int32), passing -1 for the parameter nDecimalPlaces.

Exceptions

Type	Condition
System.ArgumentNullException	The given sValue was `null`.
System.ArgumentOutOfRangeException	The given sValue was an empty string, or was longer than 15 characters.
System.FormatException	The given sValue was not an acceptable representation according to the rules of this method.

Parse(String, Int32)

Parses a SWIFT conforming string representation of a decimal number into a Decimal value.

Declaration

public static decimal Parse(string sValue, int nDecimalPlaces)

Parameters

Type	Name	Description
System.String	sValue	String representation of a decimal number that shall be parsed. This string must not be longer than 15 characters and must not be `null`.
System.Int32	nDecimalPlaces	Number of decimal places that may occur in the value string. If this is zero, then no decimal places at all may occur after the decimal point symbol. The absolute maximum number of decimal places accepted by this method is 13. If this parameter is -1, then the number of decimal places is not explicitly restricted at all. Note that trailing decimal zeroes also count as decimal places, although they do not add anything to the resulting value. For example: If nDecimalPlaces is 2, then the value string "0,100" will cause a FormatException to be thrown, because it specifies three decimal places. The given number of decimal places also affects the maximum accepted length of the integer part. As a general rule, the maximum length of the formatted value string is 15 characters. Therefore, if two decimal places are specified, then the maximum length of the integer part is 12 characters. This limitation is imposed, regardless of the actual number of decimal places given in the value string. The reason for this restriction is, that you would otherwise easily run into problems when adding two numbers.

Returns

Type	Description
System.Decimal	Parsed quantity as a decimal value.

Remarks

String representations that can be parsed by this method must solely consist of digits, an optional leading minus sign '-', and a single optional decimal point symbol, which can be either a comma ',' or a point '.'. No other characters may appear.

According to the SWIFT specification the decimal point symbol must always appear, even if there are no decimal places following it. This method, however, is more tolerant and also accepts strings that do not contain a decimal point symbol but solely consist of digits only.

Also, according to SWIFT, no sign must appear. All SWIFT decimals are always only positive vaules. In SWIFT negative values are usually indicated by an additional flag, somewhere else in the message data.

According to the HBCI and FinTS specifications, no leading or trailing zeroes are allowed. Again, however, this method tolerates any number of leading or trailing zeroes.

Here are some valid and some invalid examples:

0.01	This is just one of the many possible valid representations of that value. All the following representations would also be accepted, and lead to the very same value: "0,01", "0,0100", "0000.0100".
99999999999999,	This is the maxium value that can be parsed by this method. Any higher value will cause a FormatException to be thrown. Alternative acceptable representations of this value are: "99999999999999", "99999999999999.", "099999999999999".
0,0000000000001	This is the smallest value (apart from zero) that can be parsed by this method. Any value with more decimal places will cause a FormatException to be thrown. Alternative acceptable representations of this value are: "0.0000000000001", ",0000000000001".
1000000000000,00	Invalid because it is longer than 15 characters in total.
,00000000000010	Invalid because it has more than the maximum number of 13 decimal places following the decimal point symbol.
123 234,00	Invalid because it contains whitespace.
+123,00	Invalid because it contains a plus sign.
-123,	This is a valid representation of a negative value.

Exceptions

Type	Condition
System.ArgumentNullException	The given sValue was `null`.
System.ArgumentOutOfRangeException	The given sValue was an empty string, or was longer than 16 characters. The nDecimalPlaces parameter was smaller than -1 or greater than 13.
System.FormatException	The given sValue was not an acceptable representation according to the rules of this method.

ToString()

Declaration

public override string ToString()

Returns

Type	Description
System.String

Overrides

System.ValueType.ToString()

TryParse(String)

Tries to parse the string with any number of decimal places.

Declaration

public static decimal TryParse(string sValue)

Parameters

Type	Name	Description
System.String	sValue

Returns

Type	Description
System.Decimal

Remarks

Internally this just calls TryParse(String, Int32) with the value -1 for nDecimalPlaces.

TryParse(String, Int32)

Tries to parse the string with the given number of decimal places.

Declaration

public static decimal TryParse(string sValue, int nDecimalPlaces)

Parameters

Type	Name	Description
System.String	sValue
System.Int32	nDecimalPlaces

Returns

Type	Description
System.Decimal	If parsing fails, this method does not throw an exception, but rather returns the decimal value zero.

Operators

Equality(SwiftAmt, SwiftAmt)

Declaration

public static bool operator ==(SwiftAmt lhs, SwiftAmt rhs)

Parameters

Type	Name	Description
SwiftAmt	lhs
SwiftAmt	rhs

Returns

Type	Description
System.Boolean

GreaterThan(SwiftAmt, SwiftAmt)

Declaration

public static bool operator>(SwiftAmt lhs, SwiftAmt rhs)

Parameters

Type	Name	Description
SwiftAmt	lhs
SwiftAmt	rhs

Returns

Type	Description
System.Boolean

GreaterThanOrEqual(SwiftAmt, SwiftAmt)

Declaration

public static bool operator >=(SwiftAmt lhs, SwiftAmt rhs)

Parameters

Type	Name	Description
SwiftAmt	lhs
SwiftAmt	rhs

Returns

Type	Description
System.Boolean

Inequality(SwiftAmt, SwiftAmt)

Declaration

public static bool operator !=(SwiftAmt lhs, SwiftAmt rhs)

Parameters

Type	Name	Description
SwiftAmt	lhs
SwiftAmt	rhs

Returns

Type	Description
System.Boolean

LessThan(SwiftAmt, SwiftAmt)

Declaration

public static bool operator <(SwiftAmt lhs, SwiftAmt rhs)

Parameters

Type	Name	Description
SwiftAmt	lhs
SwiftAmt	rhs

Returns

Type	Description
System.Boolean

LessThanOrEqual(SwiftAmt, SwiftAmt)

Declaration

public static bool operator <=(SwiftAmt lhs, SwiftAmt rhs)

Parameters

Type	Name	Description
SwiftAmt	lhs
SwiftAmt	rhs

Returns

Type	Description
System.Boolean

Implements

System.IComparable