When working on macros, we sometimes need to know whether a range is empty or perhaps whether it contains only whitespace characters.
Thanks for your interest
This content is part of a paid plan.
Is a document range empty or whitespace?
When creating VBA macros, the logic occasionally requires us to know whether a range is empty, or in more general circumstances, whether it contains only whitespace characters.
Functions make creating more complex and more useful macros easier and safer. With this function, we can just "ask" whether the range in question is empty or just whitespace and make the appropriate decision in the macro. We don't need to reinvent the wheel each time by embedding the same set of test steps just tweaked to match the specifics of the current macro.
These functions provide a useful pair of tools for our own little VBA toolbox. Depending on the specific needs of a macro in progress, this function parallels a sibling macro to check whether a paragraph is empty, but the details for ranges are a little different.
If you prefer to skip the background details, jump down to the initial validation check or the main function steps.
Create the function skeletons
Open the VBA editor and create the following function skeletons.
The single quote tells VBA the rest of the text on that line is a comment meant for human readers. For later reference, functions should include at least a description of what it does, the parameters, and the meaning of the result. We start our steps on the empty line.
Depending on the specific macro logic, detecting a strictly empty range or one containing only whitespace are both useful choices, so we're implementing both. The former is short and simple, so we begin with it.
Parameter
Both functions require a single Range parameter which is the document range to test. Any external macro (essentially) must provide a range variable, or it will create an error. No changes will be made to the WhichRange parameter inside either function.
As we write the function steps, we simply refer to the WhichRange name, and VBA automatically references the data provided by the external macro. By default, any changes to the Range variable inside the macro will affect the argument outside the function. Unless this is a desired effect (not recommended), we can create a duplicate of the range inside the function to avoid any issues.
Returned result
The result is a True or False (called a "Boolean") value based on whether the given range is empty or not. The first version strictly tests for an empty paragraph containing literally no text or special characters, but see the following comments because this is a tad more involved than it seems at first glance. The second function includes extra steps to verify only spaces, tabs, or paragraph marks are present in the range, but the result is still a Boolean value answering the question.
Anytime before the function ends, we need to assign the result to the function name like a typical variable assignment of that type.
The sibling article to check whether a paragraph is empty talks more about the invalid condition with a Boolean variable as opposed to a valid but False result.
What is an empty range?
Before we can answer the yes or no question to get the function result, what does "empty" mean for a Range? This question is subtle for ranges, but we'll stick to the basics.
A Range variable is partly defined by Start and End positions in the document. Of course, it contains other methods and properties, but we're mostly interested it its left and right positions for these functions.
How does Word define a document position?
Word marks an absolute document position based on its character count from the beginning of the document. The position data type is a Long which means its like a regular Integer, but it allows a larger maximum value (and requires more memory storage). If two position variables have the same value, they're at same position in the document.
Range character caveat
All VBA Range variables technically contain at least one character even if the Start and End positions are equal. Specifically, an empty range would still contain the character immediately to its right. Unfortunately, a range than spans one character also contains … one character.
It's not quite a contradiction, but it's definitely counterintuitive. For this macro, it means we cannot use the character count to validate an empty range.
Ughhh.
Empty paragraph condition
I find the issue annoying, but we can sidestep the inconsistency by just checking whether the Start and End positions are the same. If so, the range is empty in the strict sense.
What are whitespace characters?
For a writer, a range might be intuitively empty if it contains no meaningful text. One obvious case corresponds to whitespace characters. In Word, a practical definition of typical whitespace includes spaces, tabs, and paragraph marks.
For my own macros, I would define this string as a global constant since it pops up in various macros and functions. While nearly trivial to assign, such a constant is outside the scope of this article, but see an example applied to punctuation marks if this slight simplification sounds interesting.
Other whitespace characters (not used)
Whitespace technically also includes various content break characters, a non-breaking space, and some formatting marks. A few relevant but less common characters are testable in the same context as the above characters. If we want to include them as whitespace, we would further concatenate any or all the following:
- Manual line break (user entered) → ChrW(11)
- Page break → ChrW(12)
- Non-breaking space → ChrW(160)
Manual line breaks are not necessary when using the various MoveWhile or MoveUntil methods unless the user specifically used the standard Word shortcut Shift+Enter to create one. Regular line breaks inserted by Word for screen display are ignored in VBA (except for some movement methods mostly with the Selection). A similar logic applies to page breaks. We only need to worry about manual page breaks entered by the user, but Word typically inserts a paragraph break along with the manual page break anyhow.
Most other whitespace attributes are modified through relevant VBA methods. They are represented by internal Word formatting and not as a single character spanned by a range, so we will ignore them. Anchors for floating or inline shapes and other related content are also invisible, but they are positioned as zero-width characters and cannot be directly manipulated in the range.
Detecting an empty range
A strictly empty range is easy to test, but we need to take a quick detour to avoid a possible error. We don't want to stub our toe (encounter an error that will immediately crash the macro) right out of the starting gate.
Check for invalid range
When creating a function, we should always consider whether the data being given to it is even valid. A rough conditional statement might look something like:
How do we check for an invalid range? In this function, we have a single range parameter WhichRange.
It may seem a little strange to test for an invalid variable as the main case, but this is often performed in the context of preventing possible errors. The rest of the macro steps usually (but not always) follow the validation check.
Is the Range Nothing?
VBA assigns a value of Nothing to any variable representing an object that is not yet assigned to a valid document element.
In VBA, we do not compare to objects to each other using an equals = sign. Instead, they are compared using the keyword Is. Since a Range is an object in VBA, the Is keyword is used to test whether two Ranges refer to the same thing (we won't mention any fancy terminology). This carries over to checking whether a range variable is Nothing.
Thus, we literally use Is Nothing to see whether WhichRange is not yet assigned to a valid document range.
For extra clarity, if this condition is True, the WhichRange argument is invalid, and False corresponds to valid. This is another place where VBA strives to make VBA more approachable than some other "scripting" languages.
Set the invalid result
If the WhichRange argument is invalid, we need to set the function result to False.
While VBA will assign a default value to the function result, relying on default values is sketchy and asking for trouble somewhere down the line. We should always clearly and explicitly assign the result before exiting the function.
Exit the function
What do we do if the given WhichRange argument is invalid? We just exit the function.
This command ends the function immediately which is why we needed to assign the function result first. No steps after this line are run.
Invalid range conditional statement
We combine the above commands with the earlier proposed conditional statement. Some macros will include some steps to run in each of the invalid and valid cases. If so, we include the Else (otherwise) part into a longer If-Else statement.
Often, the rest of the macro corresponds to the "valid steps," so the Else part may be omitted for convenience. We then focus the conditional statement on handling only the invalid steps and just let VBA continue with the rest of the macro if WhichRange is a valid variable.
This validation should be tested before anything other actions are attempted with the WhichRange variable. If not, the macro will crash, and VBA will pop up an annoying error message. As a result, many such validation checks are placed at the top of the function, so it is easier to just exit the function immediately if a problem is found with the variable.
Any other tests?
Speaking generally, if we have more information about the specific or expected document status, we could add extra tests. Anything we catch here will just might save us from future trouble. After passing the validation check(s), we can be more assured the rest of the macro steps have a valid starting point.
Of course, conditional statements are much more general than just validation checks, so see our brief introduction in a separate article for more information.
Is the range strictly empty?
We're given a document Range variable WhichRange (called an "argument" when the user provides it to the function). If the range is strictly empty, then the Start and End positions are the same. This gives us a clear True or False condition to answer the question posed by the function.
We already know WhichRange is a valid Range, so we can just refer to the respective Start and End position properties.
If the paragraph is empty in the strict sense, we're asking whether these two positions are the same in the document. We create the condition that answers this question.
This looks like an assignment, but in a conditional statement (e.g., such as an If-Then statement), VBA will interpret it as a Boolean value.
Is the range only whitespace?
Empty in the intuitive sense could include not spanning any meaningful text in the range. Of course, allowing this condition is a preference, but it's a reasonable and natural one. So, rather than requiring the range to be strictly empty, we could instead allow "whitespace".
Practically in novel, whitespace would consist of spaces (ignoring non-breaking spaces), paragraph marks, and tabs. General ranges can span any amount of document content in any combination, so we have some work to do to properly validate whether only whitespace characters exist within a range.
How do we detect whitespace?
We need to check whether each character in the range is one of the above characters. A naive approach might manually check each character in the range, but this is more complicated than necessary (don't tell anyone this is how I implemented my first version of this function). Instead, we can take advantage of a convenient VBA Range method.
What's the better way to detect whitespace?
With broad brush strokes, the idea is to compare the original range to a range designed to span all whitespace in the same region. The logic is simple, but it might cause you to tilt your head at first, so let's work through it before looking at the VBA steps. What are the basic steps?
- Duplicate the given range into another working range variable which also leaves the original unchanged for later comparison
- Collapse the working range, so we know it is positioned precisely at the start of the original range
- Extend the working range forward in the document across any whitespace characters
- Compare the two ranges to see if the original range is contained inside the working (now whitespace) range
Declare our working range
The function already declared the original input range variable as WhichRange. We need a second working range which we will manipulate to span all whitespace near the original. We'll call it rSpace.
Dim is the VBA keyword to declare variables, and "As Range" tells VBA what type of data type is stored in the variable. Stating the data type is necessary, or it will default to a generic "Variant" type (which can be anything). I like to precede Range variables with an "r" to remind myself what type of data they store (yeah, I know I broke this "rule" for WhichRange). After this, VBA knows rSpace is a Range, and we have access to anything a Range can do.
Assign the working whitespace range
We want the whitespace range to begin at the same initial position as the original range.
It looks good at first … but it doesn't work as expected. The range is indeed set to the original, but as assigned, they literally refer to the same range.
It's like two kids holding onto the same toy when both want to play with it. Awkward. Anything one kid does affects the other kid. It would be nice if both kids had the same, but physically different toys. Then both of them are happy.
With this assignment, any changes to rSpace will also change WhichRange and vice versa. It's even worse because any changes to WhichRange will also leak outside the function! We need our function to be self-contained and just give the overall result (a True or False value answering the question).
Arghhh.
That's not what we want (especially the outside the function stuff).
Duplicate the original range
We need the original to stay unchanged, so we can compare our whitespace range to it later. Fortunately, we can assign an independent range using the Duplicate property.
Collapse the whitespace working range
We only want to work from the beginning of the range (see next command below), so we use the Collapse method.
The default direction is to collapse toward the Start position (left side) which is what we need for this macro.
Extend over any whitespace characters
We have an empty working range rSpace (Start and End positions are the same) positioned at the beginning of the original WhichRange argument. We need to extend the End position of the working range forward in the document across any whitespace. The appropriate command is the MoveEndWhile method.
This command does not change the Start position. Thus, if any whitespace characters are found, the range extends to the right in the document.
These Move "While" or "Until" methods all need a set of characters to check against in the document. These are stored in a Cset option.
We want whitespace, and a space character is literally just " " in double quotes.
A paragraph mark and a tab are special characters, but we can get them from a miscellaneous constants table. The constants are vbCr and vbTab, respectively. We need to "add" (called concatenate for plain text strings) them together with the other characters using a plus + sign.
Now the rSpace working range will span any whitespace beginning from the Start position of the paragraph. The remaining question is whether rSpace is smaller, the same, or bigger than the original paragraph range.
Any other whitespace characters?
These characters handle typical whitespace in a manuscript, but if you want to add a few other whitespace-related characters like non-breaking spaces or manual, user-entered line breaks, see the comments on the topic near the top.
Compare the two ranges
How do we check whether one range is inside another one?
Any Range variable has a convenient InRange method to check exactly this condition.
More specifically, InRange checks whether the range on the left is inside the range inside the parentheses. The test is not strict in the sense that the respective Start, End, or both positions could be the same and still be considered "inside" by the method. The result is a True or False value answering the question.
Alternative approach to compare the ranges
Both working ranges have the same Start position by design, so we could just compare the End positions directly. Specifically, the original WhichRange is inside the whitespace range if the End position of rSpace is greater than or equal to the End position of WhichRange.
It's a matter of preference, but the InRange version just looks nicer. This one looks too much like programming. Blehh.
Assign the function result
We need to tell the function the result of our comparison. In VBA, we just assign the InRange result to the function name.
A value of True means the WhichRange is inside the working whitespace range rSpace. InRange gives a False result if any part of WhichRange is outside of rSpace which is exactly what we need for this macro.
Final functions
We have two main variations for an empty range.
Strictly empty range function
Putting the steps together for a strictly empty range, we have:
The extra parentheses on the result check are just for extra clarity. VBA would still properly interpret the right side as a True or False result.
This version is trivial enough that the validation check is longer than the function result. That's a little annoying, but we tidied it up as best we could and just jammed everything together into one conditional statement. Since the conditional statement is checking for a valid range argument, including an Else part corresponds to a valid WhichRange argument.
Range is only whitespace function
The more general version checking whether the original range is empty or if it contains only whitespace is:
Fortunately, this version also catches a strictly empty range, so we only need to use the one that applies in our current macro.
At a concept level, checking whether WhichRange is only whitespace seems like a simple enough task, but see how messy it gets quickly? Packing all this into a separate function makes the main macro easier to read.
