Skip Headers
Oracle® Data Provider for .NET Developer's Guide
10g Release 2 (10.2)

Part Number B14307-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

OracleString Structure

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

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


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.

Declaration

// C#
public OracleString(string data);

Parameters

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

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

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

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

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

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 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

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 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

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

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

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.

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

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.

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

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.

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

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.

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

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.

NotEquals

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

Declaration

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

Parameters

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.


OracleString Static Operators

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

operator +

This static operator concatenates two OracleString values.

Declaration

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

Parameters

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

Return Value

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

Remarks

The following rules apply to the behavior of this method.

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

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.

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

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.

operator !=

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

Declaration

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

Parameters

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.

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

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.

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

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.


OracleString Type Conversions

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

explicit operator string

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

Declaration

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

Parameters

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

Return Value

An OracleString.


OracleString Properties

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

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 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

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

Return Value

The method returns a number that is:

Implements

IComparable

Exceptions

ArgumentException - The obj parameter is not of type OracleString.

Remarks

The following rules apply to the behavior of this method.

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

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.

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".