System.Collections.Specialized.NameValueCollection Class

public class NameValueCollection : Object

Base Types

Object
  NameValueCollection

This type implements ICollection and IEnumerable.

Assembly

System

Library

Networking

Summary

Represents a collection of associated String keys and String values.

Description

This class can be used for headers, query strings and form data. Each key in the collection is associated with one or more values. Multiple values for a particular key are contained in a single String are stored as a ArrayList .

The capacity is the number of key-and-value pairs that the NameValueCollection can contain. The default initial capacity is zero. The capacity is automatically increased as required.

The hash code provider dispenses hash codes for keys in the NameValueCollection.

The comparer determines whether two keys are equal.

Attributes

DefaultMemberAttribute("Item")

See Also

System.Collections.Specialized Namespace

Members

NameValueCollection Constructors

NameValueCollection() Constructor
NameValueCollection(System.Collections.Specialized.NameValueCollection) Constructor
NameValueCollection(System.Collections.IHashCodeProvider, System.Collections.IComparer) Constructor
NameValueCollection(int) Constructor
NameValueCollection(int, System.Collections.Specialized.NameValueCollection) Constructor
NameValueCollection(int, System.Collections.IHashCodeProvider, System.Collections.IComparer) Constructor

NameValueCollection Methods

NameValueCollection.Add(System.String, System.String) Method
NameValueCollection.Add(System.Collections.Specialized.NameValueCollection) Method
NameValueCollection.Clear Method
NameValueCollection.CopyTo Method
NameValueCollection.Get(int) Method
NameValueCollection.Get(System.String) Method
NameValueCollection.GetKey Method
NameValueCollection.GetValues(int) Method
NameValueCollection.GetValues(System.String) Method
NameValueCollection.HasKeys Method
NameValueCollection.InvalidateCachedArrays Method
NameValueCollection.Remove Method
NameValueCollection.Set Method

NameValueCollection Properties

NameValueCollection.AllKeys Property
NameValueCollection.Item(System.String) Property
NameValueCollection.Item(int) Property


NameValueCollection() Constructor

public NameValueCollection();

Summary

Constructs and initializes a new instance of the NameValueCollection class.

Description

The new instance is initialized with the default initial capacity, IHashCodeProvider, and IComparer.

See Also

System.Collections.Specialized.NameValueCollection Class, System.Collections.Specialized Namespace

NameValueCollection(System.Collections.Specialized.NameValueCollection) Constructor

public NameValueCollection(NameValueCollection col);

Summary

Constructs and initializes a new instance of the NameValueCollection class using the values of the specified NameValueCollection .

Parameters

col
The NameValueCollection used to initialize the new instance.

Exceptions

Exception TypeCondition
ArgumentNullExceptioncol is null .

Description

The capacity, values, and order of values of the new instance are equal to the capacity and values of col . The IHashCodeProvider and IComparer of the new instance are the default instances.

The elements of the new NameValueCollection are sorted in the same order as the source NameValueCollection.

See Also

System.Collections.Specialized.NameValueCollection Class, System.Collections.Specialized Namespace

NameValueCollection(System.Collections.IHashCodeProvider, System.Collections.IComparer) Constructor

public NameValueCollection(IHashCodeProvider hashProvider, IComparer comparer);

Summary

Constructs and initializes a new instance of the NameValueCollection class with the specified IHashCodeProvider and the specified IComparer .

Parameters

hashProvider
The IHashCodeProvider that supplies the hash codes for all keys in the new instance; or, null to use the default hash code provider.

comparer
The IComparer to use to determine whether two keys are equal. Specify null to use the default comparer.

Description

The new instance is initialized with the default capacity of zero.

See Also

System.Collections.Specialized.NameValueCollection Class, System.Collections.Specialized Namespace

NameValueCollection(int) Constructor

public NameValueCollection(int capacity);

Summary

Constructs and initializes a new instance of the NameValueCollection class with the specified initial capacity.

Parameters

capacity
A Int32 containing the initial number of entries that the new instance can contain.

Exceptions

Exception TypeCondition
ArgumentOutOfRangeExceptioncapacity < 0.

Description

The new instance is initialized with the default IHashCodeProvider and IComparer .

See Also

System.Collections.Specialized.NameValueCollection Class, System.Collections.Specialized Namespace

NameValueCollection(int, System.Collections.Specialized.NameValueCollection) Constructor

public NameValueCollection(int capacity, NameValueCollection col);

Summary

Constructs and initializes new instance of the NameValueCollection class that contains the same values as the specified NameValueCollection and either the specified capacity or the capacity of the specified collection, whichever is greater.

Parameters

capacity
A Int32 containing the initial number of entries that the new instance can contain.
col
The NameValueCollection used to initialize the new instance.

Exceptions

Exception TypeCondition
ArgumentNullExceptioncol is null .

Description

The new instance is initialized with the default IHashCodeProvider and IComparer .

See Also

System.Collections.Specialized.NameValueCollection Class, System.Collections.Specialized Namespace

NameValueCollection(int, System.Collections.IHashCodeProvider, System.Collections.IComparer) Constructor

public NameValueCollection(int capacity, IHashCodeProvider hashProvider, IComparer comparer);

Summary

Constructs and initializes new instance of the NameValueCollection class with the specified initial capacity, hash code provider, and comparer.

Parameters

capacity
A Int32 containing the initial number of entries that the NameValueCollection can contain.
hashProvider
The IHashCodeProvider that will supply the hash codes for all keys in the new instance.
comparer
The IComparer to use to determine whether two keys in the new instance are equal.

Exceptions

Exception TypeCondition
ArgumentOutOfRangeExceptioncapacity < 0.

See Also

System.Collections.Specialized.NameValueCollection Class, System.Collections.Specialized Namespace

NameValueCollection.Add(System.String, System.String) Method

public virtual void Add(string name, string value);

Summary

Adds an entry with the specified key and value to the current instance.

Parameters

name
A String that represents the key of the entry to add. Can be null .

value
A String that represents the value of the entry to add. Can be null .

Exceptions

Exception TypeCondition
NotSupportedExceptionThe current instance is read-only.

Description

[Behaviors: As described above.]

[Default: If the specified key already exists in the current instance, the specified value is added to the existing comma-separated list of values associated with the same key.

If the same value already exists under the same key in the collection, the new value overwrites the old value.

]

[Overrides: Override this method to customize the default behavior in a type derived from the current type.]

[Usage: Use this method to add an entry to the current instance.]

See Also

System.Collections.Specialized.NameValueCollection Class, System.Collections.Specialized Namespace

NameValueCollection.Add(System.Collections.Specialized.NameValueCollection) Method

public void Add(NameValueCollection c);

Summary

Copies the entries from the specified NameValueCollection to the current instance.

Parameters

c
The NameValueCollection to copy to the current instance.

Exceptions

Exception TypeCondition
NotSupportedExceptionThe current instance is read-only.
ArgumentNullExceptionc is null .

Description

If a key in c already exists in the target NameValueCollection instance, the associated value in c is added to the existing comma-separated list of values associated with the same key in the target NameValueCollection instance.

See Also

System.Collections.Specialized.NameValueCollection Class, System.Collections.Specialized Namespace

NameValueCollection.Clear Method

public void Clear();

Summary

Invalidates the cached arrays and removes all entries from the current instance.

Exceptions

Exception TypeCondition
NotSupportedExceptionThe current instance is read-only.

Description

The value of each key and value in the current instance is set to null .

If the current instance is empty, it remains unchanged and no exception is thrown.

See Also

System.Collections.Specialized.NameValueCollection Class, System.Collections.Specialized Namespace

NameValueCollection.CopyTo Method

public void CopyTo(Array dest, int index);

Summary

Copies the elements from the current instance to the specified Array, starting at the specified index in that array.

Parameters

dest
A one-dimensional, zero-based Array that is the destination of the elements copied from the current instance.
index
A Int32 containing the zero-based index in dest at which copying begins.

Exceptions

Exception TypeCondition
ArgumentNullExceptiondest is null .
ArgumentOutOfRangeExceptionindex < 0.
ArgumentExceptiondest has more than one dimension.

index >= dest.Length.

The number of elements in the current instance is greater than the available space from index to the end of the destination dest.

InvalidCastExceptionAt least one element in the current instance is not assignment-compatible with the type of dest.

Description

This method uses System.Array.Copy(System.Array,System.Array,System.Int32) to copy the elements.

[Note: This method is implemented to support the ICollection interface.]

See Also

System.Collections.Specialized.NameValueCollection Class, System.Collections.Specialized Namespace

NameValueCollection.Get(int) Method

public virtual string Get(int index);

Summary

Returns the values at the specified index of the current instance.

Parameters

index
A Int32 that specifies the zero-based index of the entry that contains the values to get from the current instance.

Return Value

A String that contains a comma-separated list of the values at the specified index of the current instance, if found; otherwise, null .

Exceptions

Exception TypeCondition
ArgumentOutOfRangeExceptionindex is outside the valid range of indices for the current instance.

Description

[Behaviors: As described above.]

See Also

System.Collections.Specialized.NameValueCollection Class, System.Collections.Specialized Namespace

NameValueCollection.Get(System.String) Method

public virtual string Get(string name);

Summary

Gets the values associated with the specified key from the current instance combined into one comma-separated list.

Parameters

name
A String that specified the key of the entry that contains the values to get.

Return Value

A String that contains a comma-separated list of the values associated with the specified key from the current instance, if found; otherwise, null .

Description

[Behaviors: As described above.]

[Default: If name is null , no exception is thrown and null is returned.]

See Also

System.Collections.Specialized.NameValueCollection Class, System.Collections.Specialized Namespace

NameValueCollection.GetKey Method

public virtual string GetKey(int index);

Summary

Returns the key at the specified index of the current instance.

Parameters

index
A Int32 that specifies the zero-based index of the key to get from the current instance.

Return Value

A String that contains the key at the specified index of the current instance, if found; otherwise, null .

Exceptions

Exception TypeCondition
ArgumentOutOfRangeExceptionindex is outside the valid range of indices for the current instance.

Description

[Behaviors: As described above.]

See Also

System.Collections.Specialized.NameValueCollection Class, System.Collections.Specialized Namespace

NameValueCollection.GetValues(int) Method

public virtual string[] GetValues(int index);

Summary

Returns an array that contains the values at the specified index of the current instance.

Parameters

index
A Int32 that specifies the zero-based index of the entry that contains the values to get from the current instance.

Return Value

A String array containing the values at the specified index of the current instance, if found; otherwise, null .

Exceptions

Exception TypeCondition
ArgumentOutOfRangeExceptionindex is outside the valid range of indices for the current instance.

Description

[Behaviors: As described above.]

See Also

System.Collections.Specialized.NameValueCollection Class, System.Collections.Specialized Namespace

NameValueCollection.GetValues(System.String) Method

public virtual string[] GetValues(string name);

Summary

Gets the values associated with the specified key from the current instance.

Parameters

name
A String that specifies the key of the entry that contains the values to get.

Return Value

A String array containing the values associated with name from the current instance, if found; otherwise, null .

Description

[Behaviors: As described above.]

[Default: If name is null , no exception is thrown and null is returned.]

See Also

System.Collections.Specialized.NameValueCollection Class, System.Collections.Specialized Namespace

NameValueCollection.HasKeys Method

public bool HasKeys();

Summary

Gets a Boolean value indicating whether the current instance contains keys that are not null .

Return Value

true if the current instance contains keys that are not null ; otherwise, false .

See Also

System.Collections.Specialized.NameValueCollection Class, System.Collections.Specialized Namespace

NameValueCollection.InvalidateCachedArrays Method

protected void InvalidateCachedArrays();

Summary

Resets the cached arrays of the current instance to null .

Description

[Note: The array returned by System.Collections.Specialized.NameValueCollection.AllKeys is cached for better performance and is automatically refreshed when the collection changes. A derived class can invalidate the cached version by calling System.Collections.Specialized.NameValueCollection.InvalidateCachedArrays, thereby forcing the arrays to be recreated.]

See Also

System.Collections.Specialized.NameValueCollection Class, System.Collections.Specialized Namespace

NameValueCollection.Remove Method

public virtual void Remove(string name);

Summary

Removes the entry with the specified key from the current instance.

Parameters

name
A String containing the key of the entry to remove from the current instance.

Exceptions

Exception TypeCondition
NotSupportedExceptionThe current instance is read-only or has a fixed size.

Description

[Behaviors: If name is found, the key name and its associated value are set to null . Removing an element does not alter the capacity of a NameValueCollection . ]

[Default: This method uses the System.Object.Equals(System.Object) implementation of name to locate name in the current instance. If name is not found in the current instance or is null , no exception is thrown and the current instance is unchanged. ]

See Also

System.Collections.Specialized.NameValueCollection Class, System.Collections.Specialized Namespace

NameValueCollection.Set Method

public virtual void Set(string name, string value);

Summary

Sets the value of the specified entry in the current instance to the specified value.

Parameters

name
A String containing the key of the entry to add the new value to.

value
A String containing the new value to add to the specified entry.

Exceptions

Exception TypeCondition
NotSupportedExceptionThe current instance is read-only.

Description

[Behaviors: If the specified key already exists in the current instance, this method overwrites the existing values with the specified value. If the specified key does not exist in the current instance, this method creates a new entry using the specified key and the specified value.]

[Usage: Use the System.Collections.Specialized.NameValueCollection.Add(System.Collections.Specialized.NameValueCollection) method to add the new value to the existing list of values.]

See Also

System.Collections.Specialized.NameValueCollection Class, System.Collections.Specialized Namespace

NameValueCollection.AllKeys Property

public virtual string[] AllKeys { get; }

Summary

Gets all the keys in the current instance.

Property Value

A String array containing all the keys of the current instance. If the current instance is empty, the value of this property is an empty array.

Description

[Behaviors: This property is read-only.]

[Usage: The array returned by System.Collections.Specialized.NameValueCollection.AllKeys is cached for better performance and is automatically refreshed when the collection changes. A derived class can invalidate the cached version by calling System.Collections.Specialized.NameValueCollection.InvalidateCachedArrays, thereby forcing the array to be refreshed.]

See Also

System.Collections.Specialized.NameValueCollection Class, System.Collections.Specialized Namespace

NameValueCollection.Item(System.String) Property

public string this[string name] { get; set; }

Summary

Gets or sets the value in the current instance that is associated with the specified key.

Parameters

name
A String containing the key of the entry to locate.

Property Value

A String that contains the comma-separated list of values associated with the specified key. If key is not contained in the current instance, attempting to get it returns null , and attempting to set it creates a new entry using key .

Exceptions

Exception TypeCondition
ArgumentOutOfRangeExceptionindex is outside the valid range of indexes for the collection.
NotSupportedExceptionThe property is being set and the current instance is read-only. The property is being set, key is not contained in the current instance, and the current instance has a fixed size.

Description

If the specified key already exists in the collection, setting this property overwrites the existing values with the specified value. If the specified key does not exist in the collection, setting this property creates a new entry using the specified key and the specified value.

[Note: This property provides the ability to access a specific element in the current instance using the following notation: myCollection[key] .

To add the new value to the existing list of values, use the System.Collections.Specialized.NameValueCollection.Add(System.Collections.Specialized.NameValueCollection) method.

]

See Also

System.Collections.Specialized.NameValueCollection Class, System.Collections.Specialized Namespace

NameValueCollection.Item(int) Property

public string this[int index] { get; }

Summary

Gets the value in the current instance that is associated with the specified index.

Parameters

index
A Int32 that specifies the zero-based index of the entry to locate in the current instance.

Property Value

A String that contains the comma-separated list of values at the specified index of the current instance.

Exceptions

Exception TypeCondition
ArgumentOutOfRangeExceptionindex is outside the valid range of indices for the current instance.

Description

This property is read-only.

[Note: This property provides the ability to access a specific element in the collection by using the following syntax: myCollection[index].

This property cannot be set. To set the value at a specified index, use Item[GetKey(index)].

]

See Also

System.Collections.Specialized.NameValueCollection Class, System.Collections.Specialized Namespace