# HierarchicalKey Methods

[Type overview](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.hierarchicalkey/)

## Append(HierarchicalKey) {#append-orleans-durable-messaging-hierarchicalkey-8297959a}

[Dedicated page](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.hierarchicalkey/methods/append-orleans-durable-messaging-hierarchicalkey-8297959a/)

[Source](https://github.com/dotnet/orleans/blob/6a0e937f544c35ffcf11b37e4c2b7de5a1580a03/src/Orleans.Durable/Messaging/HierarchicalKey.cs#L127-L129)

```csharp
public HierarchicalKey Append(HierarchicalKey suffix)
```

Composes this hierarchy with an already constructed suffix hierarchy.

### Parameters

- `suffix` (`HierarchicalKey`): The constructed suffix.

### Returns

A flat concatenated identity preserving both paths' segment boundaries.

### Exceptions

- `System.InvalidOperationException`: This key is unset.
- `System.ArgumentException`: `suffix` is unset.

## Create(ReadOnlySpan&lt;string&gt;) {#create-params-system-readonlyspan-string-71d646c0}

[Dedicated page](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.hierarchicalkey/methods/create-params-system-readonlyspan-string-71d646c0/)

[Source](https://github.com/dotnet/orleans/blob/6a0e937f544c35ffcf11b37e4c2b7de5a1580a03/src/Orleans.Durable/Messaging/HierarchicalKey.cs#L93-L104)

```csharp
public static HierarchicalKey Create(params ReadOnlySpan<string> values)
```

Creates a hierarchy from literal segments in root-first order.

### Parameters

- `values` (`ReadOnlySpan<string>`): The nonempty literal segments.

### Returns

A flat canonical identity which owns its immutable backing string.

### Exceptions

- `System.ArgumentNullException`: A segment is null.
- `System.ArgumentException`: The input or a segment is empty, or a segment contains an unpaired surrogate.

## Create(string) {#create-string-ee1c186f}

[Dedicated page](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.hierarchicalkey/methods/create-string-ee1c186f/)

[Source](https://github.com/dotnet/orleans/blob/6a0e937f544c35ffcf11b37e4c2b7de5a1580a03/src/Orleans.Durable/Messaging/HierarchicalKey.cs#L82-L83)

```csharp
public static HierarchicalKey Create(string value)
```

Creates one literal segment, escaping slash and backslash characters.

### Parameters

- `value` (`string`): The nonempty literal segment.

### Returns

The segment identity.

### Exceptions

- `System.ArgumentNullException`: `value` is null.
- `System.ArgumentException`: `value` is empty or contains an unpaired surrogate.

## CreateChildKey(string) {#createchildkey-string-2ebf7854}

[Dedicated page](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.hierarchicalkey/methods/createchildkey-string-2ebf7854/)

[Source](https://github.com/dotnet/orleans/blob/6a0e937f544c35ffcf11b37e4c2b7de5a1580a03/src/Orleans.Durable/Messaging/HierarchicalKey.cs#L115-L117)

```csharp
public HierarchicalKey CreateChildKey(string value)
```

Appends one literal child segment.

### Parameters

- `value` (`string`): The nonempty literal child segment.

### Returns

The child identity.

### Exceptions

- `System.InvalidOperationException`: This key is unset.
- `System.ArgumentNullException`: `value` is null.
- `System.ArgumentException`: `value` is empty or contains an unpaired surrogate.

## Equals(HierarchicalKey) {#equals-orleans-durable-messaging-hierarchicalkey-4e695d3c}

[Dedicated page](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.hierarchicalkey/methods/equals-orleans-durable-messaging-hierarchicalkey-4e695d3c/)

[Source](https://github.com/dotnet/orleans/blob/6a0e937f544c35ffcf11b37e4c2b7de5a1580a03/src/Orleans.Durable/Messaging/HierarchicalKey.cs#L194)

```csharp
public bool Equals(HierarchicalKey other)
```

Indicates whether the current object is equal to another object of the same type.

### Parameters

- `other` (`HierarchicalKey`): An object to compare with this object.

### Returns

`true` if the current object is equal to the `other` parameter; otherwise, `false`.

## Equals(object?) {#equals-object-nullable-e29e5215}

[Dedicated page](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.hierarchicalkey/methods/equals-object-nullable-e29e5215/)

[Source](https://github.com/dotnet/orleans/blob/6a0e937f544c35ffcf11b37e4c2b7de5a1580a03/src/Orleans.Durable/Messaging/HierarchicalKey.cs#L198)

```csharp
public override bool Equals(object? obj)
```

Indicates whether this instance and a specified object are equal.

### Parameters

- `obj` (`object?`): The object to compare with the current instance.

### Returns

`true` if `obj` and this instance are the same type and represent the same value; otherwise, `false`.

## GetEnumerator {#getenumerator-2305f5a4}

[Dedicated page](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.hierarchicalkey/methods/getenumerator-2305f5a4/)

[Source](https://github.com/dotnet/orleans/blob/6a0e937f544c35ffcf11b37e4c2b7de5a1580a03/src/Orleans.Durable/Messaging/HierarchicalKey.cs#L235)

```csharp
public SegmentEnumerator GetEnumerator()
```

Enumerates escaped canonical segment spans in root-first order.

### Returns

An allocation-free segment enumerator.

## GetHashCode {#gethashcode-2bf64ca9}

[Dedicated page](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.hierarchicalkey/methods/gethashcode-2bf64ca9/)

[Source](https://github.com/dotnet/orleans/blob/6a0e937f544c35ffcf11b37e4c2b7de5a1580a03/src/Orleans.Durable/Messaging/HierarchicalKey.cs#L201)

```csharp
public override int GetHashCode()
```

Returns the hash code for this instance.

### Returns

A 32-bit signed integer that is the hash code for this instance.

## GetParent {#getparent-05beb5ac}

[Dedicated page](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.hierarchicalkey/methods/getparent-05beb5ac/)

[Source](https://github.com/dotnet/orleans/blob/6a0e937f544c35ffcf11b37e4c2b7de5a1580a03/src/Orleans.Durable/Messaging/HierarchicalKey.cs#L136-L138)

```csharp
public HierarchicalKey? GetParent()
```

Gets the immediate parent, or null for a root or unset key.

### Returns

The parent identity when this key has more than one segment.

## IsAncestorOf(HierarchicalKey) {#isancestorof-orleans-durable-messaging-hierarchicalkey-906582d7}

[Dedicated page](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.hierarchicalkey/methods/isancestorof-orleans-durable-messaging-hierarchicalkey-906582d7/)

[Source](https://github.com/dotnet/orleans/blob/6a0e937f544c35ffcf11b37e4c2b7de5a1580a03/src/Orleans.Durable/Messaging/HierarchicalKey.cs#L154-L156)

```csharp
public bool IsAncestorOf(HierarchicalKey other)
```

Tests whether this key is equal to or an ancestor of the other key.

### Parameters

- `other` (`HierarchicalKey`): The identity to inspect.

### Returns

Whether the full prefix consists of equal ordinal segments. Unset keys return false.

## IsChildOf(HierarchicalKey) {#ischildof-orleans-durable-messaging-hierarchicalkey-d9b87ada}

[Dedicated page](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.hierarchicalkey/methods/ischildof-orleans-durable-messaging-hierarchicalkey-d9b87ada/)

[Source](https://github.com/dotnet/orleans/blob/6a0e937f544c35ffcf11b37e4c2b7de5a1580a03/src/Orleans.Durable/Messaging/HierarchicalKey.cs#L144)

```csharp
public bool IsChildOf(HierarchicalKey other)
```

Tests whether this key is the other's immediate child.

### Parameters

- `other` (`HierarchicalKey`): The potential parent.

### Returns

Whether there is exactly one additional segment.

## IsParentOf(HierarchicalKey) {#isparentof-orleans-durable-messaging-hierarchicalkey-e934c2b4}

[Dedicated page](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.hierarchicalkey/methods/isparentof-orleans-durable-messaging-hierarchicalkey-e934c2b4/)

[Source](https://github.com/dotnet/orleans/blob/6a0e937f544c35ffcf11b37e4c2b7de5a1580a03/src/Orleans.Durable/Messaging/HierarchicalKey.cs#L149)

```csharp
public bool IsParentOf(HierarchicalKey other)
```

Tests whether this key is the other's immediate parent.

### Parameters

- `other` (`HierarchicalKey`): The potential child.

### Returns

Whether the other key extends this key by exactly one segment.

## Parse(ReadOnlySpan&lt;char&gt;, IFormatProvider?) {#parse-system-readonlyspan-char-system-iformatprovider-nullable-9284fe8c}

[Dedicated page](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.hierarchicalkey/methods/parse-system-readonlyspan-char-system-iformatprovider-nullable-9284fe8c/)

[Source](https://github.com/dotnet/orleans/blob/6a0e937f544c35ffcf11b37e4c2b7de5a1580a03/src/Orleans.Durable/Messaging/HierarchicalKey.cs)

```csharp
public static HierarchicalKey Parse(ReadOnlySpan<char> s, IFormatProvider? provider = null)
```

Parses a span of characters into a value.

### Parameters

- `s` (`ReadOnlySpan<char>`): The span of characters to parse.
- `provider` (`IFormatProvider?`): An object that provides culture-specific formatting information about `s`.

### Returns

The result of parsing `s`.

### Exceptions

- `System.FormatException`: `s` is not in the correct format.
- `System.OverflowException`: `s` is not representable by `TSelf`.

## Parse(string, IFormatProvider?) {#parse-string-system-iformatprovider-nullable-d4d68f37}

[Dedicated page](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.hierarchicalkey/methods/parse-string-system-iformatprovider-nullable-d4d68f37/)

[Source](https://github.com/dotnet/orleans/blob/6a0e937f544c35ffcf11b37e4c2b7de5a1580a03/src/Orleans.Durable/Messaging/HierarchicalKey.cs)

```csharp
public static HierarchicalKey Parse(string s, IFormatProvider? provider = null)
```

Parses a string into a value.

### Parameters

- `s` (`string`): The string to parse.
- `provider` (`IFormatProvider?`): An object that provides culture-specific formatting information about `s`.

### Returns

The result of parsing `s`.

### Exceptions

- `System.ArgumentNullException`: `s` is `null`.
- `System.FormatException`: `s` is not in the correct format.
- `System.OverflowException`: `s` is not representable by `TSelf`.

## ToString {#tostring-d354ffe2}

[Dedicated page](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.hierarchicalkey/methods/tostring-d354ffe2/)

[Source](https://github.com/dotnet/orleans/blob/6a0e937f544c35ffcf11b37e4c2b7de5a1580a03/src/Orleans.Durable/Messaging/HierarchicalKey.cs#L216)

```csharp
public override string ToString()
```

Returns the fully qualified type name of this instance.

### Returns

The fully qualified type name.

## ToString(string?, IFormatProvider?) {#tostring-string-nullable-system-iformatprovider-nullable-2873d0f9}

[Dedicated page](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.hierarchicalkey/methods/tostring-string-nullable-system-iformatprovider-nullable-2873d0f9/)

[Source](https://github.com/dotnet/orleans/blob/6a0e937f544c35ffcf11b37e4c2b7de5a1580a03/src/Orleans.Durable/Messaging/HierarchicalKey.cs#L219)

```csharp
public string ToString(string? format, IFormatProvider? formatProvider)
```

Formats the value of the current instance using the specified format.

### Parameters

- `format` (`string?`): The format to use. -or- A null reference (`Nothing` in Visual Basic) to use the default format defined for the type of the `System.IFormattable` implementation.
- `formatProvider` (`IFormatProvider?`): The provider to use to format the value. -or- A null reference (`Nothing` in Visual Basic) to obtain the numeric format information from the current locale setting of the operating system.

### Returns

The value of the current instance in the specified format.

## TryFormat(Span&lt;char&gt;, int, ReadOnlySpan&lt;char&gt;, IFormatProvider?) {#tryformat-system-span-char-out-int-system-readonlyspan-char-system-iformatprovid-84e523ee}

[Dedicated page](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.hierarchicalkey/methods/tryformat-system-span-char-out-int-system-readonlyspan-char-system-iformatprovid-84e523ee/)

[Source](https://github.com/dotnet/orleans/blob/6a0e937f544c35ffcf11b37e4c2b7de5a1580a03/src/Orleans.Durable/Messaging/HierarchicalKey.cs#L224-L230)

```csharp
public bool TryFormat(Span<char> destination, out int charsWritten, ReadOnlySpan<char> format, IFormatProvider? provider)
```

Tries to format the value of the current instance into the provided span of characters.

### Parameters

- `destination` (`Span<char>`): The span in which to write this instance's value formatted as a span of characters.
- `charsWritten` (`int`): When this method returns, contains the number of characters that were written in `destination`.
- `format` (`ReadOnlySpan<char>`): A span containing the characters that represent a standard or custom format string that defines the acceptable format for `destination`.
- `provider` (`IFormatProvider?`): An optional object that supplies culture-specific formatting information for `destination`.

### Returns

`true` if the formatting was successful; otherwise, `false`.

## TryParse(ReadOnlySpan&lt;char&gt;, IFormatProvider?, HierarchicalKey) {#tryparse-system-readonlyspan-char-system-iformatprovider-nullable-out-orleans-du-0e48e9f8}

[Dedicated page](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.hierarchicalkey/methods/tryparse-system-readonlyspan-char-system-iformatprovider-nullable-out-orleans-du-0e48e9f8/)

[Source](https://github.com/dotnet/orleans/blob/6a0e937f544c35ffcf11b37e4c2b7de5a1580a03/src/Orleans.Durable/Messaging/HierarchicalKey.cs)

```csharp
public static bool TryParse(ReadOnlySpan<char> s, IFormatProvider? provider, out HierarchicalKey result)
```

Tries to parse a span of characters into a value.

### Parameters

- `s` (`ReadOnlySpan<char>`): The span of characters to parse.
- `provider` (`IFormatProvider?`): An object that provides culture-specific formatting information about `s`.
- `result` (`HierarchicalKey`): When this method returns, contains the result of successfully parsing `s`, or an undefined value on failure.

### Returns

`true` if `s` was successfully parsed; otherwise, `false`.

## TryParse(string?, IFormatProvider?, HierarchicalKey) {#tryparse-string-nullable-system-iformatprovider-nullable-out-orleans-durable-mes-1c69a3ca}

[Dedicated page](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.hierarchicalkey/methods/tryparse-string-nullable-system-iformatprovider-nullable-out-orleans-durable-mes-1c69a3ca/)

[Source](https://github.com/dotnet/orleans/blob/6a0e937f544c35ffcf11b37e4c2b7de5a1580a03/src/Orleans.Durable/Messaging/HierarchicalKey.cs)

```csharp
public static bool TryParse(string? s, IFormatProvider? provider, out HierarchicalKey result)
```

Tries to parse a string into a value.

### Parameters

- `s` (`string?`): The string to parse.
- `provider` (`IFormatProvider?`): An object that provides culture-specific formatting information about `s`.
- `result` (`HierarchicalKey`): When this method returns, contains the result of successfully parsing `s` or an undefined value on failure.

### Returns

`true` if `s` was successfully parsed; otherwise, `false`.

## operator ==(HierarchicalKey, HierarchicalKey) {#op-equality-orleans-durable-messaging-hierarchicalkey-orleans-durable-messaging-d6e3d65a}

[Dedicated page](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.hierarchicalkey/methods/op-equality-orleans-durable-messaging-hierarchicalkey-orleans-durable-messaging-d6e3d65a/)

[Source](https://github.com/dotnet/orleans/blob/6a0e937f544c35ffcf11b37e4c2b7de5a1580a03/src/Orleans.Durable/Messaging/HierarchicalKey.cs#L207)

```csharp
public static bool operator ==(HierarchicalKey left, HierarchicalKey right)
```

Compares complete ordinal key values.

### Parameters

- `left` (`HierarchicalKey`): The first identity.
- `right` (`HierarchicalKey`): The second identity.

### Returns

Whether the identities are equal.

## operator !=(HierarchicalKey, HierarchicalKey) {#op-inequality-orleans-durable-messaging-hierarchicalkey-orleans-durable-messagin-93f09b96}

[Dedicated page](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.hierarchicalkey/methods/op-inequality-orleans-durable-messaging-hierarchicalkey-orleans-durable-messagin-93f09b96/)

[Source](https://github.com/dotnet/orleans/blob/6a0e937f544c35ffcf11b37e4c2b7de5a1580a03/src/Orleans.Durable/Messaging/HierarchicalKey.cs#L213)

```csharp
public static bool operator !=(HierarchicalKey left, HierarchicalKey right)
```

Compares complete ordinal key values for inequality.

### Parameters

- `left` (`HierarchicalKey`): The first identity.
- `right` (`HierarchicalKey`): The second identity.

### Returns

Whether the identities differ.
