The OracleString structure represents a variable-length stream of characters to be stored in or retrieved from a database.
Class Inheritance
Object
ValueType
OracleString
Declaration
// C# public struct OracleString : IComparable
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
OracleString members are listed in the following tables:
OracleString Constructors
OracleString constructors are listed in Table 11-74
Table 11-74 OracleString Constructors
| Constructor | Description |
|---|---|
| OracleString Constructors | Instantiates a new instance of OracleString structure (Overloaded) |
OracleString Static Fields
The OracleString static fields are listed in Table 11-75.
Table 11-75 OracleString Static Fields
| Field | Description |
|---|---|
| Null | Represents a null value that can be assigned to an instance of the OracleString structure |
OracleString Static Methods
The OracleString static methods are listed in Table 11-76.
Table 11-76 OracleString Static Methods
| Methods | Description |
|---|---|
| Concat | Concatenates two OracleString instances and returns a new OracleString instance that represents the result |
| Equals | Determines if two OracleString values are equal (Overloaded) |
| GreaterThan | Determines whether or not the first of two OracleString values is greater than the second |
| GreaterThanOrEqual | Determines whether or not the first of two OracleString values is greater than or equal to the second |
| LessThan | Determines whether or not the first of two OracleString values is less than the second |
| LessThanOrEqual | Determines whether or not the first of two OracleString values is less than or equal to the second |
| NotEquals | Determines whether two OracleString values are not equal |
OracleString Static Operators
The OracleString static operators are listed in Table 11-77.
Table 11-77 OracleString Static Operators
| Operator | Description |
|---|---|
| operator + | Concatenates two OracleString values |
| operator == | Determines if two OracleString values are equal |
| operator > | Determines if the first of two OracleString values is greater than the second |
| operator >= | Determines if the first of two OracleString values is greater than or equal to the second |
| operator != | Determines if the two OracleString values are not equal |
| operator < | Determines if the first of two OracleString values is less than the second |
| operator <= | Determines if two OracleString values are not equal |
OracleString Type Conversions
The OracleString type conversions are listed in Table 11-78.
Table 11-78 OracleString Type Conversions
| Operator | Description |
|---|---|
| explicit operator string | Converts the supplied OracleString to a string instance |
| implicit operator OracleString | Converts the supplied string to an OracleString instance |
OracleString Properties
The OracleString properties are listed in Table 11-79.
Table 11-79 OracleString Properties
| Properties | Description |
|---|---|
| IsCaseIgnored | Indicates whether or not case should be ignored when performing string comparison |
| IsNull | Indicates whether or not the current instance has a null value |
| Item | Obtains the particular character in an OracleString using an index. |
| Length | Returns the length of the OracleString |
OracleString Methods
The OracleString methods are listed in Table 11-80.
Table 11-80 OracleString Methods
| Methods | Description |
|---|---|
| Clone | Returns a copy of the current OracleString instance |
| CompareTo | Compares the current OracleString instance to the supplied object, and returns an integer that represents their relative values |
| Equals | Determines whether or not an object has the same string value as the current OracleString structure (Overloaded) |
| GetHashCode | Returns a hash code for the OracleString instance |
| GetNonUnicodeBytes | Returns an array of bytes, containing the contents of the OracleString, in the client character set format |
| GetType | Inherited from Object |
| GetUnicodeBytes | Returns an array of bytes, containing the contents of the OracleString, in Unicode format |
| ToString | Converts the current OracleString instance to a string |
The OracleString constructors create new instances of the OracleString structure.
Overload List:
This constructor creates a new instance of the OracleString structure and sets its value using a string.
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.
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.
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.
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.
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.
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.
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.
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.
The OracleString static fields are listed in Table 11-81.
Table 11-81 OracleString Static Fields
| Field | Description |
|---|---|
| Null | Represents a null value that can be assigned to an instance of the OracleString structure |
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;
The OracleString static methods are listed in Table 11-82.
Table 11-82 OracleString Static Methods
| Methods | Description |
|---|---|
| Concat | Concatenates two OracleString instances and returns a new OracleString instance that represents the result |
| Equals | Determines if two OracleString values are equal (Overloaded) |
| GreaterThan | Determines whether or not the first of two OracleString values is greater than the second |
| GreaterThanOrEqual | Determines whether or not the first of two OracleString values is greater than or equal to the second |
| LessThan | Determines whether or not the first of two OracleString values is less than the second |
| LessThanOrEqual | Determines whether or not the first of two OracleString values is less than or equal to the second |
| NotEquals | Determines whether two OracleString values are not equal |
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.
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.
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.
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.
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.
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.
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.
The OracleString static operators are listed in Table 11-83.
Table 11-83 OracleString Static Operators
| Operator | Description |
|---|---|
| operator + | Concatenates two OracleString values |
| operator == | Determines if two OracleString values are equal |
| operator > | Determines if the first of two OracleString values is greater than the second |
| operator >= | Determines if the first of two OracleString values is greater than or equal to the second |
| operator != | Determines if the two OracleString values are not equal |
| operator < | Determines if the first of two OracleString values is less than the second |
| operator <= | Determines if two OracleString values are not equal |
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.
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.
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.
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.
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.
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.
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.
The OracleString type conversions are listed in Table 11-84.
Table 11-84 OracleString Type Conversions
| Operator | Description |
|---|---|
| explicit operator string | Converts the supplied OracleString to a string instance |
| implicit operator OracleString | Converts the supplied string to an OracleString instance |
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.
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.
The OracleString properties are listed in Table 11-85.
Table 11-85 OracleString Properties
| Properties | Description |
|---|---|
| IsCaseIgnored | Indicates whether or not case should be ignored when performing string comparison |
| IsNull | Indicates whether or not the current instance has a null value |
| Item | Obtains the particular character in an OracleString using an index. |
| Length | Returns the length of the OracleString |
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));
}
}
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.
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.
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.
The OracleString methods are listed in Table 11-86.
Table 11-86 OracleString Methods
| Methods | Description |
|---|---|
| Clone | Returns a copy of the current OracleString instance |
| CompareTo | Compares the current OracleString instance to the supplied object, and returns an integer that represents their relative values |
| Equals | Determines whether or not an object has the same string value as the current OracleString structure (Overloaded) |
| GetHashCode | Returns a hash code for the OracleString instance |
| GetNonUnicodeBytes | Returns an array of bytes, containing the contents of the OracleString, in the client character set format |
| GetType | Inherited from Object |
| GetUnicodeBytes | Returns an array of bytes, containing the contents of the OracleString, in Unicode format |
| ToString | Converts the current OracleString instance to a string |
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));
}
}
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.
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.
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.
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.
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.
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".