OracleString Structure

The OracleString structure represents a variable-length stream of characters to be stored in or retrieved from a database.

Class Inheritance

System.Object

  System.ValueType

    Oracle.DataAccess.Types.OracleString

Declaration

// ADO.NET 2.0: C#
public struct OracleString : IComparable, INullable, IXmlSerializable

Thread Safety

All public static methods are thread-safe, although instance methods do not guarantee thread safety.

Example

// C#
 
using System;
using Oracle.DataAccess.Types;
 
class OracleStringSample
{
  static void Main()
  {
    // Initialize OracleString structs
    OracleString string1 = new OracleString("AAA");
    
    // Display the string "AAA"
    Console.WriteLine("{0} has length of {1}", string1, string1.Length);
 
    // Contatenate characters to string1 until the length is 5 
    while (string1.Length < 5)
      string1 = OracleString.Concat(string1,"a");
      
    // Display the string of "AAAaa"
    Console.WriteLine("{0} has length of {1}", string1, string1.Length);
  }
}

Requirements

Namespace: Oracle.DataAccess.Types

Assembly: Oracle.DataAccess.dll

ODP.NET Version: ODP.NET for .NET Framework 2.0 or ODP.NET for .NET Framework 4

---

OracleString Members

OracleString members are listed in the following tables:

OracleString Constructors

OracleString constructors are listed in Table 14-74

OracleString Static Fields

The OracleString static fields are listed in Table 14-75.

OracleString Static Methods

The OracleString static methods are listed in Table 14-76.

OracleString Static Operators

The OracleString static operators are listed in Table 14-77.

OracleString Type Conversions

The OracleString type conversions are listed in Table 14-78.

OracleString Properties

The OracleString properties are listed in Table 14-79.

OracleString Methods

The OracleString methods are listed in Table 14-80.

---

OracleString Constructors

The OracleString constructors create new instances of the OracleString structure.

Overload List:

• OracleString(string)

  This constructor creates a new instance of the OracleString structure and sets its value using a string.

• OracleString(string, bool)

  This constructor creates a new instance of the OracleString structure and sets its value using a string and specifies if case is ignored in comparison.

• OracleString(byte [ ], bool)

  This constructor creates a new instance of the OracleString structure and sets its value using a byte array and specifies if the supplied byte array is Unicode encoded.

• OracleString(byte [ ], bool, bool)

  This constructor creates a new instance of the OracleString structure and sets its value using a byte array and specifies the following: if the supplied byte array is Unicode encoded and if case is ignored in comparison.

• OracleString(byte [ ], int, int, bool)

  This constructor creates a new instance of the OracleString structure and sets its value using a byte array, and specifies the following: the starting index in the byte array, the number of bytes to copy from the byte array, and if the supplied byte array is Unicode encoded.

• OracleString(byte [ ], int, int, bool, bool)

  This constructor creates a new instance of the OracleString structure and sets its value using a byte array, and specifies the following: the starting index in the byte array, the number of bytes to copy from the byte array, if the supplied byte array is Unicode encoded, and if case is ignored in comparison.

OracleString(string)

This constructor creates a new instance of the OracleString structure and sets its value using a string.

Declaration

// C#
public OracleString(string data);

Parameters

• data

  A string value.

OracleString(string, bool)

This constructor creates a new instance of the OracleString structure and sets its value using a string and specifies if case is ignored in comparison.

Declaration

// C#
public OracleString(string data, bool isCaseIgnored);

Parameters

• data

  A string value.

• isCaseIgnored

  Specifies if case is ignored in comparison. Specifies true if case is to be ignored; otherwise, specifies false.

OracleString(byte [ ], bool)

This constructor creates a new instance of the OracleString structure and sets its value using a byte array and specifies if the supplied byte array is Unicode encoded.

Declaration

// C#
public OracleString(byte[] data, bool fUnicode);

Parameters

• data

  Byte array data for the new OracleString.

• fUnicode

  Specifies if the supplied data is Unicode encoded. Specifies true if Unicode encoded; otherwise, false.

Exceptions

ArgumentNullException - The data parameter is null.

OracleString(byte [ ], bool, bool)

This constructor creates a new instance of the OracleString structure and sets its value using a byte array and specifies the following: if the supplied byte array is Unicode encoded and if case is ignored in comparison.

Declaration

// C#
public OracleString(byte[] data, bool fUnicode, bool isCaseIgnored);

Parameters

• data

  Byte array data for the new OracleString.

• fUnicode

  Specifies if the supplied data is Unicode encoded. Specifies true if Unicode encoded; otherwise, false.

• isCaseIgnored

  Specifies if case is ignored in comparison. Specifies true if case is to be ignored; otherwise, specifies false.

Exceptions

ArgumentNullException - The data parameter is null.

OracleString(byte [ ], int, int, bool)

This constructor creates a new instance of the OracleString structure and sets its value using a byte array, and specifies the following: the starting index in the byte array, the number of bytes to copy from the byte array, and if the supplied byte array is Unicode encoded.

Declaration

// C#
public OracleString(byte[] data, int index, int count, bool fUnicode);

Parameters

• data

  Byte array data for the new OracleString.

• index

  The starting index to copy from data.

• count

  The number of bytes to copy.

• fUnicode

  Specifies if the supplied data is Unicode encoded. Specifies true if Unicode encoded; otherwise, false.

Exceptions

ArgumentNullException - The data parameter is null.

ArgumentOutOfRangeException - The count parameter is less than zero.

IndexOutOfRangeException - The index parameter is greater than or equal to the length of data or less than zero.

OracleString(byte [ ], int, int, bool, bool)

This constructor creates a new instance of the OracleString structure and sets its value using a byte array, and specifies the following: the starting index in the byte array, the number of bytes to copy from the byte array, if the supplied byte array is Unicode encoded, and if case is ignored in comparison.

Declaration

// C#
public OracleString(byte[] data, int index, int count, bool fUnicode,
 bool isCaseIgnored);

Parameters

• data

  Byte array data for the new OracleString.

• index

  The starting index to copy from data.

• count

  The number of bytes to copy.

• fUnicode

  Specifies if the supplied data is Unicode encoded. Specifies true if Unicode encoded; otherwise, false.

• isCaseIgnored

  Specifies if case is ignored in comparison. Specifies true if case is to be ignored; otherwise, specifies false.

Exceptions

ArgumentNullException - The data parameter is null.

ArgumentOutOfRangeException - The count parameter is less than zero.

IndexOutOfRangeException - The index parameter is greater than or equal to the length of data or less than zero.

---

OracleString Static Fields

The OracleString static fields are listed in Table 14-81.

Null

This static field represents a null value that can be assigned to an instance of the OracleString structure.

Declaration

// C#
public static readonly OracleString Null;

---

OracleString Static Methods

The OracleString static methods are listed in Table 14-82.

Concat

This static method concatenates two OracleString instances and returns a new OracleString instance that represents the result.

Declaration

// C#
public static OracleString Concat(OracleString str1, OracleString str2);

Parameters

• str1

  The first OracleString.

• str2

  The second OracleString.

Return Value

An OracleString.

Remarks

If either argument has a null value, the returned OracleString structure has a null value.

Equals

Overloads Object

This static method determines whether or not the two OracleStrings being compared are equal.

Declaration

// C#
public static bool Equals(OracleString str1, OracleString str2);

Parameters

• str1

  The first OracleString.

• str2

  The second OracleString.

Return Value

Returns true if the two OracleStrings being compared are equal; returns false otherwise.

Remarks

The following rules apply to the behavior of this method.

• Any OracleString that has a value is greater than an OracleString that has a null value.

• Two OracleStrings that contain a null value are equal.

GreaterThan

This static method determines whether or not the first of two OracleString values is greater than the second.

Declaration

// C#
public static bool GreaterThan(OracleString str1, OracleString str2);

Parameters

• str1

  The first OracleString.

• str2

  The second OracleString.

Return Value

Returns true if the first of two OracleStrings is greater than the second; otherwise, returns false.

Remarks

The following rules apply to the behavior of this method.

• Any OracleString that has a value is greater than an OracleString that has a null value.

• Two OracleStrings that contain a null value are equal.

GreaterThanOrEqual

This static method determines whether or not the first of two OracleString values is greater than or equal to the second.

Declaration

// C#
public static bool GreaterThanOrEqual(OracleString str1, 
    OracleString str2);

Parameters

• str1

  The first OracleString.

• str2

  The second OracleString.

Return Value

Returns true if the first of two OracleStrings is greater than or equal to the second; otherwise, returns false.

Remarks

The following rules apply to the behavior of this method.

• Any OracleString that has a value is greater than an OracleString that has a null value.

• Two OracleStrings that contain a null value are equal.

LessThan

This static method determines whether or not the first of two OracleString values is less than the second.

Declaration

// C#
public static bool LessThan(OracleString str1, OracleString str2);

Parameters

• str1

  The first OracleString.

• str2

  The second OracleString.

Return Value

Returns true if the first is less than the second; otherwise, returns false.

Remarks

The following rules apply to the behavior of this method.

• Any OracleString that has a value is greater than an OracleString that has a null value.

• Two OracleStrings that contain a null value are equal.

LessThanOrEqual

This static method determines whether or not the first of two OracleString values is less than or equal to the second.

Declaration

// C#
public static bool LessThanOrEqual(OracleString str1, OracleString str2);

Parameters

• str1

  The first OracleString.

• str2

  The second OracleString.

Return Value

Returns true if the first is less than or equal to the second; otherwise, returns false.

Remarks

The following rules apply to the behavior of this method.

• Any OracleString that has a value is greater than an OracleString that has a null value.

• Two OracleStrings that contain a null value are equal.

NotEquals

This static method determines whether two OracleString values are not equal.

Declaration

// C#
public static bool NotEquals(OracleString str1, OracleString str2);

Parameters

• str1

  The first OracleString.

• str2

  The second OracleString.

Return Value

Returns true if the two OracleString instances are not equal; otherwise, returns false.

Remarks

The following rules apply to the behavior of this method.

• Any OracleString that has a value is greater than an OracleString that has a null value.

• Two OracleStrings that contain a null value are equal.

---

OracleString Static Operators

The OracleString static operators are listed in Table 14-83.

operator +

This static operator concatenates two OracleString values.

Declaration

// C#
public static OracleString operator + (OracleString value1, OracleString value2);

Parameters

• value1

  The first OracleString.

• value2

  The second OracleString.

Return Value

An OracleString.

Remarks

If either argument has a null value, the returned OracleString structure has a null value.

operator ==

This static operator determines if two OracleString values are equal.

Declaration

// C#
public static bool operator == (OracleString value1, OracleString value2);

Parameters

• value1

  The first OracleString.

• value2

  The second OracleString.

Return Value

Returns true if two OracleString values are equal; otherwise, returns false.

Remarks

The following rules apply to the behavior of this method.

• Any OracleString that has a value is greater than an OracleString that has a null value.

• Two OracleStrings that contain a null value are equal.

operator >

This static operator determines if the first of two OracleString values is greater than the second.

Declaration

// C#
public static bool operator > (OracleString value1, OracleString value2);

Parameters

• value1

  The first OracleString.

• value2

  The second OracleString.

Return Value

Returns true if the first of two OracleString values is greater than the second; otherwise returns false.

Remarks

The following rules apply to the behavior of this method.

• Any OracleString that has a value is greater than an OracleString that has a null value.

• Two OracleStrings that contain a null value are equal.

operator >=

This static operator determines if the first of two OracleString values is greater than or equal to the second.

Declaration

// C#
public static bool operator >= (OracleString value1, OracleString value2);

Parameters

• value1

  The first OracleString.

• value2

  The second OracleString.

Return Value

Returns true if the first of two OracleString values is greater than or equal to the second; otherwise, returns false.

Remarks

The following rules apply to the behavior of this method.

• Any OracleString that has a value is greater than an OracleString that has a null value.

• Two OracleStrings that contain a null value are equal.

operator !=

This static operator determines if two OracleString values are not equal.

Declaration

// C#
public static bool operator != (OracleString value1, OracleString value2);

Parameters

• value1

  The first OracleString.

• value2

  The second OracleString.

Return Value

Returns true if two OracleString values are not equal; otherwise, returns false.

Remarks

The following rules apply to the behavior of this method.

• Any OracleString that has a value is greater than an OracleString that has a null value.

• Two OracleStrings that contain a null value are equal.

operator <

This static operator determines if the first of two OracleStrings is less than the second.

Declaration

// C#
public static bool operator < (OracleString value1, OracleString value2);

Parameters

• value1

  The first OracleString.

• value2

  The second OracleString.

Return Value

Returns true if the first of two OracleStrings is less than the second; otherwise, returns false.

Remarks

The following rules apply to the behavior of this method.

• Any OracleString that has a value is greater than an OracleString has a null value.

• Two OracleStrings that contain a null value are equal.

operator <=

This static operator determines if the first of two OracleString values is less than or equal to the second.

Declaration

// C#
public static bool operator <= (OracleString value1, OracleString value1);

Parameters

• value1

  The first OracleString.

• value2

  The second OracleString.

Return Value

Returns true if the first of two OracleString values is less than or equal to the second; otherwise, returns false.

Remarks

The following rules apply to the behavior of this method.

• Any OracleString that has a value is greater than an OracleString that has a null value.

• Two OracleStrings that contain a null value are equal.

---

OracleString Type Conversions

The OracleString type conversions are listed in Table 14-84.

explicit operator string

This type conversion operator converts the supplied OracleString to a string.

Declaration

//C#
public static explicit operator string (OracleString value1);

Parameters

• value1

  The supplied OracleString.

Return Value

string

Exceptions

OracleNullValueException - The OracleString structure has a null value.

implicit operator OracleString

This type conversion operator converts the supplied string to an OracleString.

Declaration

// C#
public static implicit operator OracleString (string value1);

Parameters

• value1

  The supplied string.

Return Value

An OracleString.

---

OracleString Properties

The OracleString properties are listed in Table 14-85.

IsCaseIgnored

This property indicates whether or not case should be ignored when performing string comparison.

Declaration

//C#
public bool IsCaseIgnored {get;set;}

Property Value

Returns true if string comparison must ignore case; otherwise false.

Remarks

Default value is true.

Example

// C#
 
using System;
using Oracle.DataAccess.Types;
 
class IsCaseIgnoredSample
{
  static void Main()
  {
    OracleString string1 = new OracleString("aAaAa");
    OracleString string2 = new OracleString("AaAaA");
 
    // Ignore case for comparisons
    string1.IsCaseIgnored = true;
    string2.IsCaseIgnored = true;
 
    // Same; Prints 0
    Console.WriteLine(string1.CompareTo(string2));
 
    // Make comparisons case sensitive   
    // Note that IsCaseIgnored must be set to false for both 
    //   OracleStrings; otherwise an exception is thrown
    string1.IsCaseIgnored = false;
    string2.IsCaseIgnored = false;
 
    // Different; Prints nonzero value
    Console.WriteLine(string1.CompareTo(string2));
  }
}

IsNull

This property indicates whether or not the current instance contains a null value.

Declaration

// C#
public bool IsNull {get;}

Property Value

Returns true if the current instance contains has a null value; otherwise, returns false.

Item

This property obtains the particular character in an OracleString using an index.

Declaration

// C#
public char Item {get;}

Property Value

A char value.

Exceptions

OracleNullValueException - The current instance has a null value.

Length

This property returns the length of the OracleString.

Declaration

// C#
public int Length {get;}

Property Value

A int value.

Exceptions

OracleNullValueException - The current instance has a null value.

---

OracleString Methods

The OracleString methods are listed in Table 14-86.

Clone

This method creates a copy of an OracleString instance.

Declaration

// C#
public OracleString Clone();

Return Value

An OracleString structure.

Remarks

The cloned object has the same property values as that of the object being cloned.

Example

// C#
 
using System;
using Oracle.DataAccess.Types;
 
class CloneSample
{
  static void Main()
  {
    OracleString str1 = new OracleString("aAaAa");
    OracleString str2 = str1.Clone();
 
    // The OracleStrings are same; Prints 0
    Console.WriteLine(str1.CompareTo(str2));
  }
}

CompareTo

This method compares the current OracleString instance to the supplied object, and returns an integer that represents their relative values.

Declaration

// C#
public int CompareTo(object obj);

Parameters

• obj

  The object being compared to the current instance.

Return Value

The method returns a number that is:

• Less than zero: if the current OracleString value is less than obj.

• Zero: if the current OracleString value is equal to obj.

• Greater than zero: if the current OracleString value is greater than obj.

Implements

IComparable

Exceptions

ArgumentException - The obj parameter is not of type OracleString.

Remarks

The following rules apply to the behavior of this method.

• The comparison must be between OracleStrings. For example, comparing an OracleString instance with an OracleBinary instance is not allowed. When an OracleString is compared with a different type, an ArgumentException is thrown.

• Any OracleString that has a value is greater than an OracleString that has a null value.

• Two OracleStrings that contain a null value are equal.

Equals

This method determines whether or not supplied object is an instance of OracleString and has the same values as the current OracleString instance.

Declaration

// C#
public override bool Equals(object obj);

Parameters

• obj

  An object being compared.

Return Value

Returns true if the supplied object is an instance of OracleString and has the same values as the current OracleString instance; otherwise, returns false.

Remarks

The following rules apply to the behavior of this method.

• Any OracleString that has a value is greater than an OracleString that has a null value.

• Two OracleStrings that contain a null value are equal.

GetHashCode

Overrides Object

This method returns a hash code for the OracleString instance.

Declaration

// C#
public override int GetHashCode();

Return Value

A number that represents the hash code.

GetNonUnicodeBytes

This method returns an array of bytes, containing the contents of the OracleString, in the client character set format.

Declaration

// C#
public byte[] GetNonUnicodeBytes();

Return Value

A byte array that contains the contents of the OracleString in the client character set format.

Remarks

If the current instance has a null value, an OracleNullValueException is thrown.

GetUnicodeBytes

This method returns an array of bytes, containing the contents of the OracleString in Unicode format.

Declaration

// C#
public byte[] GetUnicodeBytes();

Return Value

A byte array that contains the contents of the OracleString in Unicode format.

Remarks

If the current instance has a null value, an OracleNullValueException is thrown.

ToString

Overrides Object

This method converts the current OracleString instance to a string.

Declaration

// C#
public override string ToString();

Return Value

A string.

Remarks

If the current OracleString instance has a null value, the string contains "null".