the argument vector

Understanding argc and argv in C Programming: A Comprehensive Guide

When programming in C, two commonly used parameters in the main() function are argc and argv. They play an essential role in passing command-line arguments to a program. In this blog post, we'll explore what these parameters are and how they work.

First, let's start with argc. This parameter is short for "argument count" and represents the number of arguments passed to the program. When a C program is executed from the command line, the operating system passes any additional arguments provided by the user to the program. These arguments can be anything from filenames to options or flags that modify the program's behavior.

The value of argc is determined by the operating system and is based on the number of arguments provided by the user. The first argument, argv[0], is always the name of the program itself. The remaining arguments, if any, are stored in consecutive memory locations starting at argv[1]. For example, if the user enters "program_name arg1 arg2 arg3" in the command line, argc will be 4, and argv[0] will be "program_name," argv[1] will be "arg1," argv[2] will be "arg2," and argv[3] will be "arg3."

Now, let's move on to argv. This parameter is short for "argument vector" and is an array of strings that contains the command-line arguments passed to the program. Each element of the array represents a single argument, and the array is terminated by a null pointer.

The elements of the argv array are always of type char*, which means they are pointers to null-terminated strings. This allows the program to access the argument values as C strings and perform string manipulation operations on them.

Here is an example program that demonstrates how argc and argv can be used:

  #include int main(int argc, char *argv[]) {     int i;     printf("The program name is: %s\n", argv[0]);     for (i = 1; i < argc; i++) {         printf("Argument %d: %s\n", i, argv[i]);     }     return 0; }

In this program, we first print out the program name, which is stored in argv[0]. Then, using a loop, we print out each argument in the argv array, starting from argv[1]. The output of this program would look something like this:

$ ./example arg1 arg2 arg3 The program name is: ./example Argument 1: arg1 Argument 2: arg2 Argument 3: arg3

In conclusion, argc and argv are essential parameters in C programs that allow them to receive and process command-line arguments. argc represents the number of arguments passed to the program, while argv is an array of strings that contains the actual argument values. Understanding these parameters is crucial for writing programs that can be executed with different command-line options and arguments.

Beginning Arduino Uno Programming in C++

Mustafa Qamaruddin

Multi-Threading In C++

Daniel McCarthy

Modern OpenGL C++ 3D Game Tutorial Series & 3D Rendering

Sonar Systems

Share This Course

A Short Explanation of ARGV

The following is a guest post by Joe O’Conor and originally appeared on his blog. Joe is a Flatiron School alumni. You can follow him on Twitter here. I’d come across ARGV or ARGV[0] a few times while looking at code examples on StackOverflow or the Ruby mailing lists. I recognized it as a kind of placeholder variable, but did not really […]

The following is a guest post by Joe O’Conor and originally appeared on  his blog .  Joe is a Flatiron School alumni. You can follow him on Twitter  here .

I’d come across  ARGV  or  ARGV[0]  a few times while looking at code examples on StackOverflow or the Ruby mailing lists. I recognized it as a kind of placeholder variable, but did not really understand its purpose or use and winced every time I saw it, worrying that I was missing something important. So now that I’m feeling more comfortable with the basics of Ruby, I decided to learn all about ARGV.

What is ARGV?

As a concept, ARGV is a convention in programming that goes back (at least) to the C language. It refers to the “argument vector,” which is basically a variable that contains the arguments passed to a program through the command line. It typically manifests as an array and can be manipulated in that way, meaning you can reference specific arguments by index or you can iterate through them in the standard ways. In languages other than Ruby, you will often run into ARGV’s companion, ARGC, which refers to the “argument count,” and this is a useful shortcut for iterating in languages that rely on for-loops to iterate. The argument vector is often a crucial component for command line utilities (you probably use it every day) and can simplify a utility’s user interface and make it much faster to use. (We’ll talk more about that towards the end of the post.)

ARGV in Ruby

In Ruby, ARGV is a constant defined in the  Object class . It is an instance of the Array class and has access to all the array methods. Since it’s an array, even though it’s a constant, its elements can be modified and cleared with no trouble. By default, Ruby captures all the command line arguments passed to a Ruby program (split by spaces) when the command-line binary is invoked and stores them as strings in the ARGV array. Ruby’s ARGV is different from many other implementations in that it does not store the program name — ARGV[0]  references the first argument passed to the program, and not the program’s name itself. Here’s an illustration.

$ ./awesome_ruby_cli_utility.rb first_arg second_arg third_arg

Here,  ARGV  is equal to  [“first_arg”, “second_arg”, “third_arg”] . If we want to parse the arguments in our program, we can use  ARGV[0] ,  ARGV[1] , and  ARGV[2] , or  ARGV.first  or even an iterator like  ARGV.each . As I eluded to before, there is no  ARGC  in Ruby, but Rubyists have an easy substitute with Ruby’s many iterators as well as  ARGV.length  (or #size , or  #count  with no block; ♥ Ruby).

This is tremendously useful. Let’s take a look at a real world example, from the Rails source code:

https://github.com/rails/rails/blob/master/railties/lib/rails/commands.rb

This example employs a couple of common tactics. First, if no argument is passed (meaning ARGV will be empty), then it pushes a --help  argument which details how to use the  rails  binary, instead of throwing an error or booting into something. It’s like, Hey, if you don’t know how to use me, here are some things you can do. Second,  command s are  #shift -ed off of the front of the ARGV for processing by a new CommandsTasks object. This way you can sequentially process arguments and even dispose of bad arguments with no issue if you want to set it up that way. (They’ve also included an awesome alias hash and a short-circuit || operator. Some beautiful code!)

Working ARGV Into a Gem

Let’s see if we can employ this in some of my code. This week I wrote a (shoddy)  gem  that scrapes SpeakerDeck.com based on a given query and produces output sorted by presentation views, suitable for storage in a database or website. It optionally generates barebones HTML. As it’s written right now, it needs to be  require -d in a Ruby script, like this:

Here I’ve initiated a scrape of presentations about javascript and included a verbose display option, then pushed the results to an HTML file. Easy enough, but if we just wanted to look at the data this is kind of cumbersome. I could write a command line interface, which might be kind of nice, but the end product is going to be an HTML file, so the terminal window is ultimately going to get in the way. However, we can make a binary, include some ARGV parsing to grab the query and options, and use the command line to directly launch the process (which, I might add, is time consuming, perfect as a background task). Let’s do it.

First thing, make a binary:

We’ll also want to specify this as an executable in the gemspec. Now we’ve got a binary that will be installed into our path when we install the gem. There are different ways to implement it, but for now, we’ll go with the simplest option and just write some code into the binary.

There we go. That first line is important for binaries. It lets the shell know to run the file using Ruby (more on this line: http://www.ruby-doc.org/docs/ProgrammingRuby/html/preface.html#UC ). So now when we call  spdeck-scrape  from the command line and pass a query and a range, we’ll be initiating a new scrape with that query and range. I had to force the range into an integer with  #to_i  because  ARGV  takes the arguments as strings, and my SpeakerdeckScraper class is looking for a Fixnum . Let’s allow the user to specify the display option also.

What happens if the user doesn’t specify any arguments? Right now it will blow up, because query, range, and display will be set to nil. Let’s add some instructions.

It’s not terribly robust, but it’s looking pretty good. I’d like to add one last thing for now: default options. I want a user to be able to just specify a query and nothing else. By default we’ll grab 5 pages of results and have concise display.

And now we’ve got some default values. It will mostly work as intended. We can build the gem, install it, and run it from the command line.

$ spdeck-scrape ruby 5 -v -html

screenshot of HTML output

There’s plenty more we could do with this gem, including refactoring our parsing to support multi-word queries by calling  #join on our  ARGV , adding aliases like in the Rails code, or taking advantage of the tools available in Ruby’s  ARGF  class or the OptionsParser  class, which could streamline and automate a lot of the parsing that I did manually in my gem. I’ve covered only the bare minimum about  ARGV  here.

Some additional references and resources:

http://www.ruby-doc.org/core-2.0.0/ARGF.html

http://www.ruby-doc.org/core-2.0.0/Object.html

http://ruby-doc.org/stdlib-2.0.0/libdoc/optparse/rdoc/OptionParser.html

https://www.ruby-forum.com/topic/683961

http://guides.rubygems.org/make-your-own-gem/

You can install my gem with RubyGems:

$ gem install spdeck-scrape

Or you can browse the source code at Github:  https://github.com/jnoconor/spdeck-scrape/ .  

Are you looking for a career as a Ruby developer?

Disclaimer: The information in this blog is current as of October 14, 2013. Current policies, offerings, procedures, and programs may differ.

About Flatiron School

Related posts.

Learn to Code Python: Free Lesson for Beginners

Anslie Brant: From Nanny to Operations Analyst

Microinteractions: Small Design Details That Make a Big Difference

Related resources.

Behind JavaScript, HTML/CSS, and SQL, Python is the fourth most popular language with 44.1% of developers. Check out this article on how you can learn this popular programming language for free.

"I went from being a nanny with no corporate experience to working a technical role in a fintech corporation."

Can small design details really yield big usability improvements? When microinteractions are implemented thoughtfully, the answer is yes. Learn how these subtle design cues can increase user understanding of a digital interface, reduce errors, and strengthen brand voice within a product’s design.

Privacy Overview

Art and Comics Blog Critical Mass Emacs Free Stuff Games Gnu/Linux Home Learn Japanese Links Montreal Music News Some Essays Statistics

Argc and argv.

Next: Environment Variables , Up: The Basic Program/System Interface   [ Contents ][ Index ]

25.1 Program Arguments

The system starts a C program by calling the function main . It is up to you to write a function named main —otherwise, you won’t even be able to link your program without errors.

In ISO C you can define main either to take no arguments, or to take two arguments that represent the command line arguments to the program, like this:

The command line arguments are the whitespace-separated tokens given in the shell command used to invoke the program; thus, in ‘ cat foo bar ’, the arguments are ‘ foo ’ and ‘ bar ’. The only way a program can look at its command line arguments is via the arguments of main . If main doesn’t take arguments, then you cannot get at the command line.

The value of the argc argument is the number of command line arguments. The argv argument is a vector of C strings; its elements are the individual command line argument strings. The file name of the program being run is also included in the vector as the first element; the value of argc counts this element. A null pointer always follows the last element: argv [ argc ] is this null pointer.

For the command ‘ cat foo bar ’, argc is 3 and argv has three elements, "cat" , "foo" and "bar" .

In Unix systems you can define main a third way, using three arguments:

The first two arguments are just the same. The third argument envp gives the program’s environment; it is the same as the value of environ . See Environment Variables . POSIX.1 does not allow this three-argument form, so to be portable it is best to write main to take two arguments, and use the value of environ .

• Program Argument Syntax Conventions
• Parsing Program Arguments

cppreference.com

Std:: vector.

The elements are stored contiguously, which means that elements can be accessed not only through iterators, but also using offsets to regular pointers to elements. This means that a pointer to an element of a vector may be passed to any function that expects a pointer to an element of an array.

The storage of the vector is handled automatically, being expanded as needed. Vectors usually occupy more space than static arrays, because more memory is allocated to handle future growth. This way a vector does not need to reallocate each time an element is inserted, but only when the additional memory is exhausted. The total amount of allocated memory can be queried using capacity() function. Extra memory can be returned to the system via a call to shrink_to_fit() [1] .

Reallocations are usually costly operations in terms of performance. The reserve() function can be used to eliminate reallocations if the number of elements is known beforehand.

The complexity (efficiency) of common operations on vectors is as follows:

• Random access - constant 𝓞(1) .
• Insertion or removal of elements at the end - amortized constant 𝓞(1) .
• Insertion or removal of elements - linear in the distance to the end of the vector 𝓞(n) .

std::vector (for T other than bool ) meets the requirements of Container , AllocatorAwareContainer (since C++11) , SequenceContainer , ContiguousContainer (since C++17) and ReversibleContainer .

• ↑ In libstdc++, shrink_to_fit() is not available in C++98 mode.

[ edit ] Template parameters

[edit]

[ edit ] Specializations

The standard library provides a specialization of std::vector for the type bool , which may be optimized for space efficiency.

[ edit ] Iterator invalidation

[ edit ] member types, [ edit ] member functions, [ edit ] non-member functions, [ edit ] notes, [ edit ] example, [ edit ] defect reports.

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

• Recent changes
• Offline version
• What links here
• Related changes
• Upload file
• Special pages
• Printable version
• Permanent link
• Page information
• In other languages
• This page was last modified on 13 November 2023, at 23:49.
• This page has been accessed 14,569,309 times.
• Privacy policy
• About cppreference.com
• Disclaimers

This browser is no longer supported.

Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.

vector class

• 8 contributors

The C++ Standard Library vector class is a class template for sequence containers. A vector stores elements of a given type in a linear arrangement, and allows fast random access to any element. A vector is the preferred container for a sequence when random-access performance is at a premium.

Type The element data type to be stored in the vector

Allocator The type that represents the stored allocator object that encapsulates details about the vector's allocation and deallocation of memory. This argument is optional and the default value is allocator<Type> .

Vectors allow constant time insertions and deletions at the end of the sequence. Inserting or deleting elements in the middle of a vector requires linear time. The deque class container is faster at insertions and deletions at the beginning and end of a sequence. The list class container is faster at insertions and deletions at any location within a sequence.

Vector reallocation occurs when a member function must increase the sequence contained in the vector object beyond its current storage capacity. Other insertions and erasures may alter various storage addresses within the sequence. In all such cases, iterators or references that point at altered portions of the sequence become invalid. If no reallocation happens, only iterators and references before the insertion/deletion point remain valid.

The vector<bool> class is a full specialization of the class template vector for elements of type bool . It has an allocator for the underlying type used by the specialization.

The vector<bool> reference class is a nested class whose objects can provide references to elements (single bits) within a vector<bool> object.

Constructors

Allocator_type.

A type that represents the allocator class for the vector object.

allocator_type is a synonym for the template parameter Allocator .

See the example for get_allocator for an example that uses allocator_type .

Erases a vector and copies the specified elements to the empty vector.

first Position of the first element in the range of elements to be copied.

last Position of the first element beyond the range of elements to be copied.

count The number of copies of an element being inserted into the vector.

value The value of the element being inserted into the vector.

init_list The initializer_list containing the elements to insert.

First, assign erases any existing elements in a vector. Then, assign either inserts a specified range of elements from the original vector into a vector, or it inserts copies of a new specified value element into a vector.

Returns a reference to the element at a specified location in the vector.

position The subscript or position number of the element to reference in the vector.

Return value

A reference to the element subscripted in the argument. If position is greater than the size of the vector, at throws an exception.

If the return value of at is assigned to a const_reference , the vector object can't be modified. If the return value of at is assigned to a reference , the vector object can be modified.

Returns a reference to the last element of the vector.

The last element of the vector. If the vector is empty, the return value is undefined.

If the return value of back is assigned to a const_reference , the vector object can't be modified. If the return value of back is assigned to a reference , the vector object can be modified.

When compiled by using _ITERATOR_DEBUG_LEVEL defined as 1 or 2, a runtime error occurs if you attempt to access an element in an empty vector. For more information, see Checked iterators .

Returns a random-access iterator to the first element in the vector.

A random-access iterator addressing the first element in the vector or to the location succeeding an empty vector . Always compare the value returned with vector::end to ensure it's valid.

If the return value of begin is assigned to a vector::const_iterator , the vector object can't be modified. If the return value of begin is assigned to an vector::iterator , the vector object can be modified.

Returns the number of elements that the vector could contain without allocating more storage.

The current length of storage allocated for the vector.

The member function resize will be more efficient if sufficient memory is allocated to accommodate it. Use the member function reserve to specify the amount of memory allocated.

Returns a const iterator that addresses the first element in the range.

A const random-access iterator that points at the first element of the range, or the location just beyond the end of an empty range (for an empty range, cbegin() == cend() ).

With the return value of cbegin , the elements in the range can't be modified.

You can use this member function in place of the begin() member function to guarantee that the return value is const_iterator . Typically, it's used in with the auto type deduction keyword, as shown in the following example. In the example, consider Container to be a modifiable (non- const ) container of any kind that supports begin() and cbegin() .

Returns a const past-the-end iterator that points to the element following the last element of the vector.

A const past-the-end iterator for the vector. It points to the element following the last element of the vector. That element is a placeholder and shouldn't be dereferenced. Only use it for comparisons. If the vector is empty, then vector::cend() == vector::cbegin() .

cend is used to test whether an iterator has passed the end of its range.

You can use this member function in place of the end() member function to guarantee that the return value is const_iterator . Typically, it's used with the auto type deduction keyword, as shown in the following example. In the example, consider Container to be a modifiable (non- const ) container of any kind that supports end() and cend() .

The value returned by cend shouldn't be dereferenced. Only use it for comparisons.

Erases the elements of the vector.

const_iterator

A type that provides a random-access iterator that can read a const element in a vector.

A type const_iterator can't be used to modify the value of an element.

See the example for back for an example that uses const_iterator .

const_pointer

A type that provides a pointer to a const element in a vector.

A type const_pointer can't be used to modify the value of an element.

An iterator is more commonly used to access a vector element.

const_reference

A type that provides a reference to a const element stored in a vector. It's used for reading and doing const operations.

A type const_reference can't be used to modify the value of an element.

const_reverse_iterator

A type that provides a random-access iterator that can read any const element in the vector.

A type const_reverse_iterator can't modify the value of an element and is used to iterate through the vector in reverse.

See rbegin for an example of how to declare and use an iterator.

Returns a const iterator to the first element in a reversed vector.

A const reverse random-access iterator addressing the first element in a reversed vector or addressing what had been the last element in the unreversed vector .

With the return value of crbegin , the vector object can't be modified.

Returns a const past-the-end reverse iterator that points to the element following the last element of the reversed vector.

A const reverse past-the-end iterator for the reversed vector. It points to the element following the last element of the reversed vector, which is the same as the element before the first element of the non-reversed vector. That element is a placeholder and shouldn't be dereferenced. Only use it for comparisons.

crend is used with a reversed vector just as vector::cend is used with a vector .

With the return value of crend (suitably decremented), the vector object can't be modified.

crend can be used to test to whether a reverse iterator has reached the end of its vector .

The value returned by crend shouldn't be dereferenced. Only use it for comparisons.

Returns a pointer to the first element in the vector.

A pointer to the first element in the vector or to the location succeeding an empty vector .

difference_type

A type that provides the difference between two iterators that refer to elements within the same vector.

A difference_type can also be described as the number of elements between two pointers, because a pointer to an element contains its address.

Inserts an element constructed in place into the vector at a specified position.

position The position in the vector where the first element is inserted.

args Constructor arguments. The function infers which constructor overload to invoke based on the arguments provided.

The function returns an iterator that points to the position where the new element was inserted into the vector .

Any insertion operation can be expensive, see vector class for a discussion of vector performance.

emplace_back

Adds an element constructed in place to the end of the vector.

Tests if the vector is empty.

true if the vector is empty; false if the vector isn't empty.

Returns a past-the-end iterator that points to the element following the last element of the vector.

A past-the-end iterator for the vector. It points to the element following the last element of the vector. That element is a placeholder and shouldn't be dereferenced. Only use it for comparisons. If the vector is empty, then vector::end() == vector::begin() .

If the return value of end is assigned to a variable of type const_iterator , the vector object can't be modified. If the return value of end is assigned to a variable of type iterator , the vector object can be modified.

Removes an element or a range of elements in a vector from specified positions.

position Position of the element to be removed from the vector.

first Position of the first element removed from the vector.

last Position just beyond the last element removed from the vector.

An iterator that designates the first element remaining beyond any elements removed, or a pointer to the end of the vector if no such element exists.

Returns a reference to the first element in a vector.

A reference to the first element in the vector object. If the vector is empty, the return is undefined.

If the return value of front is assigned to a const_reference , the vector object can't be modified. If the return value of front is assigned to a reference , the vector object can be modified.

get_allocator

Returns a copy of the allocator object used to construct the vector.

The allocator used by the vector.

Allocators for the vector class specify how the class manages storage. The default allocators supplied with C++ Standard Library container classes are sufficient for most programming needs. Writing and using your own allocator class is an advanced C++ feature.

Inserts an element, or many elements, or a range of elements into the vector at a specified position.

count The number of elements being inserted into the vector.

first The position of the first element in the range of elements to be copied.

last The position of the first element beyond the range of elements to be copied.

The first two insert functions return an iterator that points to the position where the new element was inserted into the vector.

As a precondition, first and last must not be iterators into the vector, or the behavior is undefined. Any insertion operation can be expensive, see vector class for a discussion of vector performance.

A type that provides a random-access iterator that can read or modify any element in a vector.

A type iterator can be used to modify the value of an element.

See the example for begin .

Returns the maximum length of the vector.

The maximum possible length of the vector.

Returns a reference to the vector element at a specified position.

position The position of the vector element.

If the position specified is greater than or equal to the size of the container, the result is undefined.

If the return value of operator[] is assigned to a const_reference , the vector object can't be modified. If the return value of operator[] is assigned to a reference, the vector object can be modified.

When compiled by using _ITERATOR_DEBUG_LEVEL defined as 1 or 2, a runtime error occurs if you attempt to access an element outside the bounds of the vector. For more information, see Checked iterators .

Replaces the elements of the vector with a copy of another vector.

right The vector being copied into the vector .

After erasing any existing elements in a vector , operator= either copies or moves the contents of right into the vector .

A type that provides a pointer to an element in a vector.

A type pointer can be used to modify the value of an element.

Deletes the element at the end of the vector.

For a code example, see vector::push_back() .

Adds an element to the end of the vector.

value The value to assign to the element added to the end of the vector.

Returns an iterator to the first element in a reversed vector.

A reverse random-access iterator addressing the first element in a reversed vector or addressing what had been the last element in the unreversed vector.

If the return value of rbegin is assigned to a const_reverse_iterator , the vector object can't be modified. If the return value of rbegin is assigned to a reverse_iterator , the vector object can be modified.

A type that provides a reference to an element stored in a vector.

See at for an example of how to use reference in the vector class.

Returns a past-the-end reverse iterator that points to the element following the last element of the reversed vector.

A reverse past-the-end iterator for the reversed vector. It points to the element following the last element of the reversed vector, which is the same as the element before the first element of the non-reversed vector. That element is a placeholder and shouldn't be dereferenced. Only use it for comparisons.

rend is used with a reversed vector just as end is used with a vector.

If the return value of rend is assigned to a const_reverse_iterator , then the vector object can't be modified. If the return value of rend is assigned to a reverse_iterator , then the vector object can be modified.

rend can be used to test to whether a reverse iterator has reached the end of its vector.

The value returned by rend shouldn't be dereferenced. Only use it for comparisons.

Reserves a minimum length of storage for a vector object, allocating space if necessary.

count The minimum length of storage to be allocated for the vector.

Specifies a new size for a vector.

new_size The new size of the vector.

value The initialization value of new elements added to the vector if the new size is larger that the original size. If the value is omitted, the new objects use their default constructor.

If the container's size is less than the requested size, new_size , resize adds elements to the vector until it reaches the requested size. When the container's size is larger than the requested size, resize deletes the elements closest to the end of the container until it reaches the size new_size . No action is taken if the present size of the container is the same as the requested size.

size reflects the current size of the vector.

reverse_iterator

A type that provides a random-access iterator that can read or modify any element in a reversed vector.

A type reverse_iterator is used to iterate through the vector in reverse.

See the example for rbegin .

shrink_to_fit

Discards excess capacity.

Returns the number of elements in the vector.

The current length of the vector.

A type that counts the number of elements in a vector.

See the example for capacity .

Exchanges the elements of two vectors.

right A vector providing the elements to be swapped. Or, a vector whose elements are to be exchanged with the elements in the vector left .

left A vector whose elements are to be exchanged with the elements in the vector right .

A type that represents the data type stored in a vector.

value_type is a synonym for the template parameter Type .

Constructs a vector. Overloads construct a vector of a specific size, or with elements of a specific value. Or, as a copy of all or part of some other vector. Some overloads also allow you to specify the allocator to use.

allocator The allocator class to use with this object. get_allocator returns the allocator class for the object.

count The number of elements in the constructed vector.

value The value of the elements in the constructed vector.

source The vector of which the constructed vector is to be a copy.

init_list The initializer_list containing the elements to copy.

All constructors store an allocator object ( allocator ) and initialize the vector.

The first two constructors specify an empty initial vector. The second constructor explicitly specifies the allocator type ( allocator ) to use.

The third constructor specifies a repetition of a specified number ( count ) of elements of the default value for class Type .

The fourth and fifth constructors specify a repetition of ( count ) elements of value value .

The sixth constructor specifies a copy of the vector source .

The seventh constructor moves the vector source .

The eighth constructor uses an initializer_list to specify the elements.

The ninth and tenth constructors copy the range [ first , last ) of a vector.

Thread Safety in the C++ Standard Library C++ Standard Library Reference

Was this page helpful?

Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback .

Submit and view feedback for

Additional resources

Help Center Help Center

• Help Center
• Trial Software
• Product Updates
• Documentation

Declare function argument validation

Since R2019b

Description

Input argument blocks.

arguments ... end declares input arguments for a function. The arguments block is optional. If you include one or more arguments blocks, they must appear before the first executable line of the function. MATLAB ® treats any argument block that is not labeled explicitly with Input or Output as an input block.

Each argument can have one or more restrictions or a default value, as shown in this syntax:

argName (dimensions) class {validators} = defaultValue

(dimensions) — Input size, specified as a comma-separated list of two or more numbers, such as (1,2) , (3,5,2) , or (1,:) . A colon allows any length in that dimension. (dimensions) cannot include expressions.

The dimensions of the input must match (dimensions) exactly or be compatible with the size specified by (dimensions) . For example, (1,:) specifies the input must be a 1-by- n row vector, but an n -by-1 column vector is compatible. The function reshapes a row vector input into a column vector. Similarly, a size of (2,3) allows scalar input, but it expands the input to a 2-by-3 matrix. See Compatible Array Sizes for Basic Operations for more information.

class — Class or MATLAB data type specified by name, such as double . The input must be the specified type or a type that can be converted to that type. For example, a function that specifies double accepts values of class single and converts them to double . For more information on conversions, see Implicit Class Conversion .

{validators} — Comma-separated list of validation functions, such as mustBeNumeric and mustBeScalarOrEmpty , enclosed in curly brackets. Validation functions error when the input arguments do not match their conditions. Unlike class , validation functions do not modify input arguments. For a list of validation functions, see Argument Validation Functions .

defaultValue — Default values must conform to the specified size, type, and validation rules. A default value can also be an expression. Specifying a default value makes the argument optional. Optional arguments must be positioned after required arguments in the function signature and in the arguments block.

For name-value arguments, arg uses the form nv.name , where nv is a structure name in the function signature and name is the argument name in the arguments block. For instance, define a function that accepts name-value arguments using a structure named options .

y = myFunction(x,options)

In the arguments block, specify the names for name-value arguments as fields: arguments x options.Name1 options.Name2 end

For more information on using arguments blocks in general, see arguments Block Syntax .

arguments (Repeating) ... end declares repeating input arguments.

For example, if you create a function named myplot with repeating arguments X , Y , and style , the function accepts multiple sets of these three arguments, such as myplot(x1,y1,style1,x2,y2,style2) . MATLAB creates a cell array that contains all the values passed in for that argument.

Functions can include only one repeating input arguments block. If the function includes both repeating and name-value arguments, declare name-value arguments in their own, separate arguments block after the repeating arguments block.

For more information on using validation with repeating arguments, see Validate Repeating Arguments .

Output Argument Blocks

arguments (Output) ... end declares output arguments for a function. The output arguments block is optional. If you include one or more output arguments blocks, they must appear after all input blocks but before the first executable line of the function. When including both input and output blocks in a function, including the (Input) and (Output) attributes explicitly is recommended for readability. See Repeating Outputs with Argument Validation for an example. (since R2022b)

Like input arguments, output arguments can have one or more restrictions, as shown in this syntax:

argName (dimensions) class {validators}

See the description for arguments ... end for additional details. Unlike input arguments, output arguments cannot define a default value, and validation functions applied to an output argument cannot reference an earlier output argument.

arguments (Output,Repeating) ... end declares a repeating output argument for a function. You can use argument validation for a repeating output argument, but you can define only one repeating output argument per function. varargout can appear in a repeating output arguments block as long as it is the only output argument. (since R2022b)

collapse all

Restrict Size and Type of Input

Write a function that restricts the size of the input argument to a row vector of any length. Use a validation function to restrict the elements of that vector to numeric values.

Call the function on a three-element row vector.

Calling the function with a column vector is also valid because row and column vectors are compatible.

If you call the function with a vector that contains nonnumeric values, the mustBeNumeric validation function throws an error.

Define Name-Value Arguments

To declare optional name-value arguments for a function, include a structure name in the function declaration, and define the argument names as fields of that structure in the arguments block.

Declare the myRectangle function with options as a structure name. The two fields of options , LineStyle and LineWidth , are the names in the function’s name-value arguments:

Both of the argument names have defined default values, so they are both optional. All of these syntaxes are valid ways to call the function:

Before R2021a, pass names as strings or character vectors, and separate names and values with commas. Both syntaxes are valid in later releases.

Define Repeating Input Arguments

Repeating arguments are single arguments or groups of arguments that can be repeated zero or more times in a function call. The fRepeat function accepts repeating groups of arguments x , y , and style . Restrict the input arguments x and y to vectors of double values or values convertible to doubles. Restrict style to the strings "--" and ":" .

Call fRepeat with two groups of inputs. MATLAB creates a cell array containing all the values passed in for x , another array for the values of y , and a third for the values of style . The function then reshapes those arrays into a 1-by-6 cell array, z , and passes it to plot .

Restrict Output Values with Argument Validation

Write a function that rotates a two-dimensional square patch about point (0.4, 0.4) by a user-specified number of degrees. Return x - and y -coordinates of the final image as output arguments, and restrict those values to be positive. In other words, the function should return coordinates only when the final result of the rotation is entirely in the first quadrant.

Call the function with an angle of 15 degrees. This rotation does not move any of the vertices out of the first quadrant, so the function returns without error.

Call the function with an angle of 35 degrees, which moves the lower-left vertex out of the first quadrant. The negative x -coordinate does not satisfy the output argument validation, so the function returns an error.

Repeating Outputs with Argument Validation

Write a function that accepts repeating pairs of vectors and returns the sum of each pair. Restrict the inputs and outputs to row vectors.

Calculating the final output and assigning it to vectorSum{n} before the for -loop preallocates space for the cell array. Expanding the cell array in the loop without preallocation can have a negative effect on performance.

Define two pairs of vectors. Call repeatSum on with the two pairs as input. The input arguments block validation converts column vectors to row vectors because they are compatible sizes.

Because the inputs are restricted to row vectors, the sum of each pair of vectors is always a row vector. However, the output validation helps ensure that the function produces row vectors even if the function is revised at a later date. For example, if the input validation were changed to the mustBeVector function, pairs could be composed of one row vector and one column vector without conversion. In that case, the sum of x1 and y2 is a matrix.

The output of the revised repeatSum would error because the matrix would not pass the output validation.

Limitations

Argument blocks are not supported in nested functions, abstract methods, or handle class destructor methods.

Supported Data Types

Argument declarations can specify any MATLAB class or externally defined class that is supported by MATLAB, except Java classes, COM classes, and MATLAB classes defined before MATLAB software Version 7.6 (in other words, class definitions that do not use the classdef keyword).

Using data type restrictions can result in implicit conversions of input arguments. For example: function y = myFunction(inputArg1) arguments inputArg1 (1,1) double end ... For this function, if you pass the string "123" as the input argument, MATLAB converts the string to the numeric value 123 of type double .

Validation functions do not change input values in any way, so to avoid data type conversion, use one or more validator functions instead of a data type to restrict the input. For example:

To avoid conversion of strings to numeric values, use mustBeA , mustBeFloat , or mustBeNumeric .

To avoid conversion of numeric values to strings, use mustBeText , mustBeTextScalar , or mustBeNonZeroLengthText .

To avoid size conversions, use mustBeVector or mustBeScalarOrEmpty .

MATLAB is able to provide code completions and suggestions for functions with arguments blocks based on the information contained in the arguments block. This information is available without requiring a functionSignatures.json file. For more information on customizing code suggestions and completions see, Customize Code Suggestions and Completions .

Extended Capabilities

C/c++ code generation generate c and c++ code using matlab® coder™..

Code generation supports most features of arguments blocks, including size and class validation, validation functions, and default values. Code generation also supports the namedargs2cell function.

Code generation does not support these features of arguments blocks:

Size validation, class validation, and validation functions for repeating arguments

Multiple repeating input arguments

Name-value input arguments at entry-point functions

Name-value input arguments from class properties using the structName.?ClassName syntax

Size validation for table , timetable , or dlarray (Deep Learning Toolbox) objects.

For additional code generation considerations, see Generate Code for arguments Block That Validates Input and Output Arguments (MATLAB Coder) . Further considerations apply when you use an arguments block to specify the types of the input arguments to your entry-point function. See Use Function Argument Validation to Specify Entry-Point Input Types (MATLAB Coder) .

Version History

R2022b: argument validation for output arguments.

The new arguments (Output) and arguments (Output,Repeating) blocks enable you to apply argument validation to output arguments of functions and class methods.

• Function Argument Validation
• Validate Name-Value Arguments

MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

• Switzerland (English)
• Switzerland (Deutsch)
• Switzerland (Français)
• 中国 (English)

You can also select a web site from the following list:

How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

• América Latina (Español)
• Canada (English)
• United States (English)
• Belgium (English)
• Denmark (English)
• Deutschland (Deutsch)
• España (Español)
• Finland (English)
• France (Français)
• Ireland (English)
• Italia (Italiano)
• Luxembourg (English)
• Netherlands (English)
• Norway (English)
• Österreich (Deutsch)
• Portugal (English)
• Sweden (English)
• United Kingdom (English)

Asia Pacific

• Australia (English)
• India (English)
• New Zealand (English)

Contact your local office

About Vector Arguments

Introduction.

The *apply_byname() family of functions are used internally by many functions in matsbyname . These functions ( unaryapply_byname() , binaryapply_byname() , naryapply_byname() ) allow additional arguments, besides the matrices that are being transformed, which are passed via .FUNdots . Getting .FUNdots right can be challenging, and this vignette provides some background and explanation to those challenges. After reading this vignette, both callers of these functions and programmers who use these functions will be in a better position to take advantage of the various *apply_byname() functions.

To see how the .FUNdots argument works, let’s make an example function that takes advantage of unaryapply_byname() . mysum() adds entries in matrix a , the result depending upon the value of margin .

Structuring mysum() as shown above provides several interesting capabilities. First, mysum() works with single matrices.

Second, mysum() works with lists.

Finally, mysum() works within data frames.

The problem

In the above examples, margin was only 1 or 2 , not c(1, 2) for the list and data frame examples. Let’s see what happens when margin = c(1, 2) and a is a list.

To understand better what is happening, let’s try when the list argument to mysum() has length 2 .

margin = c(1, 2) is interpreted by unaryapply_byname() as “use margin = 1 for the first m in the list, and use margin = 2 for the second m in the list.

Now we see why passing margin = c(1, 2) failed for a list of length 3 ( list(m, m, m) ): unaryapply_byname() applied margin = 1 for the first m , margin = 2 for the second m . But the third m had no margin available for it.

We also see why passing margin = c(1, 2) was successful for a list of length 2 ( list(m, m) ): unaryapply_byname() applied margin = 1 for the first m , margin = 2 for the second m . In that case, we had exactly as many items in margin (2) as items in the list passed to a (2).

Now that we understand the problem, how do we fix it? In other words, how can we apply margin = c(1, 2) to all entries in list(m, m, m) ? Or, better yet, how could we apply margin = 1 to the first m , margin = 2 to the second m , and margin = c(1, 2) to the third m ?

Fixes to the problem identified above can be provided by either the caller or (partially) by the programmer in three ways:

• wrap vector arguments in a list (a caller fix),
• use the prep_vector_arg() function (a programmer fix), and
• use a data frame (a caller fix).

Wrap vector arguments in a list

If the caller is more specific, flexibility is gained. By wrapping c(1, 2) in a list() , the caller indicates “Take this margin ( c(1, 2) ), replicate it as many times as we have items in our a list, using one c(1, 2) for each item in the list.”

The caller can also supply different margin s for each item in the list of matrices.

But the caller must provide either 1 or length(a) items in the margin argument, else an error is emitted.

Use the prep_vector_arg() function

To the extent possible, programmers should remove burdens on users of their functions. So, it would be helpful if there were a way to automatically wrap vector arguments in lists. To that end, matsbyname includes the prep_vector_arg() function. prep_vector_arg() uses heuristics to wrap vector arguments in lists, if needed and when possible.

mysum2() demonstrates the use of prep_vector_arg() .

• argument a is a list,
• the vector argument (in this case margin ) is not a list, and
• the vector argument’s length is greater than 1 but not equal to the length of a,

then prep_vector_arg() wraps the vector argument (in this case margin ) in a list() , thereby relieving the caller of having to remember to make it into a list .

Note that if the length of the vector argument is equal to the length of the list in a , the caller’s intention is ambiguous, and the vector argument is passed without modification.

If the caller wants c(1, 2) to be applied to each item in the a list, the caller must wrap c(1, 2) in a list.

Use a data frame

The reason prep_vector_arg() cannot always wrap vector arguments in a list is that data frame columns are extracted as vectors when they are atomic.

It would be a mistake to wrap DF2$margin in a list() for the following call to mysum2 , because the caller’s intent is clearly “apply margin = 1 for the first row and margin = 2 for the second row.

The good news is that within the context of a data frame, the caller’s intent is unambiguous.

Dealing with vector arguments to the various *apply_byname() functions can be tricky. But there are three ways to solve any problems that arise:

This vignette illustrated all three fixes.

How to vectorize only one argument in function call

Say I have a function that accepts several vectors f(a,b,c) , but I have a vector of inputs for one of the arguments a . Can I call f like f(.a,b,c) such that f will vectorize only over a . Since if I call f.(a,b,c) f vectorizes over a , b , and c and returns nonsense.

f.(a,Ref(b),Ref(c))

You can protect arguments against broadcasting by wrapping them in a container. You should probably use Ref or a tuple, like this:

You could even use a vector:

though that would be less efficient.

When you wrap it in an outer container, broadcasting happens over the outer layer, leaving the contents as is.

If b and c are scalars, broadcast works the way you hope:

If one is a vector and you need to explicity treat it as a scalar, you can wrap it in a Ref

Why is it less efficient to wrap it in a vector?

A vector allocates memory on the heap with a pointer to your array, and must eventually be garbage collected. It’s not so much, but it’s an unnecessary waste that can sometimes grow into a significant cost if it happens often enough, or which may stop some compiler optimizations from happening.

Wrapping it in, say, a tuple, is essentially zero-cost.

This is one area in which I wish I could use JAX’s notation for vmap i.e. vmap(f)(a, b, c) which by default broadcasts f over the first (axis of the first) input, or explicitly I could do vmap(f, (0, 1, None))(a, b, c) which broadcasts f over the first axis of a , the second axis of b , and doesn’t broadcast over c at all.

How do you designate broadcasting over all axes of an argument?

That’s actually restriction of JAX: you need to write one vmap per dimension of array to map over.

For my usecase, I actually wrote a helper function called antivmap which acts as a vmap over all but the specified axes and I’ve found it super useful