{"title":"Function Overloading","description":null,"content":"Function overloading lets you give two or more functions the same name as long as their parameter lists differ. The compiler picks which one to call based on the arguments you pass at the call site. It's the feature that lets `std::cout << x` work whether `x` is an `int`, a `double`, or a `std::string`, and it's how you build small, friendly APIs that read the same way for related operations.\n\n---\n\n# What Overloading Looks Like\n\nA function name plus its parameter list together form what C++ calls the function's **signature**. Two functions can share the same name as long as their signatures differ in the **types**, **number**, or **order** of their parameters. The return type is not part of the signature, which surprises a lot of people. We'll come back to that in a later section.\n\nHere's a small `printItem` family for a product catalog. One version takes a numeric product id, another takes a product name, and a third takes both an id and a quantity.\n\n\n```cpp\n#include \n#include \n\nvoid printItem(int productId) {\n std::cout << \"Item with id \" << productId << std::endl;\n}\n\nvoid printItem(const std::string& name) {\n std::cout << \"Item named \" << name << std::endl;\n}\n\nvoid printItem(int productId, int quantity) {\n std::cout << \"Item \" << productId << \" x \" << quantity << std::endl;\n}\n\nint main() {\n printItem(42);\n printItem(std::string(\"Wireless Mouse\"));\n printItem(42, 3);\n return 0;\n}\n```\n\n\nThree functions, one name, three different parameter lists. The compiler reads each call, looks at the arguments, and picks the matching version. From the caller's point of view, there's only one `printItem` to remember. From the implementer's point of view, there are three separate functions, each with its own body.\n\nThis is the core idea: one name, many flavors, picked by argument types. The benefit is a cleaner API. Without overloading, you'd be naming three different functions `printItemById`, `printItemByName`, `printItemByIdAndQty`, and the reader has to remember which is which.\n\n---\n\n# What Counts as a Different Signature\n\nThe signature is the function name plus the type, order, and count of its parameters. Two overloads are valid if and only if their parameter lists differ in at least one of those three ways.\n\nThings that change the signature (so the overload is allowed):\n\n- A different **type** in any parameter position: `int` vs `double`, `std::string` vs `int`.\n- A different **number** of parameters: one parameter vs two.\n- A different **order** of parameters: `(int, std::string)` vs `(std::string, int)`.\n\nThings that do **not** change the signature (so the overload is not allowed):\n\n- The return type by itself.\n- The parameter **names** (those are just labels for the body).\n- A `const` qualifier on a by-value parameter.\n\nA concrete demonstration. The first two declarations are valid overloads; the third one is a compile error because it only differs from the first by parameter names.\n\n\n```cpp\n#include \n\ndouble computeShipping(double weight) {\n return weight * 0.50;\n}\n\ndouble computeShipping(double weight, double distance) {\n return weight * 0.50 + distance * 0.10;\n}\n\n// Compile error: redefinition of 'double computeShipping(double)'\n// double computeShipping(double w) { return w * 0.99; }\n\nint main() {\n std::cout << computeShipping(2.0) << std::endl;\n std::cout << computeShipping(2.0, 100.0) << std::endl;\n return 0;\n}\n```\n\n\nThe first two `computeShipping` overloads have different parameter counts, so they are different signatures. The third one has the same parameter list as the first, just renamed from `weight` to `w`. Parameter names don't enter the signature, so `g++` rejects it with `error: redefinition of 'double computeShipping(double)'`.\n\nOrder matters too. These two are valid overloads:\n\n\n```cpp\nvoid addToCart(int productId, int quantity);\nvoid addToCart(int quantity, int productId); // different parameter order\n```\n\n\nBoth have two `int` parameters, but the meaning of each position is different. The compiler is happy because the *types in order* are still `(int, int)` vs `(int, int)`. Wait, that's the same. Let's correct that with a better example because two `int` parameters in either order is actually the same signature.\n\n\n```cpp\n#include \n#include \n\nvoid label(int productId, const std::string& tag) {\n std::cout << \"id=\" << productId << \" tag=\" << tag << std::endl;\n}\n\nvoid label(const std::string& tag, int productId) {\n std::cout << \"tag=\" << tag << \" id=\" << productId << std::endl;\n}\n\nint main() {\n label(7, \"new-arrival\");\n label(\"on-sale\", 12);\n return 0;\n}\n```\n\n\nHere the types in order are `(int, const std::string&)` vs `(const std::string&, int)`, which are genuinely different signatures. The compiler can tell them apart because the first argument's type is different in each case.\n\n---\n\n# How the Compiler Picks an Overload\n\nWhen you call a function that has multiple overloads, the compiler runs **overload resolution**. It looks at the types of the arguments you passed, then ranks every overload by how well it matches. The best match wins. If two overloads tie, the call is ambiguous and the compiler refuses to pick.\n\nThe intuition: an exact match beats a conversion, and a smaller conversion beats a bigger one. So if you pass an `int`, an overload that takes `int` wins over one that takes `double` (which would require a conversion), which wins over one that takes `const std::string&` (which can't convert from `int` at all).\n\nHere's a `format` family for a price, with three overloads:\n\n\n```cpp\n#include \n#include \n\nstd::string format(double price) {\n return \"$\" + std::to_string(price);\n}\n\nstd::string format(const std::string& priceText) {\n return \"string: \" + priceText;\n}\n\nstd::string format(int priceInCents) {\n return \"cents: \" + std::to_string(priceInCents);\n}\n\nint main() {\n std::cout << format(19.99) << std::endl; // calls format(double)\n std::cout << format(1999) << std::endl; // calls format(int)\n std::cout << format(std::string(\"$19.99\")) << std::endl; // calls format(string)\n std::cout << format(\"hello\") << std::endl; // calls format(string)\n return 0;\n}\n```\n\n\nWalking through the four calls:\n\n1. `format(19.99)` passes a `double`. The `double` overload is an exact match, so it wins.\n2. `format(1999)` passes an `int`. The `int` overload is an exact match, so it wins over the `double` overload (which would require an `int` to `double` conversion).\n3. `format(std::string(\"$19.99\"))` passes a `std::string`. The `const std::string&` overload is an exact match.\n4. `format(\"hello\")` passes a `const char*`. There's no `const char*` overload, but `const char*` converts to `std::string`, so the `std::string` overload wins.\n\nYou can picture the decision as a small flowchart. For each call site, the compiler walks down the list of candidates and grades each one.\n\n\n```mermaid\nflowchart TD\n A[Call site
format arg]:::cyan --> B{Any overload
matches arg
exactly?}:::green\n B -- Yes --> C[Pick the
exact match]:::teal\n B -- No --> D{Any overload
matches via
conversion?}:::orange\n D -- Exactly one --> E[Pick that
conversion]:::teal\n D -- More than one
equally good --> F[Ambiguous call
compile error]:::red\n D -- None --> G[No matching
function error]:::red\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef red fill:#ff8787,stroke:#000,color:#000\n```\n\n\nThe diagram simplifies the real rules, which have many tiers (exact match, promotion, standard conversion, user-defined conversion, ellipsis). For day-to-day code, the simplification is good enough: exact match first, then a single conversion, then ambiguity or no match. The full rules live in the C++ standard if you ever need them.\n\n---\n\n# Ambiguity: When No Overload Is Best\n\nOverload resolution fails when two or more overloads tie for best match and neither is strictly better. The compiler refuses to guess, so it stops and reports the call as ambiguous.\n\nA simple example. We have two overloads that each take a single numeric parameter, but the types differ:\n\n\n```cpp\n#include \n\nvoid price(float dollars) {\n std::cout << \"float: \" << dollars << std::endl;\n}\n\nvoid price(long dollars) {\n std::cout << \"long: \" << dollars << std::endl;\n}\n\nint main() {\n price(19); // ambiguous: int converts equally well to both\n return 0;\n}\n```\n\n\n`g++` reports:\n\n\n```shell\nerror: call of overloaded 'price(int)' is ambiguous\nnote: candidate: 'void price(float)'\nnote: candidate: 'void price(long)'\n```\n\n\nThe argument `19` is an `int`. The compiler looks at the candidates and finds two: one takes `float`, one takes `long`. Converting `int` to `float` and converting `int` to `long` are both standard conversions of the same rank. Neither is better. The result is ambiguity, and the compiler refuses to pick arbitrarily.\n\nThere are three reasonable fixes. Cast the argument to the type you want, change the argument to match one overload exactly, or add an `int` overload to make the intent clear.\n\n\n```cpp\nprice(static_cast(19)); // fix 1: explicit cast\nprice(19L); // fix 2: literal of the right type\n// or add an exact-match overload:\nvoid price(int dollars) {\n std::cout << \"int: \" << dollars << std::endl;\n}\n```\n\n\nWith the `int` overload added, `price(19)` becomes an exact match and the ambiguity goes away. Use the cast when you don't own the overload set, and add the missing overload when you do.\n\nAmbiguity also shows up with mixed signed/unsigned numeric types, with implicit conversions from `const char*` to multiple string-like types, and with default arguments interacting with overloads (covered in the section on common mistakes below).\n\n---\n\n# Why Return Type Alone Doesn't Count\n\nThis is the rule that catches everyone the first time. Two functions cannot be distinguished by their return type alone. If they have the same name and the same parameter list, only the return type differs, the compiler rejects the second one as a redefinition.\n\n\n```cpp\n// Both functions have parameter list (int), so they are the same signature.\nint getStock(int productId);\ndouble getStock(int productId); // compile error: redefinition\n```\n\n\n`g++` reports:\n\n\n```shell\nerror: ambiguating new declaration of 'double getStock(int)'\nnote: old declaration 'int getStock(int)'\n```\n\n\nThe reason isn't arbitrary. Overload resolution happens at the **call site**, before the compiler knows what the caller plans to do with the return value. Look at this hypothetical call:\n\n\n```cpp\ngetStock(42); // result discarded\n```\n\n\nIf the two overloads above were legal, which one would this call pick? The return value is thrown away, so neither return type gives the compiler any signal. There's no way to decide. Even with a return value, the compiler resolves the overload *first* and only then computes the result:\n\n\n```cpp\nauto stock = getStock(42); // which overload? auto deduces from the result, not the other way around\n```\n\n\n`auto` is a placeholder that the compiler fills in **after** the function call is resolved. The function call is resolved using the argument types, which are identical for both overloads. There's no information left to break the tie.\n\nThe same logic applies even when the return value is used in a context that expects a specific type:\n\n\n```cpp\nint x = getStock(42); // still ambiguous, because the compiler picks the overload first\n```\n\n\nThe compiler doesn't look at where the result is going. It picks the function based on arguments, then checks if the return type fits the destination. So allowing return-type overloading would force the compiler to work backwards, which the language was deliberately designed not to do.\n\nThe takeaway: if you need two functions that do similar things and return different types, give them different names (`getStockCount`, `getStockWeight`) or different parameter types.\n\n---\n\n# Const and Overloading\n\n`const` interacts with overloading in a way that trips up almost everyone the first time. The rule depends on **where** the `const` sits.\n\nFor parameters passed by **reference** or by **pointer**, `const` is part of the signature. So `void f(int&)` and `void f(const int&)` are two distinct overloads, and the compiler picks between them based on whether the argument is a `const` lvalue or a non-`const` lvalue.\n\nFor parameters passed **by value**, `const` is **not** part of the signature. So `void f(int)` and `void f(const int)` are the same function as far as the compiler is concerned, and declaring both is a redefinition.\n\nWhy the difference? When you pass by value, the parameter is a local copy inside the function. Whether that copy is `const` or not changes how the function's body can use it, but it doesn't change what the caller sees. From the outside, both signatures take an `int` and copy it. There's nothing for the compiler to distinguish at the call site.\n\nWhen you pass by reference or pointer, the `const` says something about the *original* object: a `const T&` parameter can bind to a `const T` lvalue (an `int&` cannot), so the two overloads accept different sets of arguments and the compiler can tell them apart.\n\nHere's the full picture in code:\n\n\n```cpp\n#include \n\n// OK: differ in reference-const, so they're separate overloads.\nvoid describe(int& stock) {\n std::cout << \"non-const ref: \" << stock << std::endl;\n}\n\nvoid describe(const int& stock) {\n std::cout << \"const ref: \" << stock << std::endl;\n}\n\n// NOT OK: const on a by-value parameter doesn't change the signature.\n// Uncommenting these two would be a redefinition.\n// void inspect(int price);\n// void inspect(const int price);\n\nint main() {\n int writable = 10;\n const int readOnly = 20;\n\n describe(writable); // calls describe(int&)\n describe(readOnly); // calls describe(const int&)\n return 0;\n}\n```\n\n\n`describe(writable)` and `describe(readOnly)` go to different overloads because the argument is a `const int` lvalue in one case and a plain `int` lvalue in the other. The reference's `const`-ness is part of the signature.\n\nIf you tried to declare both `inspect(int)` and `inspect(const int)`, `g++` would say:\n\n\n```shell\nerror: redefinition of 'void inspect(int)'\nnote: 'void inspect(const int)' previously defined here\n```\n\n\nThe compiler treats `const int` and `int` as the same parameter type when they're passed by value, so the two declarations are the same function.\n\nA pragmatic note: when overloading on `const`-ness of a reference, the common pattern is to use `const T&` for read-only access and a plain `T&` (or `T*`) for mutating access. You'll see this in the standard library for member functions like `std::vector::operator[]`, which has both a `const` and non-`const` version.\n\n---\n\n# Cart::add: A Realistic Overload Family\n\nA common place overloading earns its keep is when one operation has several natural shapes. A shopping cart's `add` operation is a good example. You might want to add a single product by id, add a product with a custom quantity, or add a product by passing its name when the id isn't known yet.\n\n\n```cpp\n#include \n#include \n#include \n\nclass Cart {\npublic:\n void add(int productId) {\n items.push_back({productId, 1});\n std::cout << \"Added product \" << productId << \" (qty 1)\" << std::endl;\n }\n\n void add(int productId, int quantity) {\n items.push_back({productId, quantity});\n std::cout << \"Added product \" << productId << \" (qty \" << quantity << \")\" << std::endl;\n }\n\n void add(const std::string& productName) {\n int id = lookupId(productName);\n items.push_back({id, 1});\n std::cout << \"Added '\" << productName << \"' (resolved to id \" << id << \")\" << std::endl;\n }\n\n int size() const {\n return static_cast(items.size());\n }\n\nprivate:\n struct LineItem {\n int productId;\n int quantity;\n };\n\n int lookupId(const std::string& name) {\n // Stub: a real lookup would query a catalog.\n if (name == \"Wireless Mouse\") return 101;\n if (name == \"USB Cable\") return 102;\n return -1;\n }\n\n std::vector items;\n};\n\nint main() {\n Cart cart;\n cart.add(101); // add by id, default qty\n cart.add(102, 3); // add by id with quantity\n cart.add(std::string(\"USB Cable\")); // add by name\n\n std::cout << \"Cart has \" << cart.size() << \" line items\" << std::endl;\n return 0;\n}\n```\n\n\nFrom the caller's view, the API is just `cart.add(...)`. Whatever you pass in, the cart figures it out. From the implementer's view, each overload has its own job: the `(int)` one defaults the quantity to `1`, the `(int, int)` one takes both, and the `(const std::string&)` one does a name lookup first.\n\nIf you needed to add several more shapes (add by SKU code, add by name with a quantity, add an entire pre-built line item), you'd just add more overloads. The name `add` stays put.\n\n---\n\n# format(price): One Name, Three Input Types\n\nAnother natural fit for overloading is a formatting function that takes \"the price\" in whatever form the caller has it. Sometimes a price is a `double` (dollars). Sometimes it's a string already (read from a file, say). Sometimes it's a small struct that bundles cents and a currency code.\n\n\n```cpp\n#include \n#include \n#include \n#include \n\nstruct Money {\n int cents;\n std::string currency;\n};\n\nstd::string format(double dollars) {\n std::ostringstream out;\n out << std::fixed << std::setprecision(2) << \"$\" << dollars;\n return out.str();\n}\n\nstd::string format(const std::string& rawText) {\n return \"raw: \" + rawText;\n}\n\nstd::string format(const Money& amount) {\n double dollars = amount.cents / 100.0;\n std::ostringstream out;\n out << std::fixed << std::setprecision(2)\n << amount.currency << \" \" << dollars;\n return out.str();\n}\n\nint main() {\n std::cout << format(19.99) << std::endl;\n std::cout << format(std::string(\"free shipping\")) << std::endl;\n std::cout << format(Money{2599, \"USD\"}) << std::endl;\n return 0;\n}\n```\n\n\nThree overloads, one purpose: turn \"the price\" into a printable string. The caller picks the right one by passing the right type. The output format differs across overloads because the input differs.\n\n\n> **INFO**\n>\n> **Cost note:** Overloading itself has no runtime cost. The compiler picks one of the overloads at compile time and emits a direct call. There's no virtual table, no lookup, no branching. The choice is baked into the generated code.\n\n\nNotice the third overload takes `const Money&` rather than `Money` by value. Passing a struct by `const` reference avoids the copy and protects the caller's object from accidental modification, which is the same general advice you'd follow for any non-trivial type.\n\n---\n\n# Common Mistakes\n\nA few overloading bugs come up so often they deserve their own callouts.\n\n### Trying to Overload on Return Type\n\nWe covered the rule above, but here's the mistake in its most tempting form. You want one function that returns a parsed integer price, another that returns a parsed double price. Both take the same input.\n\n\n```cpp\n// Won't compile: identical parameter lists.\nint parsePrice(const std::string& text);\ndouble parsePrice(const std::string& text);\n```\n\n\nThe fix is to give them different names or to use a parameter to disambiguate. Different names are the cleanest path:\n\n\n```cpp\nint parsePriceCents(const std::string& text);\ndouble parsePriceDollars(const std::string& text);\n```\n\n\nIf you really want one name, you can pass a tag parameter:\n\n\n```cpp\nstruct AsInt {};\nstruct AsDouble {};\n\nint parsePrice(const std::string& text, AsInt) { /* ... */ return 0; }\ndouble parsePrice(const std::string& text, AsDouble) { /* ... */ return 0.0; }\n\n// Usage:\n// auto a = parsePrice(\"19.99\", AsInt{});\n// auto b = parsePrice(\"19.99\", AsDouble{});\n```\n\n\nThat tag-dispatch pattern shows up in the standard library (think `std::piecewise_construct`). It's more machinery than most code needs, but it works when you genuinely want one name for related operations that return different types.\n\n### Default Arguments + Overloading = Ambiguity\n\nDefault arguments and overloads can collide. Each overload has its own defaults, and the compiler matches calls against the full set of overloads as if every default expansion were a separate candidate. If two overloads can both match the same call, the call is ambiguous.\n\n\n```cpp\n#include \n\nvoid addToCart(int productId, int quantity = 1) {\n std::cout << \"one-int with default: \" << productId\n << \" x \" << quantity << std::endl;\n}\n\nvoid addToCart(int productId) {\n std::cout << \"one-int: \" << productId << std::endl;\n}\n\nint main() {\n addToCart(42); // ambiguous: both overloads match\n return 0;\n}\n```\n\n\n`g++` reports:\n\n\n```shell\nerror: call of overloaded 'addToCart(int)' is ambiguous\nnote: candidate: 'void addToCart(int, int)'\nnote: candidate: 'void addToCart(int)'\n```\n\n\nThe call `addToCart(42)` can hit the second overload directly, or it can hit the first overload with `quantity` defaulted to `1`. Neither is better than the other, so the compiler refuses to pick.\n\nThere are two ways to fix it. Either drop the default on the first overload (so it doesn't compete for the single-argument call), or remove the second overload (so the default fully owns the single-argument case).\n\n\n```cpp\n// Option A: no default, two real overloads.\nvoid addToCart(int productId, int quantity) { /* ... */ }\nvoid addToCart(int productId) { /* ... */ }\n\n// Option B: one overload with a default, no second overload.\nvoid addToCart(int productId, int quantity = 1) { /* ... */ }\n```\n\n\nOption B is usually what people actually want. Default arguments are covered in detail in the previous lesson. The point here is just to flag the interaction so you don't hit it by accident.\n\n### Overloading on Implicitly Convertible Types\n\nWhen two parameter types are implicitly convertible to each other, calls with a third type often go to the \"wrong\" overload. The fix is usually to add the missing overload directly.\n\n\n```cpp\n#include \n#include \n\nvoid show(bool flag) {\n std::cout << \"bool: \" << flag << std::endl;\n}\n\nvoid show(const std::string& text) {\n std::cout << \"string: \" << text << std::endl;\n}\n\nint main() {\n show(\"on sale\"); // surprises a lot of beginners\n return 0;\n}\n```\n\n\nThis prints `bool: 1`. The string literal `\"on sale\"` is a `const char*`, which converts to `bool` (any non-null pointer is `true`) and to `std::string`. The pointer-to-`bool` conversion is a standard conversion; the pointer-to-`std::string` conversion is a user-defined conversion. Standard conversions beat user-defined conversions, so the `bool` overload wins.\n\nThe fix is to add a `const char*` overload (or to disable the `bool` one by making it take something stricter):\n\n\n```cpp\nvoid show(const char* text) {\n show(std::string(text)); // forward to the string overload\n}\n```\n\n\nNow `show(\"on sale\")` is an exact match for the `const char*` overload, which forwards to the string version. Surprise gone.\n\n---\n\n# When Not to Overload\n\nOverloading is a tool, not an obligation. Two situations where it's the wrong call.\n\nFirst, when the two functions do **different things**. Overloading is for *the same operation* on *different argument shapes*. If you have a function that adds an item to a cart and another that removes one, they shouldn't share a name even if their parameter lists differ. The name should describe what the function does.\n\nSecond, when the parameter types are very similar and prone to confusion. If you have `charge(double dollars)` and `charge(int cents)`, a caller writing `charge(19)` might mean nineteen dollars or nineteen cents. The compiler will pick one (the `int` overload, in this case), but the caller may have meant the other. Distinct names like `chargeDollars` and `chargeCents` remove the trap.\n\nOverloading earns its keep when the operation is genuinely the same and the type variation is just a convenience for the caller. When in doubt, ask whether `std::cout << x` (overloaded for every printable type) would be a good model for your API. If yes, overload. If not, use distinct names.\n\n---\n\n# Summary\n\n- Function overloading lets multiple functions share a name as long as their parameter lists differ in type, count, or order.\n- The function signature is the name plus the parameter list. Return type and parameter names are not part of the signature.\n- The compiler picks an overload at the call site by matching argument types to candidates: exact match beats conversion, smaller conversion beats larger.\n- Ambiguous calls happen when two overloads tie for best match. Fix them with a cast, a typed literal, or by adding an exact-match overload.\n- You cannot overload on return type alone because resolution happens before the compiler knows where the result goes.\n- `const` on a reference or pointer parameter is part of the signature, so it can drive overload resolution. `const` on a by-value parameter is not part of the signature and cannot be used to overload.\n- Default arguments and overloads can collide and produce ambiguity. Pick one mechanism for a given call shape and stick with it.\n- Implicit conversions sometimes route calls to surprising overloads (`const char*` to `bool` is a classic). Add an exact-match overload to redirect them.\n- Overloading has no runtime cost. The compiler bakes the choice into the generated code.\n\nIn the next lesson, we'll look at the `inline` keyword: what it actually means (and doesn't mean), how it affects linkage and code generation, and when it's the right tool for short functions you want defined in a header.","pageType":"cpp"}

Function Overloading

Get Premium