Important: MessageSet Is an IMAP Helper Class

Chilkat.MessageSet is not intended to be a general application collection class. Its purpose is to hold message UIDs or sequence numbers used by Chilkat.Imap. For example, an IMAP search may return a MessageSet, and another IMAP method may accept a MessageSet to fetch, copy, delete, or otherwise operate on those messages.

Used with IMAP Holds message identifiers for Chilkat.Imap operations.

UIDs or Sequence Numbers The HasUids property identifies whether the set contains UIDs or message sequence numbers.

Compact Ranges Convert between comma-separated lists and compact IMAP-style ranges such as 1:5,8:10.

Set Operations Insert IDs, remove IDs, test membership, subtract one set from another, and access IDs by index.

Typical Workflow

Obtain a MessageSet from an IMAP operation, such as a search, or create one to pass to an IMAP method.
Check HasUids to know whether the set contains UIDs or sequence numbers.
Use Count to determine how many message identifiers are in the set.
Use GetId to retrieve individual identifiers by zero-based index.
Use InsertId, RemoveId, or Subtract to modify the set if needed.
Use ToCompactString or ToCommaSeparatedStr when a string representation is needed.
Check LastErrorText if an operation fails or behaves unexpectedly.

UID vs sequence number: Always check HasUids. A numeric value in a MessageSet represents either a UID or a sequence number depending on this setting.

Core Concepts

Concept	Meaning	Important Members
Message Identifier	A number identifying an IMAP message. It may be a UID or a sequence number.	HasUids, GetId, InsertId
UID Set	A message set where identifiers are IMAP UIDs.	HasUids = true
Sequence Number Set	A message set where identifiers are IMAP message sequence numbers.	HasUids = false
Compact String	A range-compressed representation of message IDs, such as 1:5,8:10.	FromCompactString, ToCompactString
Comma-Separated String	A non-compact representation such as 1,2,3,4,5,8,9,10.	ToCommaSeparatedStr
Set Difference	Removes all message IDs in one set from another set.	Subtract

Properties

Property	Purpose	Guidance
Count	Number of message UIDs or sequence numbers in the set.	Use before iterating by index.
HasUids	Indicates whether the set contains UIDs or sequence numbers.	If true, the set contains UIDs. If false, it contains sequence numbers. This matters when passing the set to IMAP methods.
LastErrorText	Diagnostic information for the last method or property access.	Check after failures or unexpected behavior. Diagnostic information may be available regardless of success or failure.

Adding, Removing, and Testing IDs

Method	Purpose	Important Details
InsertId	Inserts a message ID into the set.	If the ID already exists, a duplicate is not inserted.
RemoveId	Removes a message ID from the set.	Use to exclude a single UID or sequence number from the set.
ContainsId	Tests whether a message ID is contained in the set.	Returns true if the ID is present.
Subtract	Removes all message IDs in another MessageSet from the caller's set.	Useful when one IMAP result set should be reduced by another result set.

No duplicates: InsertId will not insert a duplicate ID when the same identifier is already present.

Retrieving IDs

Method	Returns	Important Details
GetId	The message ID at the specified index.	Indexing begins at 0. Returns 0xFFFFFFFF if the index is out of range.
Count	Number of IDs in the set.	Use Count to avoid calling GetId with an out-of-range index.

Index note: Valid indexes are 0 through Count - 1.

Compact and Non-Compact String Formats

A MessageSet can be represented as a simple comma-separated list or as a compact range string. Compact strings are especially useful when a set contains consecutive message IDs.

Non-Compact String	Compact String	Meaning
1,2,3,4,5	1:5	IDs 1 through 5.
1,2,3,4,5,8,9,10	1:5,8:10	IDs 1 through 5 and 8 through 10.
1,3,4,5,8,9,10	1,3:5,8:10	ID 1, IDs 3 through 5, and IDs 8 through 10.

String Conversion Methods

Method	Direction	Behavior
FromCompactString	Compact string to message set.	Loads the set from a compact range representation such as 1:5,8:10.
ToCompactString	Message set to compact string.	Returns the set represented as compact ranges.
ToCommaSeparatedStr	Message set to comma-separated string.	Returns the set in non-compact form, such as 1,2,3,4,5.

Method Summary by Category

Category	Methods / Properties	Purpose
Identify the set type	HasUids	Determines whether the set contains UIDs or sequence numbers.
Inspect and retrieve IDs	Count, GetId, ContainsId	Count IDs, retrieve IDs by index, or test membership.
Modify the set	InsertId, RemoveId, Subtract	Add one ID, remove one ID, or subtract another message set.
String conversion	FromCompactString, ToCompactString, ToCommaSeparatedStr	Load or emit compact and non-compact string representations.
Diagnostics	LastErrorText	Read diagnostic information after failed or unexpected operations.

Diagnostics and Troubleshooting

Problem Area	Member	What to Check
IMAP method behaves as if IDs are wrong	HasUids	Confirm whether the set contains UIDs or sequence numbers, and ensure the receiving IMAP method expects the same type.
Unexpected out-of-range value from GetId	GetId, Count	GetId returns 0xFFFFFFFF if the index is out of range. Check Count before indexing.
Duplicate ID was not added	InsertId	Duplicate IDs are intentionally not inserted.
Compact string does not load	FromCompactString, LastErrorText	Verify the compact string format, such as 1:5,8:10, and inspect diagnostics if loading fails.
Subtract removes more or fewer IDs than expected	Subtract	Confirm that both message sets refer to the same kind of identifiers: either both UIDs or both sequence numbers.
Need operation details after failure	LastErrorText	Check diagnostic text after failed or unexpected parsing, task loading, or message set operations.

Common Pitfalls

Pitfall	Better Approach
Treating MessageSet as a general-purpose collection.	Use it specifically as an IMAP helper object for message UIDs or sequence numbers.
Forgetting to check whether the set contains UIDs or sequence numbers.	Check HasUids before passing the set to an IMAP method.
Assuming GetId uses 1-based indexing.	Indexing begins at 0.
Assuming duplicate IDs can exist in the set.	InsertId prevents duplicates.
Mixing UID-based and sequence-number-based sets.	Keep sets consistent. Do not subtract or pass sets together unless they use the same identifier type.
Ignoring diagnostics after unexpected behavior.	Check LastErrorText for details.

Best Practices

Recommendation	Reason
Use MessageSet only with Chilkat.Imap workflows.	The class exists to pass and return sets of IMAP message identifiers.
Check HasUids before using the set.	IMAP UIDs and sequence numbers are both numeric, so the flag determines how the numbers should be interpreted.
Use Count before iterating with GetId.	It avoids out-of-range access and the 0xFFFFFFFF out-of-range return value.
Use ToCompactString for readable range output.	Consecutive IDs are easier to read and pass around as compact ranges.
Use ToCommaSeparatedStr when every ID should be listed explicitly.	The non-compact format is useful for debugging or displaying the exact IDs.
Use Subtract only with sets that use the same identifier type.	Subtracting UIDs from sequence numbers, or the reverse, produces meaningless results.
Check LastErrorText after failures.	It provides useful diagnostic detail for failed or unexpected message set operations.

Summary

Chilkat.MessageSet is an IMAP-specific helper class used by Chilkat.Imap to pass and return sets of messages. It stores numeric message identifiers, where the identifiers are either UIDs or sequence numbers depending on HasUids.

The most important practical guidance is to treat this as an IMAP message-ID set, not a general-purpose collection; always check whether it contains UIDs or sequence numbers; use Count before calling GetId; use compact strings for concise range representation; and inspect LastErrorText whenever a message set operation fails or behaves unexpectedly.

Chilkat.MessageSet Class Overview