Search

S.4.4c — Using a language reference

Depending on where you’re at in your journey with learning programming languages (and specifically, C++), LearnCpp.com might be the only resource you’re using to learn C++ or to look something up. LearnCpp.com is designed to explain concepts in a beginner-friendly fashion, but it simply can’t cover every aspect of the language. As you begin to explore outside the topics that these tutorials cover, you’ll inevitably run into questions that these tutorials don’t answer. In that case, you’ll need to leverage outside resources.

One such resource is Stack Overflow, where you can ask questions (or better, read the answer to the same question someone before you asked). But sometimes a better first stop is a reference guide. Unlike tutorials, which are designed to describe part of the language using informal language, reference guides describe the language using formal language. Because of this, reference material tends to be comprehensive, accurate, and… hard to understand.

In this lesson, we’ll show how to use cppreference, a popular standard reference that we refer to throughout the lessons, by researching 3 examples.

Overview

Cppreference greets you with an overview of the core language and libraries:

cppreference overview

From here, you can get to everything cppreference has to offer, but it’s easier to use the search function, or a search engine. The overview is a great place to visit once you’ve finished the tutorials on LearnCpp.com, to delve deeper into the libraries, and to see what else the language has to offer that you might not be aware of.

The upper half of the table shows features currently in the language, while the bottom half shows technical specifications, which are features that may or may not be added to C++ in a future version, or have already been partially accepted into the language. This can be useful if you want to see what new capabilities are coming soon.

Starting with C++11, cppreference marks all features with the language standard version they’ve been added in. The standard version is the little green number you can see next to some of the links in the above image. Features without a version number have been available since C++98/03. The version numbers are not only in the overview, but everywhere on cppreference, letting you know exactly what you can or cannot use in a specific C++ version.

A reminder

The C++ versions are C++98, C++03, C++11, C++14, C++17, (in-progress C++20).

Warning

If you use a search engine and a technical specification has just been accepted into the standard, you might get linked to a technical specification rather than the official reference, which can differ.

Tip

Cppreference is not only a reference for C++, but also for C. Since C++ shares some functions with C (which can differ), you may find yourself in the C reference after searching for something. The URL and the navigation bar at the top of cppreference always show you if you’re browsing the C or C++ reference.

std::string::length

We’ll start by researching a function that you know from the previous lesson, std::string::length, which returns the length of a string.

On the top right of cppreference, search for “string”. Doing so shows a long list of types and functions, of which only the top is relevant for now.

string search

We could have searched for “string length” right away, but for the purpose of showing as much as possible in this lesson, we’re taking the long route. Clicking on “std::string” leads to std::basic_string. There is no page for std::string, because std::string is a typedef for std::basic_string<char>, which can be seen in the typedef list:

typedef

The <char> means that each character of the string is of type char. You’ll note that C++ offers other strings that use different character types. These can be useful when using Unicode instead of ASCII.

Further down the same page, there’s a list of member functions (the behaviors that a type has). If you want to know what you can do with a type, this list is very convenient. In this list, you’ll find a row for length (and size).

Following the link brings us to the detailed function description of length and size, which both do the same thing.

The top of each page starts with a short summary of the feature and syntax, overloads, or declarations:

string length overloads

The title of the page shows the name of the class and function with all template parameters. We can ignore this part. Below the title, we see all of the different function overloads (different versions of the function that share the same name) and which language standard they apply to.

Below that, we can see the parameters that the function takes, and what the return value means.

Because std::string::length is a simple function, there’s not a lot of content on this page. Many pages show example uses of the feature they’re documenting, as does this one:

string length example

Until you’re done learning C++, there will be features in the examples that you haven’t seen before. If there are enough examples, you’re probably able to understand a sufficient amount of it to get an idea of how the function is used and what it does. If the example is too complicated, you can search for an example somewhere else or read the reference of the parts you don’t understand (you can click on functions and types in the examples to see what they do).

Now we know what std::string::length does, but we knew that before. Let’s have a look at something new!

std::cin.ignore

In lesson S.4.4b -- An introduction to std::string, we talked about std::cin.ignore, which is used to ignore everything up to a line break. One of the parameters of this function is some long and verbose value. What was that again? Can’t you just use a big number? What does this argument do anyway? Let’s figure it out!

The search function on cppreference doesn’t find anything when we search for “std::cin.ignore”, let’s try our favorite search engine:

Search engine results
  • std::ignore - No, that’s not it.
  • std::basic_istream::ignore - Eew, no.
  • std::cin - We want .ignore, not plain std::cin.
  • std::getline - That’s not it either.

It’s not there, what now? Let’s go to std::cin and work our way from there. There’s nothing immediately obvious on that page. On the top, we can see the declaration of std::cin and std::wcin, and it tells us which header we need to include to use std::cin:

Declaration

We can see that std::cin is an object of type std::istream. Let’s follow the link to std::istream:

basic_istream

Hold up! We’ve seen std::basic_istream before when we searched for “std::cin.ignore” in our search engine. It turns out that istream is a typedef for basic_istream, so maybe our search wasn’t so wrong after all.

Scrolling down on that page, we’re greeted with familiar functions:

Member functions

We’ve used many of these functions already: operator>>, get, getline, ignore. Scroll around on that page to get an idea of what else there is in std::cin. Then click ignore, since that’s what we’re interested in.

ignore

On the top of the page there’s the function signature and a description of what the function and its two parameters do. The = signs after the parameters indicate a default argument (we cover this in lesson 7.7 -- Default arguments). If we don’t provide an argument for a parameter that has a default value, the default value is used.

The first bullet point answers all of our questions. We can see that std::numeric_limits<std::streamsize>::max() has special meaning to std::cin.ignore, in that it disables the character count check. This means std::cin.ignore will continue ignoring characters until it finds the delimiter, or until it runs out of characters to look at.

Many times, you don’t need to read the entire description of a function if you already know it but forgot what the parameters or return value mean. In such situations, reading the parameter or return value description suffices.

Parameters and return value

The parameter description is brief. It doesn’t contain the special handling of std::numeric_limits<std::streamsize>::max() or the other stop conditions, but serves as a good reminder.

A language grammar example

Alongside the standard library, cppreference also documents the language grammar. Here’s a valid program:

Why is there a variable definition inside the condition of the if-statement? Let’s use cppreference to figure out what it does by searching for “cppreference if statement” in our favorite search engine. Doing so leads us to if statements. At the top, there’s a syntax reference.

On the right, we can again see the version for which this syntax is relevant. Look at the version of the if-statement that is relevant since C++17. If you remove all of the optional parts, you get an if-statement that you already know. Before the condition, there’s an optional init-statement, that looks like what’s happening in the code above.

if ( init-statement condition ) statement-true
if ( init-statement condition ) statement-true else statement-false

Below the syntax reference, there’s an explanation of each part of the syntax, including the init-statement. It says that the init-statement is typically a declaration of a variable with an initializer.

Following the syntax is an explanation of if-statements and simple examples:

Explanation on examples

We already know how if-statements work, and the examples don’t include an init-statement, so we scroll down a little to find a section dedicated to if-statements with initializers:

If Statements with Initializer

First, it is shown how the init-statement can be written without actually using an init-statement. Now we know what the code in question is doing. It’s a normal variable declaration, just merged into the if-statement.

The sentence after that is interesting, because it lets us know that the names from the init-statement are available in both statements (statement-true and statement-false). This may be surprising, since you might otherwise assume the variable is only available in the statement-true.

The init-statement examples use features and types that we haven’t covered yet. You don’t have to understand everything you see to understand how the init-statement works. Let’s skip everything that’s too confusing until we find something we can work with:

The easiest example seems to be the one with an int. Then we look after the semicolon and there’s another definition, odd… Let’s go back to the std::lock_guard example.

From this, it’s relatively easy to see how an init-statement works. Define some variable (lock), then a semicolon, then the condition. That’s exactly what happened in our example.

A warning about the accuracy of cppreference

Cppreference is not an official documentation source -- rather, it is a wiki. With wikis, anyone can add and modify content -- the content is sourced from the community. Although this means that it’s easy for someone to add wrong information, that misinformation is typically quickly caught and removed, making cppreference a reliable source.

The only official source for C++ is the the standard (Free drafts on github), which is a formal document and not easily usable as a reference.

Quiz time

Question #1


What does the following program print? Don’t run it, use a reference to figure out what erase does.

Tip

When you find erase on cppreference, you can ignore the function signatures (2) and (3).

Tip

Indexes in C++ start at 0. The character at index 0 in the string “House” is ‘H’, at 1 it’s ‘o’, and so on.

Show Solution

Question #2


In the following code, modify str so that its value is “I saw a blue car yesterday” without repeating the string. ie. don’t do this:

You only need to call one function to replace “red” with “blue”.

Show Hint

Show Hint

Show Hint

Show Hint

Show Solution


S.4.5 -- Enumerated types
Index
S.4.4b -- An introduction to std::string

10 comments to S.4.4c — Using a language reference

  • Vir1oN

    Thanks for the lesson, I’m so glad that you are now officially part of this beautiful resource, Nascardriver!
    This one is definitely going to teach some people a bit of self-dependence, which is often a rarity these days.

    The last thing, I believe there is a typo in the 1st sentence of the paragraph below (’ in let’s)

    “ The sentence after that is interesting, because it let’s us know that the names from the init-statement are available in both statements (statement-true and statement-false). This may be surprising, since you might otherwise assume the variable is only available in the statement-true.” (This is “A language grammar example” section, under 3d screenshot)

    P.S: And of course thank you, Alex, for maintaining the website!

  • Matt

    This is a phenomenal lesson.  I remember back when I first started using learncpp.com, it was the only place I was comfortable going to reference anything to do with coding.  I STILL come here to refresh on things I've gotten rusty on or don't use often because I'm so intimately familiar with the layout of the site now. I can remember little things (like if I forget the proper syntax for std::numeric_limits<std::streamsize>::MAX I can find it in the lesson on getline(), haha).  That said, as I got more comfortable with programming in general, I started wanting to branch out from the tutorials on this site...inevitably leading me to research things that aren't covered or hadn't been covered yet.

    All that to say my first few visits outside the nest of this site left me feeling overwhelmed and unsure if I had actually ever learned anything in all my time studying!  Eventually I grew accustomed to the formats of other sites and realized it's like anything: exposure yields confidence.

    This lesson was a great idea, and should help ease the transition for learners to branch out from this site to other references.  Nice!

  • Scoons

    In the red/blue car example there's a rogue full stop of a difference which should be fixed or removed

  • fighter_fish

    Wow, thank you!

  • Sirdavos

    Hi NascarDriver,
    I think this page is uselful but little bit too long. You can shorten the examples maybe or divide the page 2 different part.
    Thx

    • Omran

      no need to divide the page into 2 different parts , if you want to divide it , then read the first part of it and save the other one for later or something :)

Leave a Comment

Put all code inside code tags: [code]your code here[/code]