Ranges encapsulate the notion of a contiguous region of Word document content providing a multipurpose VBA tool to help us write better macros. We introduce VBA object concepts and move into explaining how to use and manipulate range variables.
Thanks for your interest
This content is part of a paid plan.
Introduction to Word VBA Ranges
We take another look behind the VBA curtain with Word Ranges. Using them will improve our macros because we can work with them covertly until we're ready to show the world (or the writer) our amazing edits. Toward that goal, we need to understand how they work, so we can use them more effectively. We set the stage with some important VBA concepts and then reveal some Range-specific details and examples. For a more official overview, see the Microsoft documentation, but the commentary is terse.
We’ve touched on Ranges in various macros, particularly in member articles, but we only needed a few details at a time usually related to the immediate command. The following (as well as many other articles on this site) will mostly consider text documents primarily aimed at creating practical macros for writing and editing novels, non-fiction manuscripts, and related notes documents. Many of the macros are nevertheless useful elsewhere.
What do we gain by using ranges?
Why should we use a Range over the Selection in an editing macro?
Several good reasons include:
- Create better, cleaner macros that have fewer side effects for the user
- Make changes to a document without changing the Selection unless that is part of the macro's purpose
- Compare content in a document and take different actions accordingly (intermediate)
- Manipulate content in different regions of one or more documents (intermediate to advanced)
- Create functions using ranges to extend our macro superpowers (intermediate to advanced)
For example, in many macros, it's nice to leave the initial position or selection in the document unchanged, so we can keep working without interruption. This feature was my main motivation for introducing Range variables in my own macros. We'll still use the Selection, but it will be reserved mostly for shorter, simpler macros where we’re already moving or changing the selection on screen.
What is a VBA object?
VBA represents various document elements as virtual "objects" which contain the data (called "properties") and actions (called "methods") associated with that type of document content. Typical object types include a Paragraph, Document, etc. Less obvious ones include a generalization of the Application or a document Range. We use the respective properties and methods to manipulate the object and any associated document content. Most objects are names according to the document element just capitalized.
What is a property?
Properties describe the specific data or information about that object type like Start or End positions for a Range, a Style for a Paragraph, etc. Sometimes we can only read the property information (literally called read-only), but often we can also use the property to change the setting. They almost always represent a setting of some sort, but certain properties (like the Find property of a Range variable) can feel more like a method when they are used since they perform an action.
What is a method?
The methods of an object usually act on its own properties or the related document content, but sometimes we can further access and act on other portions of the document.
Object variables
Important document elements for a macro are often identified and stored in a variable with that object type (imagine a Paragraph object for concreteness). We can then refer to the same document content at a later step and easily act on that content using the properties and methods of that object type.
What is the Selection?
The Selection is an important VBA object that represents the document selection or insertion point we see on the screen. It is like a specialized Range, but the Selection object includes extra properties and methods that are specific to what it represents on screen, or they make manipulating it more convenient. Only one Selection exists per document. For more on the Selection, see a separate introductory article.
What is a Range?
A Range in Word VBA is essentially a contiguous span of content in the document. It's much like an invisible document selection with Start and End positions (counted as the number of characters from the beginning of the document), but it also has other properties like the Style or Case which we can use to modify the content. Ranges also include methods that, among other tasks, allow us to control its extent or position in the document, insert or delete text, etc.
Some document elements like characters, words, sentences, or heading content are not VBA objects on their own. Rather, they're represented as document ranges when we need to work with them. We often access them through various collections like Characters, Words, or Sentences that indicate which content is fully or partially spanned by the range. Other methods such as Previous or Next return the requested content as a Range.
We can create as many Range variables as needed to implement the macro logic, but whichever approach we use to access a document range, we can then use the methods and properties to manipulate the respective content.
Selection and Range comparison
Ranges closely correlate to what we can do with the Selection when manipulating document content, but the accessible methods vary some. The short explanation is a Range is a general span of document content that is invisible to the user unless the macro changes the document. We can set as many Range variables as we need in a macro, but the Selection is a unique, specialized document Range.
Thinking about how we might manipulate the actual on-screen selection will take us a long way toward understanding Ranges in a macro. We can often implement the steps as if the Range variable were an invisible, independent Selection. However, we should still take advantage of the tools VBA offers rather than emulating the steps as if using the keyboard or mouse.
Common Range properties
In the context of editing macros, commonly used Range properties include:
- Text
- Text (plain text content)
- FormattedText (formatted text as seen on screen)
- Bold, Italic, and Underline (typical text formatting)
- Case, Font, and Style (character or paragraph)
- Collections of document content partially or fully spanned by the range
- Characters, Words, and Sentences
- Paragraphs
- Find (access all Find search features)
The above list is not exhaustive, those missing are more special purpose (which does happen) or usually outside the scope of typical manuscript editing. Examples include but are not limited to tables, fields, and lists.
Less common Range properties
Some other relevant but more specialized Range properties include:
- Other collections of content spanned by the range
- Bookmarks and Comments
- GrammaticalErrors and SpellingErrors
- Duplicate (creates an independent range spanning the same content)
Many other range properties exist, but all the above will carry us a long way in our editing macros journey.
Common Range methods
Some often-used Range methods include:
- Select (make the range the new document Selection)
- Delete (remove the content from the document without using the clipboard)
- Copy, Cut, and Paste (standard clipboard actions)
- Insert content
- InsertBefore and InsertAfter (insert plain text)
- InsertParagraph, InsertParagraphBefore, and InsertParagraphAfter
- Movement methods
- Move (typical unit-based movement)
- GoTo, GoToNext, and GoToPrevious (move to specific content types)
- StartOf, EndOf (constrained unit-based movement)
- MoveWhile, MoveUntil (character-based movement)
- Extension (or contraction) methods
- Collapse (empty the range)
- Expand (unit-based extension)
- StartOf, EndOf (constrained unit-based extension)
- MoveStart, MoveEnd (unit-based extension)
- MoveStartWhile, MoveEndWhile (character-based extension)
- MoveStartUntil, MoveEndUntil (character-based extension)
- SetRange (shorthand way to reassign the range with known positions)
- Next and Previous (access neighboring content)
It's a long list, but the various move and extension methods, for example, are all useful in different editing contexts.
Less common Range methods
Some other useful but more special case methods include:
- Specialized paste actions
- PasteAndFormat (reformat clipboard contents and paste into the document)
- PasteSpecial (specify details about the paste action)
- Test range variables
- IsEqual (check whether two ranges span exactly the same content)
- InRange (test whether one range is contained inside another)
- Insert special content
- InsertAutoText (insert a specific AutoText entry)
- InsertBreak (insert any content break)
More methods exist, but it would be cumbersome to include all of them. General omitted categories include methods to manipulate tables, lists, fields, and shapes.
Working with Ranges in VBA
Now that we know what VBA Ranges are and what they can do, how do we use them to carry out our amazing editing tasks. The following explanation is necessarily a brief summary of possibilities. Individual articles go into more detail about the properties or methods used when implementing practical and specific editing macros.
Declare a working range variable
In more complex macros, it's helpful to declare a working range variable which we change based on the needs of the macro.
We declare most variables in VBA with the Dim keyword, and "As Range" tells VBA what type of data the variable stores. I usually precede range variables with a lowercase "r" to remind myself what type of data it stores, but this is optional. VBA does not care about a specific variable name as long as we don't try to use one of it's reserved words like Dim or Range, and the name cannot contain spaces or punctuation other than a possible underscore _ character. If only one working range exists in a macro, I'll often just call it "r" for brevity, but I usually add comments to explain what it means and what is happening in the macro.
Do I need to declare my variables?
VBA doesn't require variables to be declared by default, but by default, all variables not declared explicitly will be a defined internally as a generic type (as a "Variant") that can represent anything.
Declaring variables is a good habit as our macros become more complex or when we want to be more careful.
- VBA requires explicit data types when "passing" data to a function, and functions accept Range parameters are a common category for useful editing macros.
- Being more specific with any variable types is clearer if you ever need to return to the macro. Why waste time remembering what you were thinking? On the other hand, adding descriptive comments is also clear.
- It helps prevent unintended consequences when VBA is blissfully ignorant of your human intentions. For example, VBA will treat a misspelled variable name as a new variable and just keep going. It's worse when the error does not cause the macro to crash, and we have to dig to find the error (wasted time).
- We also get a little help from the VBA editor where we can tab through property or method suggestions for a known variable type.
Force variable declarations
VBA does exactly what the macros steps say, not what we want them to do. If you want to force yourself to declare variables (which I do with most of my personal editing macros), add a line with Option Explicit at the top of the macro file.
It's Nothing (at the moment)
At this point, the working range r literally has a value of Nothing since it has not been assigned to a valid document range. If we try to use it to do anything meaningful—other than checking whether it is Nothing—before assigning it, the macro will crash and pop up an annoying error message.
Assigning a valid Range
If we wanted to create a numeric variable and assign it a value of 5, we'd do something like:
Ranges are objects in VBA consisting of various properties and methods, so we can’t just assign them like we do with numbers or plain text strings. We must instead "Set" the variable value.
Using Set ensures all the data defining the Range (technically, the Start and End positions along with the StoryType) are copied over when creating or modifying the new Range. In this example, SomeDocumentRange must refer to a valid document range. The data types on both sides of the equals = sign must agree, but some exceptions exist (with some number types, for example where VBA can automatically convert between them).
Setting a range based on the initial Selection
A common assignment near the beginning of the macro is to set a working range variable equal to the current selection whether it spans any content or is just an insertion point.
We need to refer to the Range property of the Selection since it is more than just a document range.
This is a convenient starting point for many macros since we often want to manipulate content near the initial selection or insertion point in the document. The working range r is now an independent range that just happens to span the same document content as the initial selection or insertion point.
Dynamic and fixed ranges … (slightly technical)
Technically, the above assignment sets a reference to the same document range spanned by Selection.Range. This is more subtle than it appears at first glance because typical range assignments literally refer to the same range (see below for more explanation), but the Range property references for many objects are regenerated automatically every time they are used.
This is called "dynamic generation" where we essentially get a new and independent range with each Range property reference. It seems to apply to any Word-state or Document-state objects such as the Selection, Application, ActiveDocument, etc. The above assignment seems to be a safe and consistent way to assign a new, but more importantly, an independent range variable. We explain below how to duplicate range variables to achieve an independent range.
Unassign a range variable
If a Range variable becomes invalid for any reason, we can literally set it to Nothing.
While this may sound pointless at first glance, we sometimes need a way to clearly indicate the working range variable is no longer assigned to anything valid in the document. Why?
- We want to ensure the variable cannot be mistakenly used later in the macro.
- We might want a function returning a document Range to indicate when it did not obtain a valid result or perhaps nothing happened inside the function based on the input data.
These are not fixed rules but rather a logical possibilities that may be used depending on the context. Setting the range to Nothing communicates that a change or maybe even an issue occurred. Sometimes it's a warning about a genuine problem, but at other times, it's just useful negative information about the document. Either way, the assignment gives us a clear value to test against before attempting other actions in the macro. After unassigning an object variable, the only valid use of the variable is checking whether it is Nothing.
Reassign a valid range variable
Several ways exist to change the extent of a range variable. Unfortunately, the changes below only work if the range is already valid, so it is common to initially set the range based on a known and useful valid range in the document.
Start and End positions
The Start or End properties are stored as character positions (counted from the beginning of the document). The positions are numeric values (as a Long number type), so they're just assigned using a regular equals = sign.
Often, we'll assign these positions based on known values from other document elements (perhaps a nearby paragraph's Start or End position). The Start position must be less than or equal to the End position, or VBA will automatically correct the conflicting position to be equal to the other one.
SetRange method
The SetRange method uses similarly named Start and End options to do the same assignments as above.
SetRange is slightly more convenient since we can assign it on one line.
Duplicating a range variable
We can also duplicate a range variable which is important when we want to copy a range but keep the original unchanged (perhaps for later comparison). Suppose we have two range variables rOne and rTwo where we want to copy the range rTwo into the rOne variable.
Danger Will Robinson!
If we just naively assign rTwo to rOne, it technically works but not in the way we would intuitively expect.
So, what's all the dangerous innuendo about?
This assignment will make the ranges span the exact same content—
Yeah … isn't that what we want?
Well, not quite. It's like calling me "Pete" (please don't) or "Peter", both names refer to me and any request of Pete necessarily affects Peter in the same way because they literally refer to the same person.
In the above assignment, the two variables literally refer to the same range as opposed to independent ranges that happen to have the same Start and End positions. Instead, any changes to rOne directly affects the other and vice versa. It's a strange default behavior in my opinion, and it caused me some consternation for a while until I found the (obvious) solution below.
Why would we ever want two variables referring to the same thing?
Skip to the assignment below if you do not want any details.
Would we ever want two variables that literally refer to the same document content?
Uhhh … it doesn't happen often.
One of the few cases (outside of function parameters mentioned below) might occur in large macros. We might want two conveniently named variables for different parts of the macro logic that carry out different tasks on the same range. The different sequences of steps would be easier to understand with clear and relevant variable names, but we might still want the range variables to be consistent when we're done.
Hmmm … like I said, it's a niche use case, so it probably shouldn't be the default behavior. However, I also think mint chocolate chip ice cream is the best flavor (maybe only by a smidgen), but only 8% of Americans agree with me (no convenient international statistics exist). Another mystery of the universe, I suppose.
For functions … (but we can ignore this aspect for now)
As an aside, one place where this referencing issue occurs often (and is even super useful in the process) is with functions and subroutines (let's focus on functions to simplify the language). Why?
We need the function to work with any range given to it. When a range variable is passed to a function (called an "argument" in that context), VBA automatically connects the passed range to the variable parameter name as it is used inside the function. Inside the function, we can use that local variable name knowing it refers exactly to the range argument given by the user. Such reference parameters are important for some data types since they are a more efficient way to provide information to a function.
In practice, I usually create an independent range inside my functions to avoid any unexpected changes to the user's external range variable. I then return a possibly updated range as the function result when appropriate. If the user wishes, they can update their variable with the new result which keeps them in control of the logical process in the external macro.
Assign independent ranges
If we want the rOne and rTwo ranges to be independent, we just use the Duplicate property in the assignment.
Now, the rOne range variable can be changed without affecting the extent of the rTwo range or vice versa.
Common Range methods
We summarized many of the Range variable methods earlier. Some of the more common examples follow with limited commentary. Specific macro articles will go into more detail about any methods or properties used. The commands use a working range variable named r for brevity.
Standard clipboard commands
We can Copy or Cut the range content to the clipboard:
For example, Cut will obviously remove the range content from the document and place it on the clipboard. Copy leaves the content in the document but puts it on the clipboard. Formatting is preserved in the cut or copy operation, but see the clipboard comment below before relying on these methods too much in general editing macros.
Paste into the document
We can also Paste the clipboard content into the document.
This method replaces the range content in the document, and the range will span the pasted content. To paste the content before or after the range, use the Collapse method first (see below).
Word has to interpret the clipboard content, so one of the more specific paste commands PasteAndFormat (along with a format constant) or PasteSpecial may work better in some circumstances.
These paste methods give us more control over how the action is implemented in the document.
Only use the clipboard when needed
As a best practice, use the clipboard only when it works well with the purpose of the macro.
Outside of purpose-built macros, only a few editing macros exist where using the clipboard is unavoidable to accomplish the intended macro task. Thus, it is poor macro-ing to use the clipboard as a logical crutch. If it's used when it shouldn't be, the clipboard contents may mysteriously change resulting is some confused squinting and blinking at the screen.
What's the problem?
Suppose we copy some of our wonderfully amazing dialog text, but make an intermediate edit. We happen to notice an error in the nearby description paragraph and make a quick edit that involves a macro shortcut or two. We move to the next scene and attempt to paste the copied dialog back into the novel … only the wrong text is inserted because a poorly written macro replaced the clipboard contents in between the actions.
Ughhh.
It's jarring and confusing for a moment. What happened? … Oh, that old description text … we groan and go back to recopy the dialog. Wasted time and effort.
It's even worse if we instead cut the dialog text from the document. The offending macro will replace the primary clipboard contents. When we paste, we get the wrong text, and the dialog is no longer in our novel. The editing veers into a crazy scramble to save our amazing dialog. In Windows, we can open the Office Clipboard if we remember it and paste the previously cut text. Otherwise, we smash the undo shortcut for the last several actions to restore the cut text to the document. Then we repeat the steps without using the offending macro.
It's a mess and annoying to boot, and it might even turn us off of using perfectly reasonable editing macros. Unnecessarily using the clipboard is also slower. Although, the actual speed difference would not be noticeable in most editing macros.
It can't be thaaat bad?
Is it the end of the editing world to use the clipboard if it makes the macro easier to write?
No … but it's momentarily confusing when a conflict arises, and we might waste time repeating previous edits. Using it too much is also a lazier approach since VBA usually offers better solutions. Finding that solution is often only a matter of perusing the lists of Range methods or properties to find the right tool for the task, or … just search through our article archive for some pointers. Member versions usually delve deeper into the topic and provide more advanced solutions.
Basically, use the clipboard when you need to do so and when it's consistent with the macro action(s), but don't use it when you don't need it.
Most common improper clipboard use … preserve text formatting
Besides dedicated cut or copy macros (say for Sentences or other document elements), probably the most common case where you would be tempted to use the Copy or Cut methods will be as a logical step in a macro that moves text in the document while preserving the formatting.
The most obvious and direct approach to copy text from one range position to another would use the Text property.
This assignment works fine if we only care about the plain text. If any formatting exists in the text, it will disappear in favor of the local text formatting.
We should not use the Copy method to preserve the text formatting.
If formatting is important, the FormattedText property is a better choice.
This assignment will preserve the formatting, even down to a character, as desired.
Delete the range content
We can delete the Range contents from the document using the Delete method.
This method is nice since it doesn't change the clipboard like the Cut method does.
Insert text at the range
We can insert plain text into the document using either the InsertBefore or InsertAfter methods.
These methods keep the range content intact and insert the new texts at the indicated position. The range automatically extends over the inserted text. Most plain text must be included in double quotes. Including the option name and the assignment symbol := as Text:= is optional since only one argument is allowed with these methods.
Text property approach
We could also just assign the Text property directly.
Since the Text property just stores plain text (as a "String" of characters), we use a regular equals = sign for the assignment. This version replaces the current range content which can save a step in some macros. The revised range will, of course, span the new text.
Insert gotcha with multiple ranges
When more than one range variable is involved, inserting text at the beginning of a range can result in some strange but accurate gotcha-like effects. The other ranges, even if they are independent, will automatically extend based on the Start position of the working range r. Normally this is okay and even expected, but when just the Start positions are shared, the result is a little counterintuitive (to me at least). We need to be aware of it and work around this behavior where it matters, but we'll address those cases in more detail as needed.
Insert a paragraph mark at the range
We can insert a paragraph break using any of the InsertParagraph, InsertParagraphBefore, or InsertParagraphAfter methods:
The first method replaces the range content with just a paragraph mark leaving the range to span just the new paragraph mark. The latter two just insert a paragraph mark on the respective side and extend the range to include it.
Text property approach for a paragraph mark
We can also include a paragraph mark with the Text option by adding (called "concatenating") the vbCr constant (from the miscellaneous constants table) to the new text using a plus + sign.
I tend to avoid this version unless it makes the macro more concise and usually only if I already have a String variable storing text for some other reason.
Move a Range variable
Ranges include several methods to move around the document based on the needs of a macro.
Which move method do we use?
Five general types of move methods exist in Word VBA. We list the desired move technique to the corresponding Range method(s).
- By a content unit → Move
- By a content unit but no farther → StartOf and EndOf
- To a specific document content type → GoTo, GoToNext, and GoToPrevious
- While certain characters are found near the range → MoveWhile
- Until certain characters are found near the range → MoveUntil
The Move and the GoTo methods sound similar, but they cover different aspects of range movement. For example, the Move, StartOf, and EndOf methods move by typical document element units. Content units are defined in a standard Word units table which includes the obvious character, word, sentence, paragraph, plus some more. The GoTo methods can jump by pages or even move to grammar errors, spelling errors, bookmarks, etc. The relevant content types are defined in a similar GoTo items table. Some move restrictions exist such as Ranges cannot move by lines in the document (only the Selection or the GoTo methods can do that).
Move method
For Ranges, the move methods are condensed into fewer commands compared to what the Selection offers, but we lose almost nothing in terms of capability. The main Move method for a range variable is:
We then specify the Unit based on the document units table which include the obvious wdWord, wdSentence, wdParagaph, and others. The movement direction is inferred by the Unit.
An optional argument of Count exists which controls how many units to move. Negative Count values move the range position backward in the document and positive values move it forward. For example, the following command moves the working range r location back by one or two paragraphs depending on the initial position in the paragraph.
The first backward paragraph step usually moves to the beginning of the current paragraph (unless the range is already there), and the second step moves to the previous paragraph.
The move action collapses the Range by default, so the Start and End positions are the same after the move.
Ranges cannot move by lines
One of the few drawbacks of using a range variable to manipulate document content is they cannot move by lines. Attempting to use the wdLine unit will cause an error. Moving up or down by lines within a paragraph only works with the Selection. The GoTo methods (see below) have a line option. It's a clunky command for such a simple move, but it works for lines if needed.
Constrained movement methods
The StartOf and EndOf methods work similar to Move except they will not move past the immediate unit at the range position.
This command moves to the beginning of the current sentence but no farther even if the range is already positioned there. These are useful in some macros when we want to ensure a specific location for any following actions or macro steps.
In Word VBA, the "start" of a unit is the same position as the "end" of the previous unit. This sounds obvious, but it does affect the logic in some macros.
GoTo methods
The GoTo method along with the convenient variations GoToPrevious and GoToNext allow us to specify certain content types to jump to their location in the document. It gives a different way to handle document navigation and can be used with bookmarks, standard Word headings, etc.; but a gotcha is waiting.
GoTo movement options
The GoTo method is one of the messier methods to use if we want to specify a general move.
- The What option as used above indicates the type of document content.
- It can further take a Which option from a GoTo direction table.
- Movements can be made relative to the range position using a direction.
- It will also accept an absolute position number for that particular document element type counting occurrences from the beginning of the document.
- A Count option is also accepted with intuitive uses depending on the relative or absolute context, but only positive values are allowed.
- If a Bookmark (or few other named document elements) is specified, we must provide a name using the Name option.
The GoToNext and GoToPrevious methods only accept a What option. All GoTo methods collapse the range by default unless we're jumping to a grammatical or spelling error.
GoTo gotcha with Range variables
Suppose the want to use the GoTo to move the Selection in the document.
This repositions the insertion point to the page as desired, but if we attempt to move the range r to the next page in the document, it does not work as expected.
Why doesn't it work?
When used with the Selection, GoTo and its sibling methods literally reposition the Selection in the document. We can remain blissfully unaware that they're also returning the same document range (a position usually) because the movement action is the effect we wanted. We don't need the returned result.
When GoTo is used with a range variable, it just returns the requested range result. GoTo does not automatically move the range variable position or reassign its extent in the document.
How can we make it work for a range variable?
Instead, we need to either assign the result to a range variable (below just uses the same range r) or just Select it using the range result to just make it the new document selection.
The only practical difference is the former redefines the working range r in the process. Otherwise, they have the same practical effect of moving the document selection.
Either example requires parentheses around the option argument(s), so VBA understands the command. This notation is necessary anytime we assign the returned result to another variable or if we need to reference a method or property of the returned result such as Select in the second example.
This behavior for the range version of the method is not incorrect, per se, but it may seem confusing when testing your macro if you expect it to actually move the range. The various Range Move methods actually move the range or change its extent in the document, and the method name GoTo is verb-like, so the assumption seems fair. I would prefer it act more consistently with the other move-like methods, but the problem is easy to correct even if it makes the steps look more programmy.
Character based movement methods
Additional move methods MoveUntil or MoveWhile allow us to move based on what characters are beside the range which is handy in some circumstances.
Both methods automatically collapse the range for the move. These methods require a character set option called Cset. We basically assign the desired plain text characters using a colon equals := symbol. Plain text strings are usually given in double quotes. Either command looks for any characters in the set. They do not look for the characters as a string. For example, if Cset is "xyz", the command looks for an "x" or a "y" or a "z", not all three together as "xyz". The latter is what the Find property does.
The default is to move forward in the document by any number of characters, but an additional constant wdBackward can be assigned to a Count option enabling the command to move backward by any number of characters.
Moving based on special characters
We can further include some special characters using a miscellaneous constants table. Two common characters are a paragraph mark vbCr and a tab character vbTab. We can include them in the character set using a plus + sign (called concatenation when "adding" text strings together).
This command skips across whitespace corresponding to typical characters not visible on the screen (unless non-printing characters are shown) which is handy in some macros.
Extend (or contract) the range
Another important feature of ranges is controlling the spanned document content. The behavior of a range mimics manipulating the visible selection on screen. However, the range extent is invisible to the user unless changes are made to the document content, or the range is explicitly selected.
Which range extension method do we use?
The extension methods are similar to the basic move methods above, but we have one version each for the Start and End positions of the range. We map the desired move technique to the corresponding Range methods.
- By a content unit → MoveStart and MoveEnd
- By a content unit but no farther → Expand (both directions), StartOf, EndOf
- While certain characters are found beside the range → MoveStartWhile and MoveEndWhile
- Until certain characters are found beside the range → MoveStartUntil and MoveEndUntil
The MoveStart, MoveEnd, StartOf, and EndOf methods move the respective side of a range by a typical document unit like sentences or paragraphs as defined in the standard Word units table.
Expand a range by a unit
We can directly expand the Range using the Expand method.
The Expand command is like a single step of the extend feature when pressing the F8 shortcut in Word, but we specify a unit directly. Expand only allows a restricted set of the typical document units. The nice thing about it is the range will not grow past the given Unit (pressing F8 repeatedly expands the selection up one unit size with each tap).
In practice, the range extends outward both directions from its Start or End positions to the previous or next given unit, respectively. As a result, the expanded range could span more than one unit depending on whether the initial spanned content crossed a unit boundary. It is generally a side effect, but occasionally, we can take advantage of this implicit behavior to improve our macros.
Extend a range by a unit
We can also just extend or contract the Start or End position of a range using the MoveStart or MoveEnd methods.
We specify a unit as with the Move method above. We can also specify a Count option to indicate how many units to move the respective position. The default step is by one unit forward or +1. Negative Count values indicate movement backward in the document, and positive values indicate movement forward in the document. The direction implied by the Count option works the same for both sides of the range, so it will expand or contract the range accordingly.
If the Start position moves past the End position, the End position is set equal to Start which effectively collapses the range. The opposite occurs if the End position moves backward past the Start position of the range.
For extensions with larger document elements, the first step will often move to the respective beginning or ending of the unit, and the following steps will take full unit-sized steps. The exception is if the respective range position starts at a unit boundary.
Extend a range based on document text
The specialized move commands MoveStartWhile, MoveEndWhile, MoveStartUntil, and MoveEndUntil combine the behavior of the similarly named move methods above. These methods allow us to adjust either the Start or End positions of the Range based on which characters border the range.
Character extension options
Each method requires a character set assigned to a Cset option using the colon equals := symbol. The method will check the neighboring document text against the given character set.
The "While" versions move the respective side of the range as long as it keeps finding any of the indicated characters on that side of the range. Conversely, the "Until" versions extend or contract the range past all characters, but it stops when it finds any of the characters in the set.
An optional Count argument specifies the maximum number of possible characters to move which defaults to as many as possible. For all four methods, a negative Count value moves backward in the document, and a position value moves forward. Thus, the methods can either extend or contract the range depending on which is side is being moved which direction. A special constant wdBackward tells the command to move any number of possible matches backward in the document.
Extend (or contract) range over specific characters
The two MoveStartWhile and MoveEndWhile methods move the respective range position as long as it keeps finding characters in the document that match those in Cset.
As with the previous move methods above that use a character set, we can include special characters using the miscellaneous constants table. Common special characters include a paragraph mark vbCr and a tab vbTab, and we add them to the plain text string using a plus + sign.
Extend (or contract) range until specific characters are found
The MoveStartUntil and MoveEndUntil methods do almost the opposite. They move the respective range Start or End position until it finds a character in the document that matches any character in the Cset option.
Possible uses
At first glance, these methods be seem unnecessary, but they're exactly the right tool for certain tasks. For example, they're often useful when excluding or working with document whitespace (spaces, paragraph marks, or tabs). We can also use them to smartly handle double quotes in dialog or parentheses or just sentence punctuation in general in other working documents.
