In some Word macros, we need to know whether a paragraph is empty or perhaps whether it contains only whitespace characters before we can continue the rest of the macro steps with confidence. We create two VBA functions to answer the questions.
Thanks for your interest
This content is part of a paid plan.
Is a document paragraph empty?
When creating editing macros, we occasionally need to know whether a paragraph is empty before we do something with it. A natural extension allows whitespace characters as part of the definition, but how can we detect either case?
Creating a good function sometimes feels like we're a carpenter crafting new furniture. We want a stable chair we can just sit in it and enjoy dinner without worrying about the chair, but the details can make it a bit wobbly. Every leg the correct length and angle and mounted securely to a well-formed seat …
Sound fun yet?
Yeah, it's some extra work, but once it's finished, that shiny new VBA function will make bigger and better macros easier to create and understand. We just ask the function whether the paragraph in question is empty without worrying as much about the details. We then use the answer to make an appropriate decision in the main macro without needing to reinvent the wheel (or chair) every time.
Depending on the specific external macro needs, this function parallels a sibling macro which checks whether a range is empty, but the details for a paragraph are a little different.
If you prefer to skip some of the background details, jump down to the initial validation check, the main function steps, or even the finished functions if you just want to take the chairs home.
Create the function skeletons
Open the VBA editor and create the following empty functions.
The single quote tells VBA the rest of the text on that line is a comment meant for human readers. Given that someone (probably us) needs to understand how to use the function, it should include a description of its purpose, the required (or any optional) parameters, and the meaning and type of the return value; but VBA does not require this information. We start our function steps on the empty line.
Parameter
Both functions accept a single Paragraph parameter WhichParagraph which is the document paragraph it will test. No changes are made to the variable inside either function. As we write the function steps, we simply refer to the WhichParagraph variable, and VBA automatically references the data provided by the external macro.
Taking advantage of the data type
This is a brief example of why VBA defines "object" data types for certain document elements. We specified the data provided to the function must be a Paragraph meaning the VBA object thingy that internally represents a document paragraph. Anything else will be rejected (causing an error in the external macro).
With that restriction, we are sure of the data type for WhichParagraph inside the function, so we know which methods or properties are available as we work with it. We can further take advantage of any related constraints as we work through the function logic. For example, WhichParagraph cannot contain more than a single paragraph, even partially. Otherwise it would be a Paragraphs collection data type. Being aware of this restriction makes some of the macro steps easier or at least more focused, so we don't need to consider as many cases.
Invalid paragraph?
Since we're working with a Paragraph object, an external macro may unintentionally give our function an invalid Paragraph variable (probably not yet assigned to anything in the document). We will need to account for an unassigned (invalid) paragraph variable before taking any action with WhichParagraph.
Returned result
The result of the function is a True or False value answering whether the given paragraph is empty or not. In computer speak, it is called a "Boolean" data type. The first function strictly tests for an empty paragraph containing only a single paragraph mark, and the second includes extra steps to allow whitespace in the form of spaces or tabs.
Anytime before the function ends, we need to assign the result to the function name as if it is a regular variable assignment (which it basically is).
Invalid result discrepancy?
Let's dig into some slightly more technical stuff for a few moments to make a point, but skip ahead if you are not interested in any details (yet).
If the external macro passes a Paragraph variable that isn't yet assigned to a document paragraph, we have a problem. Avoiding the issue is "simple," which we do below, but we still have a question about the proper result to report in that case.
What is the correct result for an invalid argument?
Is False the correct result for an invalid WhichParagraph argument?
Clearly, the function can't return a True result since WhichParagraph is not even a valid paragraph, but even a False result still implies the function did the test and found some regular text in the paragraph. That's not correct either, and it's a problem because the external macro may continue with its own steps while assuming text is present in a paragraph that doesn't even exist in the document.
Once could argue that is the fault of the external macro, and it mostly is, but the result would be clearer if we could communicate some kind of invalid result distinct from True or False. Unfortunately, Boolean variables are either True or False (actually stored internally by VBA as numbers).
Invalid result workaround?
If the function result were a generic type or maybe an object type, we could assign some kind of "no-result" result (depends on the variable type) to indicate an invalid WhichParagraph argument. This would allow us to distinguish between: "Hey, we checked the paragraph, and this is a False but valid result," and the third option, "Nope, what you gave us is garbage," kind of result.
The best solution is probably to return a Variant type instead of a Boolean value since a Variant variable can be assigned an "Empty" (not the same thing as the paragraph being empty) or "Nothing" value as well as store True or False values. A Variant can even be used in conditional statements like a Boolean value.
Unfortunately, it's a little vague and messy for the difficulty level of this article, so we'll just acknowledge the issue and move on for now. The external macro is responsible for knowing its own paragraph variable is valid and refers to some real document content, but we add an extra comment in the function description text to clearly indicate what happens when the function receives an invalid Paragraph argument.
What is an empty paragraph?
Before we can answer the yes or no question to get the function result, what does "empty" mean for a paragraph?
In Word, all paragraphs contain at least a paragraph mark, so a strictly empty paragraph implies no other characters are present. This provides a way to identify an empty paragraph with a clear yes or no (True or False) answer to the question posed by the function.
Do we allow whitespace?
In word processing, an empty paragraph in an intuitive sense might also include simply not seeing any text in the paragraph. This might occur when a space is typed inadvertently in a paragraph or some paragraph text is not completely deleted. It would be nice if our editing macros handled this possibility naturally rather than being strict about it.
Invisible characters on screen are commonly called whitespace literally because a typical screen is white in that area (of course, serious writers use dark mode; just kidding, but the bright screen is hard to look at for hours at a time). These characters usually consist of spaces, paragraph marks, and tabs. The sibling function detecting empty ranges discusses whitespace in a little more detail particularly if you want to include non-breaking spaces or manual line breaks in your testing.
Strictly empty is technically correct, but intuitively we should also allow whitespace characters as needed by the external macro based on how the writer prefers it. Since both are valid choices, we'll implement both. The first is short and simple, so it's not much extra work.
Is the paragraph strictly empty?
Our function is given (called "passed") a document Paragraph (called an "argument" when it is passed to the function). Our first goal is to detect if it is empty in the strict sense.
How can we identify an empty paragraph?
All paragraphs in Word contain at least a paragraph mark. If the paragraph is strictly empty, then only that character is present. More specifically, if the paragraph contains a single character, the paragraph is empty. If not, it's not empty. This condition provides a clear True or False answer to the function question.
Get the number of characters in the paragraph
We need to determine the number of characters in the given paragraph, but a Paragraph object in VBA does not store this information directly. Rather, a Paragraph variable stores information about the settings and such that define formatting, layout, etc.—paragraph related stuff.
Therefore, we first refer to the Range property of the Paragraph variable which stores the specific information we need for this function.
The Characters collection of the range variable stores all characters as well as the number of characters in the range.
In this function, we only need to know how many characters are in the paragraph which we get by referring to the Count property of the collection.
What is the empty paragraph condition?
If the paragraph is empty in the strict sense, we want to check whether character Count has a value of one. The condition is:
This looks like an assignment, but when used in an If-Then statement (and a few other others), VBA will interpret it as a Boolean value.
Assign the function result
Now, just assign this True or False value to the function name to return the result.
The extra parentheses are just for clarity. VBA would still properly interpret the right side as a Boolean value before assigning it as the function result.
Is this the best way?
We could alternatively test the paragraph text against a paragraph mark character, but these approaches are equivalent. We only need one test that works.
Is the paragraph only whitespace?
Empty in the intuitive sense might include a writer not seeing any text in the paragraph.
How do we detect whitespace?
For a single paragraph, we need to check whether each character in it is a space, a paragraph mark, or a tab character. The sibling function detecting empty ranges discusses whitespace in a little more detail particularly if you want to include non-breaking spaces or manual line breaks.
This whitespace version includes a strictly empty paragraph as a special case since a single paragraph mark is also whitespace.
Do we ignore the paragraph mark?
We're only working with a single paragraph in this function, so it is tempting to ignore the paragraph mark at the end of WhichParagraph. We know it is present and where it is located, so why not just focus on tabs and spaces?
It makes sense, and it could work if the logic is built around it, but it doesn't save us any work or improve the macro in any significant way (perhaps maybe a tiny, itty bitty, vanishingly small efficiency boost). In fact, the assumption actually messes the nice range comparison result below, so it's easier and clearer to just leave paragraph marks in the whitespace detection logic. We explain the details more below when covering the specific command used.
Just say no … to checking every character
The direct (but more naive) solution to detect whitespace is to just check every character (don't tell anyone that's what I did the first time), but this approach is more complicated than necessary. We need to loop over every character in the Characters collection and individually check whether it is a whitespace character. Then we need a way to track when to quit—
Okay, that's enough. I think we get the point. It's a mess.
Why do that when we can take advantage of some handy VBA Range methods? It's easier and VBA handles the details. The logic is simple, but it might cause you to tilt your head in thought at first.
What's the better way to detect paragraph whitespace?
The steps below may not be immediately obvious, so let's consider a balcony view before getting into the VBA. The idea is to compare the original paragraph range to another range which is designed to span all whitespace near the given paragraph.
What are the basic steps at a conceptual level?
- Get the range of the given paragraph
- Duplicate the paragraph range into another working range variable which leaves the original variable unchanged for later comparison
- Collapse the working range, so we know it is positioned at the start of the original paragraph
- Extend the working range forward in the document across any whitespace characters
- Compare the two ranges to see if the original paragraph range is inside the whitespace range
Step 5 provides the True or False answer for the function result.
Declare the working ranges
We need one range variable that will store the initial paragraph range and another which we will manipulate to span all whitespace near the paragraph. We'll call them rParagraph and rSpace, respectively,
Dim is the VBA keyword to declare variables, and "As Range" tells VBA what the data type is. We declare both on the same line by separating them with a comma; however, both need the As Range type, or it will default to a generic Variant type (which can store anything). I like to precede Range variables with an "r" to remind myself what type of data they store.
Why bother declaring variables?
This is called "declaring" a variable, and yeah, it's a little bothersome to stop and tell VBA what variables we'll use in the function. It's like brushing teeth. No one likes it, but it helps prevent trouble in the future.
I admit a certain freedom exists with just throwing a name into a function and letting VBA handle the data type stuff. I appreciate the freedom, and I use it sometimes when I'm working quickly such as when testing a macro prototype for these articles. However, if I'm creating a macro that will work on my manuscript text, I want to be more careful. Being specific with the names and the types of data they store will save time and effort down the road since it will help us avoid silly mistakes.
Why are we working with range variables?
If this function is testing a Paragraph variable, why are we defining and using range variables.
This function uses two Range variables mostly because the available VBA Paragraph methods (the actions) and properties (the data) are specialized to manipulate Word paragraph features and settings (e.g., spacing, indents, etc.). A paragraph is still a range of document content, and a VBA Range provides useful methods and properties more relevant to what we need to do in this function.
Get the paragraph range
All paragraphs are also a range of document content, so we just need to refer to WhichParagraph's Range property.
Now, we have access to everything a VBA Range can do.
Assign the original paragraph range
Assigning the original paragraph range is easy. We just set our rParagraph variable equal to the WhichParagraph argument Range.
We have to Set Range variables to the respective document range values because they are objects not plain values like a number.
Assign the working whitespace range
We want the whitespace range to begin at the Start position of the original paragraph (on its left side). We might naively start by just assigning the paragraph range to our paragraph range variable.
It looks good at first … but it doesn't work as expected. The range is indeed set to the original paragraph, but as assigned, they literally refer to the same range. Any changes to rSpace will also change rParagraph!
Arghhh.
It's like two kids wanting to play with the same toy. Neither child will be happy, and a lot of crying and bickering will ensue before a parent steps in. We don't want that.
We need the original range to remain unchanged, so we can compare our whitespace range to it later. We can make an independent paragraph range by referring to its Duplicate property.
Collapse the whitespace working range
We only want to work from the beginning of the paragraph, so we use the Collapse method to do just that.
The default is to collapse toward the start of the range which is what we need for this macro.
Extend over the whitespace characters
We now have an empty rSpace range (Start and End positions are the same) which is positioned at the beginning of the original paragraph. We need to extend the End position of the range forward in the document across any whitespace. The appropriate command is the MoveEndWhile method.
According to its name, this command does not change the Start position. Thus, if any specified characters are found on the end, the range extends to the right in the document.
Extend over which characters?
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.
A space character is literally just " " in double quotes, so we assign it to the option using a colon equals := symbol.
Include special whitespace characters
A paragraph mark and a tab are both special characters, but we can get the values from a miscellaneous constants table as vbCr and vbTab, respectively. We need to add (called concatenate for plain text strings) them to the space character 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.
Why are we including the paragraph mark?
Since the function requires a single Paragraph, we know precisely one paragraph mark exists at the end of the rParagraph range. Knowing this fact, we could omit a paragraph mark from the character set. While it is not incorrect to do so, it makes the comparison below a tad clunkier. The whitespace range would always be shorter than the paragraph range by one character (since it would stop at the paragraph mark) which messes up the comparison result below. Thus, paragraph marks are left in the whitespace range extension to simplify the detection logic.
Comparing the two working ranges
How do we check whether one range is inside another one?
A VBA Range has a convenient method to check exactly this … the InRange method.
This method is checking whether the range on the left is inside the range inside the parentheses. The result is a True or False Boolean value answering the question.
Assign the function result
We need to tell the function the result of our comparison. In VBA, we just assign the result to the function name.
A value of True means the rParagraph range is inside the working whitespace range rSpace. InRange gives a False result if any part of rParagraph is outside of rSpace which is correct for this macro.
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. More specifically, the original paragraph range is inside the whitespace range if the End position of rSpace is greater than or equal to the End position of the original paragraph range rParagraph.
It's a matter of preference, but the previous comparison just looks nicer. This looks too much like programming. Blehh.
Check for an invalid paragraph
When creating a function, we should consider whether the data being given to us is even valid. A rough conditional statement might look something like:
See the earlier comments for why we use False as the invalid result.
How do we check for an invalid paragraph?
Is the paragraph Nothing?
A rudimentary validation is to just check whether the given paragraph variable is valid. VBA assigns a value of Nothing to any object variable not yet assigned to a valid document element. Since a Paragraph is an object in VBA, we literally compare it to Nothing using "Is Nothing".
This is one of those places where VBA strives to read more like English, so the programming is easier for anyone less comfortable with it.
Assign an invalid function result
The proper result is False if the WhichParagraph argument is invalid.
While VBA will assign a default value, assuming it is assigned the value we want it to have is not a good habit, so we explicitly assign the False result before exiting the function.
Exit the function
The command to just exit the function is simple.
Depending on the structure of the macro, we may not need to exit the function.
Invalid paragraph conditional statements
We can validate the WhichParagraph variable in two slightly different ways. Both are useful, so the choice depends on how the function is structured and what looks nicer.
Use a full If-Then-Else conditional statement
Following the above rough conditional statement, we just include both parts.
Whether we include an Exit Function (omitted as a comment line here) command depends on whether any function steps are included after the If statement. If no steps exist after it, the Exit Function command would be redundant since the function will already end without taking any other actions.
Use an abbreviated If-Then conditional statement
Alternatively, we could just focus on the validation aspect with the conditional statement but only take an action if it is invalid. As such, this version exits the function immediately if it finds a problem.
This version does not contain any other steps, so it is a stand-alone validation. All other function steps for the valid paragraph case follow the validation. WhichParagraph should be tested before attempting to use any other command or property, or the macro will crash, and VBA will pop up an error message. With this restriction, the validation steps are often placed at or near the top of the function, so the macro just quits early if it finds a problem.
Final functions
We had two main variations for an empty paragraph.
Strictly empty paragraph function
Putting the steps together for a strictly empty paragraph, we have:
If WhichParagraph is invalid, a False result is assigned. Then the If statement is allowed to end without explicitly exiting the function because the function will already end just a step later (at the End Function line). An unambiguous function result is assigned either way whether the argument is valid or not.
The number of steps required to validate WhichParagraph (four lines) are longer than the function result (one line). The disparity is a little annoying, but we can't check anything about WhichParagraph if it is not properly assigned to a valid document paragraph.
Paragraph is only whitespace function
The more general version checking whether the paragraph contains only whitespace is:
This version includes a strictly empty paragraph as a special case.
Checking for paragraph whitespace seems a simple enough task, but see how messy it gets quickly? This is another reason why it's nice to package all the steps up into a separate function. Then we can just use it in another macro to get the answer and not worry as much about the details.
