Creates a new BPath object that represents the path that's created from the arguments. See the analogous SetTo() functions for descriptions of the flavorful constructors.

• The default constructor does nothing; it should be followed by a call to SetTo().

• The copy constructor makes a copy of the argument's pathname.

The constructor automatically allocates memory for the object's stored pathname. The memory is freed when the object is deleted.

To check to see if an initialization was successful, call InitCheck().

Frees the object's pathname storage and extinguishes the object.

Appends the pathname given by path to the object's current pathname. path must be relative. If normalize is true, the new pathname is normalized; otherwise, it's normalized only if necessary.

Note that this…

Append("subdir/file")

…is the same as (and is implemented as):

path.SetTo(path.Path(), "subdir/file");

The Append() return value is picked up from the SetTo() call.

See SetTo() for other return values.

Initializes the argument with the pathname to the parent directory of this. Destructive parenting is acceptable (sociologically, it's a given):

BPath path("/boot/lbj/fido");

path.GetParent(&path);

Other details…

• GetParent() makes a call to SetTo(), but it's guaranteed not to tickle the normalization machine.

• You can't get the parent of "/".

If the initialization isn't successful, the argument's InitCheck() is set to B_NO_INIT.

Returns the status of the most recent construction or SetTo() call.

These functions return the object's full path and leaf name, respectively. For example:

BPath path("/boot/lbj/fido");
printf("Path: %sn", path.Path());
printf("Leaf: %sn", path.Leaf());

Produces…

$ Path: /boot/lbj/fido
$ Leaf: fido

In both cases, the returned pointers belong to the BPath object. When the BPath is deleted, the pointers go with it.

If the BPath isn't initialized, the functions return pointers to NULL.

The SetTo() function frees the pathname that the object currently holds, and re-initializes the object according to the arguments:

• The first version concatenates the path and leaf strings (interposing a "/" if necessary). If path is relative, the concatenated pathname is appended to the current working directory. Note that you don't have to split your pathname into two parts to call this constructor; the optional leaf argument is provided simply as a convenience.

• The second version performs a similar operation using the path of the BDirectory as the initial part of the pathname.

• The third version initilizes the object with the path and name of the entry.

Regarding the leaf argument:

• The leaf string can contain directories—it needn't be just a leaf name.

• However, leaf must be a relative pathname (it can't start with "/").

If set to true, the normalize argument tells the object to normalize the new pathname. By default (false), the pathname is normalized only if necessary. Note that the default doesn't mean that the object absolutely won't normalize, it just won't do it if it doesn't think it's necessary. See "Initializing and Normalizing" for the full story on normalizing a pathname, including the conditions that trigger default normalization. Normalizing has no meaning with the BEntry version of SetTo().

Storage for the pathname is allocated by the BPath object and is freed when the object is deleted (or when you re-initialize through SetTo()). The path and leaf arguments are copied into the allocated storage.

Other details…

• Destructive setting is safe:

  /* This works... */
  path.SetTo(path.Path(), ...);

• Currently, SetTo() only checks pathname and filename length if it has to normalize.

Unset() frees the object's pathname storage and sets the InitCheck() value to B_NO_INIT.

The return value is also recorded in InitCheck().

The following functions are implemented in accordance with the rules set down by the BFlattenable class. You never need to invoke these functions directly; they're implemented so a BPath can added to a BMessage (see "Passing a BPath in a BMessage"). But in case you're interested…

Returns true if code is B_REF_TYPE, and false otherwise.

Converts the object's pathname to an entry_ref and writes it into buffer. Currently, size is ignored.

Returns the size of the entry_ref that represents the flattened pathname.

Returns false.

Returns B_REF_TYPE.

Initializes the BPath with the flattened entry_ref data that's found in buffer. The type code must be B_REF_TYPE.

The Unflatten() return value is recorded in InitCheck().

Initializes this with a copy of the pathname that's gotten from the argument. Also sets InitCheck().

Compares this's pathname with the pathname taken from the argument. The comparison is a simple strcmp(); neither path is normalized or otherwise altered before the comparison is made. For example:

BPath path("/boot/lbj/fido");

chdir("/boot");
printf("Are they equal? %dn", path == "lbj/fido");

Displays:

$ Are they equal? 0